Operations related to inventory
Merchant API v2 (2.0.0)
The Merchant API v2 provides programmatic access to merchant data across all their sales channels.
This version shifts from sales channel-scoped access to merchant-scoped access, allowing access to data across all sales channels owned by a single merchant.
The access tokens remain the same as in v1, but now they provide access to all sales channels.
All endpoints are rate limited to 100 requests per minute per merchant. The following headers are included in every response:
X-Rate-Limit-Used: The number of requests used in the current minute.X-Rate-Limit-Max: The maximum number of requests allowed per minute (100). If the limit is exceeded, a 429 Too Many Requests response is returned.
v1 of the Merchant API will remain available as long as clients use it, but new features and improvements will only be added to v2. We recommend all new integrations use v2.
All list endpoints use cursor-based pagination. The pagination.next_page_url field in the response indicates the next page. If null, there are no more results. Use the limit query parameter to control page size. See each endpoint's response schema for details.
Hive sends webhook notifications to inform you about important events in your merchant account. Configure webhook endpoints in your merchant dashboard. See the webhooks section below for available webhook events and their payloads.
Hive signs all webhook requests with an x-hive-signature header to prevent malicious actors from sending invalid requests. This header contains a hex-encoded HMAC-SHA256 digest of the request body, using your API token as the key. Requests without this header or with invalid signatures should be ignored.
Ruby signature validation example:
def request_valid?(req)
return false if !req.post?
request_sig = req.get_header("x-hive-signature")
expected_sig = OpenSSL::HMAC.hexdigest("sha256", ENV["API_TOKEN"], req.body)
Rack::Utils.secure_compare(request_sig, expected_sig)
endWebhook URLs should be idempotent as Hive cannot guarantee the order of calls or retry attempts for the same event. What this means in practice, is that you should check the timestamp of the object in the payload. Ignore payloads with a timestamp older than the last update you saved. Only process the webhook if the updated timestamp is newer than the one you have on file.
Download OpenAPI description
Overview
URL
Hive Support
Languages
Servers
Mock server
https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/
Production API
https://app.hive.app/merchant_api/v2/
Staging API
https://staging.app.hive.app/merchant_api/v2/
- Mock serverhttps://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/orders
- Production APIhttps://app.hive.app/merchant_api/v2/orders
- Staging APIhttps://staging.app.hive.app/merchant_api/v2/orders
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/orders?sales_channel_id%5Bin%5D=0&limit=20&created_at%5Bgt%5D=2019-08-24T14%3A15%3A22Z&created_at%5Blt%5D=2019-08-24T14%3A15%3A22Z&created_at%5Bgte%5D=2019-08-24T14%3A15%3A22Z&created_at%5Blte%5D=2019-08-24T14%3A15%3A22Z' \
-H 'Authorization: Bearer <YOUR_token_HERE>'Response
application/json
{ "data": [ { … } ], "pagination": { "first_page_url": "https://app.hive.app/merchant_api/v2/collection_of_items?limit=20", "limit": 20, "next_page_url": "https://app.hive.app/merchant_api/v2/collection_of_items?limit=20&page=eyJpZCI6MTIzNDU2fQ" } }
Bodyapplication/jsonrequired
3-letter ISO 4217 currency code. Examples: EUR, USD, GBP, JPY
The order number which your customer sees. In case this is not the same as merchant_order_id.
When the order was originally created/placed by the customer. This can be different from created_at when doing bulk imports or when there's a delay between order placement and API submission.
Financial status of this order. Possible values:
- failed: Payment failed
- paid: Payment completed successfully
- pending: Payment is pending
- refunded: Payment has been refunded
Enum"failed""paid""pending""refunded"
List of items in the order (see OrderItem)
Any of:
Identifier for the line item. Needs to be unique among the line items of the order.
The discounted price per unit of this item
An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.
Any of:
2-letter ISO 3166-1 country code. Examples: DE, US, FR, NL
Customer's first name - required if last_name and full_name are omitted
Customer's full name - required if first_name and last_name are omitted
Customer's last name - required if first_name and full_name are omitted
Parcel point ID - see Sendcloud service points
State or province code. For US addresses, this should be the 2-letter state code (e.g., CA, NY, TX). For other countries, this should be the appropriate province/state/region code. Examples: CA (California), NY (New York), ON (Ontario), BE (Berlin)
- Mock serverhttps://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/orders
- Production APIhttps://app.hive.app/merchant_api/v2/orders
- Staging APIhttps://staging.app.hive.app/merchant_api/v2/orders
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/orders \
-H 'Authorization: Bearer <YOUR_token_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"items": [
{
"merchant_item_id": "1",
"price_per_unit_in_cents": 1500,
"quantity": 2,
"sku_code": "SKU-001",
"sku_id": 1001
}
],
"merchant_order_id": "ORD-1001",
"sales_channel_id": 10,
"shipping_address": {
"city": "Berlin",
"country_code": "DE",
"first_name": "Anna",
"line1": "Alexanderplatz 1",
"postal_code": "10178"
},
"currency": "EUR",
"payment_method": "credit_card",
"tags": [
"priority",
"gift"
],
"total_price_in_cents": 3000,
"total_tax_in_cents": 570,
"total_net_revenue_in_cents": 2430,
"total_net_refunds_in_cents": 0,
"total_tax_refunds_in_cents": 0,
"custom_metadata": {
"gift_message": "Happy Birthday!"
},
"customer_order_number": "CUST-ORD-2023-01",
"carrier_preference": "DHL",
"external_created_at": "2023-10-01T10:30:00Z"
}'Order created successfully
When the order was created. Will default to current time if omitted.
3-letter ISO 4217 currency code. Examples: EUR, USD, GBP, JPY
The order number which your customer sees. In case this is not the same as merchant_order_id.
When the order was originally created/placed by the customer. This can be different from created_at when doing bulk imports or when there's a delay between order placement and API submission.
Financial status of this order. Possible values:
- failed: Payment failed
- paid: Payment completed successfully
- pending: Payment is pending
- refunded: Payment has been refunded
Enum"failed""paid""pending""refunded"
List of items in the order (see OrderItem)
Any of:
Identifier for the line item. Needs to be unique among the line items of the order.
The discounted price per unit of this item
An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.
Any of:
2-letter ISO 3166-1 country code. Examples: DE, US, FR, NL
Customer's first name - required if last_name and full_name are omitted
Customer's full name - required if first_name and last_name are omitted
Customer's last name - required if first_name and full_name are omitted
Parcel point ID - see Sendcloud service points
State or province code. For US addresses, this should be the 2-letter state code (e.g., CA, NY, TX). For other countries, this should be the appropriate province/state/region code. Examples: CA (California), NY (New York), ON (Ontario), BE (Berlin)
Current fulfillment status of the order within Hive's fulfillment process. This tracks the order's progress from confirmation through delivery. Possible values:
- waiting_for_picking: Order is confirmed and waiting to be picked in the fulfillment center
- processing: Order is actively being processed (picked/packed) in the fulfillment center
- partially_shipped: Some items from the order have been shipped, but others are still pending
- shipped: All items from the order have been shipped
- on_hold: Order is temporarily paused (e.g., payment issues, merchant request)
- payment_pending: Order is waiting for payment confirmation
- cancelled: Order has been cancelled
- ignored: Order will not be fulfilled (automatically set based on external conditions)
Note: This field is read-only and managed entirely by Hive based on the fulfillment process.
Enum"waiting_for_picking""processing""partially_shipped""shipped""on_hold""payment_pending""cancelled""ignored"
Net refunds in cents (total refunded minus taxes)
Response
application/json
{ "id": 123456, "items": [ { … } ], "merchant_order_id": "ORD-1001", "sales_channel_id": 10, "shipping_address": { "city": "Berlin", "country_code": "DE", "first_name": "Anna", "line1": "Alexanderplatz 1", "postal_code": "10178" }, "fulfillment_status": "waiting_for_picking", "financial_status": "paid", "created_at": "2023-10-01T12:00:00Z", "currency": "EUR", "payment_method": "credit_card", "tags": [ "priority", "gift" ], "total_price_in_cents": 3000, "total_tax_in_cents": 570, "total_net_revenue_in_cents": 2430, "total_net_refunds_in_cents": 0, "total_tax_refunds_in_cents": 0, "custom_metadata": { "gift_message": "Happy Birthday!" }, "customer_order_number": "CUST-ORD-2023-01", "carrier_preference": "DHL", "external_created_at": "2023-10-01T10:30:00Z", "updated_at": "2023-10-01T14:30:00Z" }
- Mock serverhttps://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/orders/{id}
- Production APIhttps://app.hive.app/merchant_api/v2/orders/{id}
- Staging APIhttps://staging.app.hive.app/merchant_api/v2/orders/{id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/orders/{id}' \
-H 'Authorization: Bearer <YOUR_token_HERE>'An order
When the order was created. Will default to current time if omitted.
3-letter ISO 4217 currency code. Examples: EUR, USD, GBP, JPY
The order number which your customer sees. In case this is not the same as merchant_order_id.
When the order was originally created/placed by the customer. This can be different from created_at when doing bulk imports or when there's a delay between order placement and API submission.
Financial status of this order. Possible values:
- failed: Payment failed
- paid: Payment completed successfully
- pending: Payment is pending
- refunded: Payment has been refunded
Enum"failed""paid""pending""refunded"
List of items in the order (see OrderItem)
Any of:
Identifier for the line item. Needs to be unique among the line items of the order.
The discounted price per unit of this item
An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.
Any of:
2-letter ISO 3166-1 country code. Examples: DE, US, FR, NL
Customer's first name - required if last_name and full_name are omitted
Customer's full name - required if first_name and last_name are omitted
Customer's last name - required if first_name and full_name are omitted
Parcel point ID - see Sendcloud service points
State or province code. For US addresses, this should be the 2-letter state code (e.g., CA, NY, TX). For other countries, this should be the appropriate province/state/region code. Examples: CA (California), NY (New York), ON (Ontario), BE (Berlin)
Current fulfillment status of the order within Hive's fulfillment process. This tracks the order's progress from confirmation through delivery. Possible values:
- waiting_for_picking: Order is confirmed and waiting to be picked in the fulfillment center
- processing: Order is actively being processed (picked/packed) in the fulfillment center
- partially_shipped: Some items from the order have been shipped, but others are still pending
- shipped: All items from the order have been shipped
- on_hold: Order is temporarily paused (e.g., payment issues, merchant request)
- payment_pending: Order is waiting for payment confirmation
- cancelled: Order has been cancelled
- ignored: Order will not be fulfilled (automatically set based on external conditions)
Note: This field is read-only and managed entirely by Hive based on the fulfillment process.
Enum"waiting_for_picking""processing""partially_shipped""shipped""on_hold""payment_pending""cancelled""ignored"
Net refunds in cents (total refunded minus taxes)
Response
application/json
{ "id": 123456, "items": [ { … } ], "merchant_order_id": "ORD-1001", "sales_channel_id": 10, "shipping_address": { "city": "Berlin", "country_code": "DE", "first_name": "Anna", "line1": "Alexanderplatz 1", "postal_code": "10178" }, "fulfillment_status": "waiting_for_picking", "financial_status": "paid", "created_at": "2023-10-01T12:00:00Z", "currency": "EUR", "payment_method": "credit_card", "tags": [ "priority", "gift" ], "total_price_in_cents": 3000, "total_tax_in_cents": 570, "total_net_revenue_in_cents": 2430, "total_net_refunds_in_cents": 0, "total_tax_refunds_in_cents": 0, "custom_metadata": { "gift_message": "Happy Birthday!" }, "customer_order_number": "CUST-ORD-2023-01", "carrier_preference": "DHL", "external_created_at": "2023-10-01T10:30:00Z", "updated_at": "2023-10-01T14:30:00Z" }
Bodyapplication/json
3-letter ISO 4217 currency code. Examples: EUR, USD, GBP, JPY
The order number which your customer sees. In case this is not the same as merchant_order_id.
When the order was originally created/placed by the customer. This can be different from created_at when doing bulk imports or when there's a delay between order placement and API submission.
Financial status of this order. Possible values:
- failed: Payment failed
- paid: Payment completed successfully
- pending: Payment is pending
- refunded: Payment has been refunded
Enum"failed""paid""pending""refunded"
- Mock serverhttps://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/orders/{id}
- Production APIhttps://app.hive.app/merchant_api/v2/orders/{id}
- Staging APIhttps://staging.app.hive.app/merchant_api/v2/orders/{id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PATCH \
'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/orders/{id}' \
-H 'Authorization: Bearer <YOUR_token_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"carrier_preference": "PostNL"
}'Order updated successfully
When the order was created. Will default to current time if omitted.
3-letter ISO 4217 currency code. Examples: EUR, USD, GBP, JPY
The order number which your customer sees. In case this is not the same as merchant_order_id.
When the order was originally created/placed by the customer. This can be different from created_at when doing bulk imports or when there's a delay between order placement and API submission.
Financial status of this order. Possible values:
- failed: Payment failed
- paid: Payment completed successfully
- pending: Payment is pending
- refunded: Payment has been refunded
Enum"failed""paid""pending""refunded"
List of items in the order (see OrderItem)
Any of:
Identifier for the line item. Needs to be unique among the line items of the order.
The discounted price per unit of this item
An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.
Any of:
2-letter ISO 3166-1 country code. Examples: DE, US, FR, NL
Customer's first name - required if last_name and full_name are omitted
Customer's full name - required if first_name and last_name are omitted
Customer's last name - required if first_name and full_name are omitted
Parcel point ID - see Sendcloud service points
State or province code. For US addresses, this should be the 2-letter state code (e.g., CA, NY, TX). For other countries, this should be the appropriate province/state/region code. Examples: CA (California), NY (New York), ON (Ontario), BE (Berlin)
Current fulfillment status of the order within Hive's fulfillment process. This tracks the order's progress from confirmation through delivery. Possible values:
- waiting_for_picking: Order is confirmed and waiting to be picked in the fulfillment center
- processing: Order is actively being processed (picked/packed) in the fulfillment center
- partially_shipped: Some items from the order have been shipped, but others are still pending
- shipped: All items from the order have been shipped
- on_hold: Order is temporarily paused (e.g., payment issues, merchant request)
- payment_pending: Order is waiting for payment confirmation
- cancelled: Order has been cancelled
- ignored: Order will not be fulfilled (automatically set based on external conditions)
Note: This field is read-only and managed entirely by Hive based on the fulfillment process.
Enum"waiting_for_picking""processing""partially_shipped""shipped""on_hold""payment_pending""cancelled""ignored"
Net refunds in cents (total refunded minus taxes)
Response
application/json
{ "id": 123456, "items": [ { … } ], "merchant_order_id": "ORD-1001", "sales_channel_id": 10, "shipping_address": { "city": "Berlin", "country_code": "DE", "first_name": "Anna", "line1": "Alexanderplatz 1", "postal_code": "10178" }, "fulfillment_status": "shipped", "financial_status": "paid", "created_at": "2023-10-01T12:00:00Z", "currency": "EUR", "payment_method": "credit_card", "tags": [ "priority", "gift" ], "total_price_in_cents": 3000, "total_tax_in_cents": 570, "total_net_revenue_in_cents": 2430, "total_net_refunds_in_cents": 0, "total_tax_refunds_in_cents": 0, "custom_metadata": { "gift_message": "Happy Birthday!" }, "customer_order_number": "CUST-ORD-2023-01", "carrier_preference": "PostNL", "updated_at": "2023-10-01T15:30:00Z" }
- Mock serverhttps://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/orders/{id}/cancel
- Production APIhttps://app.hive.app/merchant_api/v2/orders/{id}/cancel
- Staging APIhttps://staging.app.hive.app/merchant_api/v2/orders/{id}/cancel
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/orders/{id}/cancel' \
-H 'Authorization: Bearer <YOUR_token_HERE>'Order cancelled successfully
When the order was created. Will default to current time if omitted.
3-letter ISO 4217 currency code. Examples: EUR, USD, GBP, JPY
The order number which your customer sees. In case this is not the same as merchant_order_id.
When the order was originally created/placed by the customer. This can be different from created_at when doing bulk imports or when there's a delay between order placement and API submission.
Financial status of this order. Possible values:
- failed: Payment failed
- paid: Payment completed successfully
- pending: Payment is pending
- refunded: Payment has been refunded
Enum"failed""paid""pending""refunded"
List of items in the order (see OrderItem)
Any of:
Identifier for the line item. Needs to be unique among the line items of the order.
The discounted price per unit of this item
An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.
Any of:
2-letter ISO 3166-1 country code. Examples: DE, US, FR, NL
Customer's first name - required if last_name and full_name are omitted
Customer's full name - required if first_name and last_name are omitted
Customer's last name - required if first_name and full_name are omitted
Parcel point ID - see Sendcloud service points
State or province code. For US addresses, this should be the 2-letter state code (e.g., CA, NY, TX). For other countries, this should be the appropriate province/state/region code. Examples: CA (California), NY (New York), ON (Ontario), BE (Berlin)
Current fulfillment status of the order within Hive's fulfillment process. This tracks the order's progress from confirmation through delivery. Possible values:
- waiting_for_picking: Order is confirmed and waiting to be picked in the fulfillment center
- processing: Order is actively being processed (picked/packed) in the fulfillment center
- partially_shipped: Some items from the order have been shipped, but others are still pending
- shipped: All items from the order have been shipped
- on_hold: Order is temporarily paused (e.g., payment issues, merchant request)
- payment_pending: Order is waiting for payment confirmation
- cancelled: Order has been cancelled
- ignored: Order will not be fulfilled (automatically set based on external conditions)
Note: This field is read-only and managed entirely by Hive based on the fulfillment process.
Enum"waiting_for_picking""processing""partially_shipped""shipped""on_hold""payment_pending""cancelled""ignored"
Net refunds in cents (total refunded minus taxes)
Response
application/json
{ "id": 123456, "items": [ { … } ], "merchant_order_id": "ORD-1001", "sales_channel_id": 10, "shipping_address": { "city": "Berlin", "country_code": "DE", "first_name": "Anna", "line1": "Alexanderplatz 1", "postal_code": "10178" }, "fulfillment_status": "waiting_for_picking", "financial_status": "paid", "created_at": "2023-10-01T12:00:00Z", "currency": "EUR", "payment_method": "credit_card", "tags": [ "priority", "gift" ], "total_price_in_cents": 3000, "total_tax_in_cents": 570, "total_net_revenue_in_cents": 2430, "total_net_refunds_in_cents": 0, "total_tax_refunds_in_cents": 0, "custom_metadata": { "gift_message": "Happy Birthday!" }, "customer_order_number": "CUST-ORD-2023-01", "carrier_preference": "DHL", "external_created_at": "2023-10-01T10:30:00Z", "updated_at": "2023-10-01T14:30:00Z" }
- Mock serverhttps://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/orders/by_merchant_order_id
- Production APIhttps://app.hive.app/merchant_api/v2/orders/by_merchant_order_id
- Staging APIhttps://staging.app.hive.app/merchant_api/v2/orders/by_merchant_order_id
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/orders/by_merchant_order_id?sales_channel_id=0&merchant_order_id=string' \
-H 'Authorization: Bearer <YOUR_token_HERE>'An order
When the order was created. Will default to current time if omitted.
3-letter ISO 4217 currency code. Examples: EUR, USD, GBP, JPY
The order number which your customer sees. In case this is not the same as merchant_order_id.
When the order was originally created/placed by the customer. This can be different from created_at when doing bulk imports or when there's a delay between order placement and API submission.
Financial status of this order. Possible values:
- failed: Payment failed
- paid: Payment completed successfully
- pending: Payment is pending
- refunded: Payment has been refunded
Enum"failed""paid""pending""refunded"
List of items in the order (see OrderItem)
Any of:
Identifier for the line item. Needs to be unique among the line items of the order.
The discounted price per unit of this item
An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.
Any of:
2-letter ISO 3166-1 country code. Examples: DE, US, FR, NL
Customer's first name - required if last_name and full_name are omitted
Customer's full name - required if first_name and last_name are omitted
Customer's last name - required if first_name and full_name are omitted
Parcel point ID - see Sendcloud service points
State or province code. For US addresses, this should be the 2-letter state code (e.g., CA, NY, TX). For other countries, this should be the appropriate province/state/region code. Examples: CA (California), NY (New York), ON (Ontario), BE (Berlin)
Current fulfillment status of the order within Hive's fulfillment process. This tracks the order's progress from confirmation through delivery. Possible values:
- waiting_for_picking: Order is confirmed and waiting to be picked in the fulfillment center
- processing: Order is actively being processed (picked/packed) in the fulfillment center
- partially_shipped: Some items from the order have been shipped, but others are still pending
- shipped: All items from the order have been shipped
- on_hold: Order is temporarily paused (e.g., payment issues, merchant request)
- payment_pending: Order is waiting for payment confirmation
- cancelled: Order has been cancelled
- ignored: Order will not be fulfilled (automatically set based on external conditions)
Note: This field is read-only and managed entirely by Hive based on the fulfillment process.
Enum"waiting_for_picking""processing""partially_shipped""shipped""on_hold""payment_pending""cancelled""ignored"
Net refunds in cents (total refunded minus taxes)
Response
application/json
{ "id": 123456, "items": [ { … } ], "merchant_order_id": "ORD-1001", "sales_channel_id": 10, "shipping_address": { "city": "Berlin", "country_code": "DE", "first_name": "Anna", "line1": "Alexanderplatz 1", "postal_code": "10178" }, "fulfillment_status": "waiting_for_picking", "financial_status": "paid", "created_at": "2023-10-01T12:00:00Z", "currency": "EUR", "payment_method": "credit_card", "tags": [ "priority", "gift" ], "total_price_in_cents": 3000, "total_tax_in_cents": 570, "total_net_revenue_in_cents": 2430, "total_net_refunds_in_cents": 0, "total_tax_refunds_in_cents": 0, "custom_metadata": { "gift_message": "Happy Birthday!" }, "customer_order_number": "CUST-ORD-2023-01", "carrier_preference": "DHL", "external_created_at": "2023-10-01T10:30:00Z", "updated_at": "2023-10-01T14:30:00Z" }
Bodyapplication/json
3-letter ISO 4217 currency code. Examples: EUR, USD, GBP, JPY
The order number which your customer sees. In case this is not the same as merchant_order_id.
When the order was originally created/placed by the customer. This can be different from created_at when doing bulk imports or when there's a delay between order placement and API submission.
Financial status of this order. Possible values:
- failed: Payment failed
- paid: Payment completed successfully
- pending: Payment is pending
- refunded: Payment has been refunded
Enum"failed""paid""pending""refunded"
- Mock serverhttps://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/orders/by_merchant_order_id
- Production APIhttps://app.hive.app/merchant_api/v2/orders/by_merchant_order_id
- Staging APIhttps://staging.app.hive.app/merchant_api/v2/orders/by_merchant_order_id
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PATCH \
'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/orders/by_merchant_order_id?sales_channel_id=0&merchant_order_id=string' \
-H 'Authorization: Bearer <YOUR_token_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"items": [
{
"merchant_item_id": "1",
"price_per_unit_in_cents": 1500,
"quantity": 2,
"sku_code": "SKU-001",
"sku_id": 1001
}
],
"shipping_address": {
"city": "Berlin",
"country_code": "DE",
"first_name": "Anna",
"line1": "Alexanderplatz 1",
"postal_code": "10178"
},
"currency": "EUR",
"payment_method": "credit_card",
"tags": [
"priority",
"gift"
],
"total_price_in_cents": 3000,
"total_tax_in_cents": 570,
"total_net_revenue_in_cents": 2430,
"total_net_refunds_in_cents": 0,
"total_tax_refunds_in_cents": 0,
"custom_metadata": {
"gift_message": "Happy Birthday!"
},
"customer_order_number": "CUST-ORD-2023-01",
"carrier_preference": "DHL"
}'Order updated successfully
When the order was created. Will default to current time if omitted.
3-letter ISO 4217 currency code. Examples: EUR, USD, GBP, JPY
The order number which your customer sees. In case this is not the same as merchant_order_id.
When the order was originally created/placed by the customer. This can be different from created_at when doing bulk imports or when there's a delay between order placement and API submission.
Financial status of this order. Possible values:
- failed: Payment failed
- paid: Payment completed successfully
- pending: Payment is pending
- refunded: Payment has been refunded
Enum"failed""paid""pending""refunded"
List of items in the order (see OrderItem)
Any of:
Identifier for the line item. Needs to be unique among the line items of the order.
The discounted price per unit of this item
An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.
Any of:
2-letter ISO 3166-1 country code. Examples: DE, US, FR, NL
Customer's first name - required if last_name and full_name are omitted
Customer's full name - required if first_name and last_name are omitted
Customer's last name - required if first_name and full_name are omitted
Parcel point ID - see Sendcloud service points
State or province code. For US addresses, this should be the 2-letter state code (e.g., CA, NY, TX). For other countries, this should be the appropriate province/state/region code. Examples: CA (California), NY (New York), ON (Ontario), BE (Berlin)
Current fulfillment status of the order within Hive's fulfillment process. This tracks the order's progress from confirmation through delivery. Possible values:
- waiting_for_picking: Order is confirmed and waiting to be picked in the fulfillment center
- processing: Order is actively being processed (picked/packed) in the fulfillment center
- partially_shipped: Some items from the order have been shipped, but others are still pending
- shipped: All items from the order have been shipped
- on_hold: Order is temporarily paused (e.g., payment issues, merchant request)
- payment_pending: Order is waiting for payment confirmation
- cancelled: Order has been cancelled
- ignored: Order will not be fulfilled (automatically set based on external conditions)
Note: This field is read-only and managed entirely by Hive based on the fulfillment process.
Enum"waiting_for_picking""processing""partially_shipped""shipped""on_hold""payment_pending""cancelled""ignored"
Net refunds in cents (total refunded minus taxes)
Response
application/json
{ "id": 123456, "items": [ { … } ], "merchant_order_id": "ORD-1001", "sales_channel_id": 10, "shipping_address": { "city": "Berlin", "country_code": "DE", "first_name": "Anna", "line1": "Alexanderplatz 1", "postal_code": "10178" }, "fulfillment_status": "waiting_for_picking", "financial_status": "paid", "created_at": "2023-10-01T12:00:00Z", "currency": "EUR", "payment_method": "credit_card", "tags": [ "priority", "gift" ], "total_price_in_cents": 3000, "total_tax_in_cents": 570, "total_net_revenue_in_cents": 2430, "total_net_refunds_in_cents": 0, "total_tax_refunds_in_cents": 0, "custom_metadata": { "gift_message": "Happy Birthday!" }, "customer_order_number": "CUST-ORD-2023-01", "carrier_preference": "DHL", "external_created_at": "2023-10-01T10:30:00Z", "updated_at": "2023-10-01T14:30:00Z" }
Bodyapplication/json
The preferred carrier to use for delivering this order
When the order was created. Will default to current time if omitted.
3-letter ISO 4217 currency code. Examples: EUR, USD, GBP, JPY
The order number which your customer sees. In case this is not the same as merchant_order_id.
When the order was originally created/placed by the customer. This can be different from created_at when doing bulk imports or when there's a delay between order placement and API submission.
Financial status of this order. Possible values:
- failed: Payment failed
- paid: Payment completed successfully
- pending: Payment is pending
- refunded: Payment has been refunded
Enum"failed""paid""pending""refunded"
List of items in the order (see OrderItem)
Any of:
Identifier for the line item. Needs to be unique among the line items of the order.
The discounted price per unit of this item
An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.
Any of:
2-letter ISO 3166-1 country code. Examples: DE, US, FR, NL
Customer's first name - required if last_name and full_name are omitted
Customer's full name - required if first_name and last_name are omitted
Customer's last name - required if first_name and full_name are omitted
Parcel point ID - see Sendcloud service points
State or province code. For US addresses, this should be the 2-letter state code (e.g., CA, NY, TX). For other countries, this should be the appropriate province/state/region code. Examples: CA (California), NY (New York), ON (Ontario), BE (Berlin)
Current fulfillment status of the order within Hive's fulfillment process. This tracks the order's progress from confirmation through delivery. Possible values:
- waiting_for_picking: Order is confirmed and waiting to be picked in the fulfillment center
- processing: Order is actively being processed (picked/packed) in the fulfillment center
- partially_shipped: Some items from the order have been shipped, but others are still pending
- shipped: All items from the order have been shipped
- on_hold: Order is temporarily paused (e.g., payment issues, merchant request)
- payment_pending: Order is waiting for payment confirmation
- cancelled: Order has been cancelled
- ignored: Order will not be fulfilled (automatically set based on external conditions)
Note: This field is read-only and managed entirely by Hive based on the fulfillment process.
Enum"waiting_for_picking""processing""partially_shipped""shipped""on_hold""payment_pending""cancelled""ignored"
Net refunds in cents (total refunded minus taxes)
Net revenue in cents (amount paid minus taxes)
Total tax in the refunded amount in cents
- Mock serverhttps://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/order.status_updated
- Production APIhttps://app.hive.app/merchant_api/v2/order.status_updated
- Staging APIhttps://staging.app.hive.app/merchant_api/v2/order.status_updated
application/json
{ "event_type": "order.status_updated", "event_id": "123e4567-e89b-12d3-a456-426614174000", "timestamp": "2023-10-01T12:00:00Z", "data": { "id": 123456, "merchant_order_id": "ORD-1001", "sales_channel_id": 10, "fulfillment_status": "shipped", "financial_status": "paid", "created_at": "2023-10-01T12:00:00Z", "currency": "EUR", "total_price_in_cents": 3000, "total_net_refunds_in_cents": 0, "total_net_revenue_in_cents": 2430, "total_tax_in_cents": 570, "total_tax_refunds_in_cents": 0, "carrier_preference": "DHL", "updated_at": "2023-10-01T14:30:00Z", "items": [ … ], "shipping_address": { … } } }