Skip to content

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.

Rate Limiting

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.

Versioning and Deprecation Policy

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.

Pagination

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.

Webhooks

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.

Webhook Security

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)
end

Webhook Reliability

Webhook 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
mapi_v2_oas31.json
mapi_v2_oas31.yaml
Overview
URL

https://developers.hive.app

Hive Support

tech.api@hive.app

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/

InventoryTransferOrders

Operations related to inventory transfer orders

OperationsWebhooks

Orders

Operations related to orders

OperationsWebhooks

List orders

Request

Returns all orders across all sales channels belonging to the authenticated merchant.

See the Pagination section in the API overview above for details on how pagination works.

Security
BearerAuth
Query
sales_channel_id[in]Array of integers(int64)

Filter results by one or more sales channel ID

limitinteger[ 1 .. 100 ]

Number of items to return per page (for pagination)

Default 20
created_at[gt]string(date-time)

Filter results created after this date (ISO 8601 format)

created_at[lt]string(date-time)

Filter results created before this date (ISO 8601 format)

created_at[gte]string(date-time)

Filter results created on or after this date (ISO 8601 format)

created_at[lte]string(date-time)

Filter results created on or before this date (ISO 8601 format)

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>'

Responses

A list of orders

Headers
X-Rate-Limit-Usedinteger

The number of requests used in the current minute.

Examples:
10
X-Rate-Limit-Maxinteger

The maximum number of requests allowed per minute (100).

Examples:
100
Bodyapplication/json
dataArray of objects(Order)
paginationobject(Pagination)
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"
  }
}

Create a new order

Request

Creates a new order for a specific sales channel within the merchant's organization.

Security
BearerAuth
Bodyapplication/jsonrequired
carrier_preferencestring or null

The preferred carrier to use for delivering this order

currencystring(CurrencyCode)^[A-Z]{3}$
custom_metadataobject or null

A JSON object with custom metadata

customer_order_numberstring or null

The order number which your customer sees. In case this is not the same as merchant_order_id.

external_created_atstring or null(date-time)

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_statusstring(OrderFinancialStatus)
Enum"failed""paid""pending""refunded"
itemsArray of OrderItem (object)(OrderItem)non-emptyrequired

List of items in the order (see OrderItem)

Any of:
items[].​merchant_item_idstringrequired

Identifier for the line item. Needs to be unique among the line items of the order.

items[].​price_per_unit_in_centsinteger(int32)>= 0

The price per unit of this item

items[].​price_per_unit_in_cents_with_discountinteger(int32)>= 0

The discounted price per unit of this item

items[].​quantityinteger(int32)>= 1required

The quantity of this item in the order

items[].​sku_codestring

The merchant's SKU identifier - required if sku_id is not provided

items[].​sku_idinteger(int64)required

Hive's SKU identifier - required if sku_code is not provided

merchant_order_idstringnon-emptyrequired

An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.

payment_methodstring or null

The payment method used for this order

sales_channel_idinteger(int64)required

The ID of the sales channel this order belongs to

shipping_addressAddress (object)(Address)required
Any of:
shipping_address.​citystringnon-emptyrequired

City name

shipping_address.​companystring or null

Company name

shipping_address.​country_codestring(CountryCode)^[A-Z]{2}$required
shipping_address.​emailstring or null(email)

Email address

shipping_address.​first_namestring or nullnon-emptyrequired

Customer's first name - required if last_name and full_name are omitted

shipping_address.​full_namestring or nullnon-empty

Customer's full name - required if first_name and last_name are omitted

shipping_address.​last_namestring or nullnon-empty

Customer's last name - required if first_name and full_name are omitted

shipping_address.​line1stringnon-emptyrequired

Customer's address line 1

shipping_address.​line2string or null

Customer's address line 2

shipping_address.​parcel_point_idstring or null

Parcel point ID - see Sendcloud service points

shipping_address.​phonestring or null

Customer's phone number

shipping_address.​postal_codestringnon-emptyrequired

Customer's postal code

shipping_address.​province_or_state_codestring or null

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)

tagsArray of strings or null

String tags for this order

total_net_refunds_in_centsinteger(int32)>= 0

Net refunds in cents (total refunded minus taxes)

total_net_revenue_in_centsinteger(int32)>= 0

Net revenue in cents (amount paid minus taxes)

total_price_in_centsinteger(int32)>= 0

Total price paid in cents

total_tax_in_centsinteger(int32)>= 0

Total tax paid in cents

total_tax_refunds_in_centsinteger(int32)>= 0

Total tax in the refunded amount in cents

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"
  }'

Responses

Order created successfully

Bodyapplication/json
carrier_preferencestring or nullrequired

The preferred carrier to use for delivering this order

created_atstring(date-time)read-onlyrequired

When the order was created. Will default to current time if omitted.

currencystring(CurrencyCode)^[A-Z]{3}$required
custom_metadataobject or null

A JSON object with custom metadata

customer_order_numberstring or null

The order number which your customer sees. In case this is not the same as merchant_order_id.

external_created_atstring or null(date-time)

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_statusstring(OrderFinancialStatus)required
Enum"failed""paid""pending""refunded"
idinteger(int64)read-onlyrequired

Hive's unique identifier for this order

itemsArray of OrderItem (object)(OrderItem)required

List of items in the order (see OrderItem)

Any of:
items[].​merchant_item_idstringrequired

Identifier for the line item. Needs to be unique among the line items of the order.

items[].​price_per_unit_in_centsinteger(int32)>= 0

The price per unit of this item

items[].​price_per_unit_in_cents_with_discountinteger(int32)>= 0

The discounted price per unit of this item

items[].​quantityinteger(int32)>= 1required

The quantity of this item in the order

items[].​sku_codestring

The merchant's SKU identifier - required if sku_id is not provided

items[].​sku_idinteger(int64)required

Hive's SKU identifier - required if sku_code is not provided

merchant_order_idstringrequired

An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.

payment_methodstring or null

The payment method used for this order

sales_channel_idinteger(int64)required

The ID of the sales channel this order belongs to

shipping_addressAddress (object)(Address)required
Any of:
shipping_address.​citystringnon-emptyrequired

City name

shipping_address.​companystring or null

Company name

shipping_address.​country_codestring(CountryCode)^[A-Z]{2}$required
shipping_address.​emailstring or null(email)

Email address

shipping_address.​first_namestring or nullnon-emptyrequired

Customer's first name - required if last_name and full_name are omitted

shipping_address.​full_namestring or nullnon-empty

Customer's full name - required if first_name and last_name are omitted

shipping_address.​last_namestring or nullnon-empty

Customer's last name - required if first_name and full_name are omitted

shipping_address.​line1stringnon-emptyrequired

Customer's address line 1

shipping_address.​line2string or null

Customer's address line 2

shipping_address.​parcel_point_idstring or null

Parcel point ID - see Sendcloud service points

shipping_address.​phonestring or null

Customer's phone number

shipping_address.​postal_codestringnon-emptyrequired

Customer's postal code

shipping_address.​province_or_state_codestring or null

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)

fulfillment_statusstring(OrderFulfillmentStatus)read-onlyrequired
Enum"waiting_for_picking""processing""partially_shipped""shipped""on_hold""payment_pending""cancelled""ignored"
tagsArray of strings or null

String tags for this order

total_net_refunds_in_centsinteger(int32)>= 0required

Net refunds in cents (total refunded minus taxes)

total_net_revenue_in_centsinteger(int32)>= 0required

Net revenue in cents (amount paid minus taxes)

total_price_in_centsinteger(int32)>= 0required

Total price paid in cents

total_tax_in_centsinteger(int32)>= 0required

Total tax paid in cents

total_tax_refunds_in_centsinteger(int32)>= 0required

Total tax in the refunded amount in cents

updated_atstring(date-time)read-onlyrequired

When the order was last updated

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"
}

Get an order

Request

Returns a specific order.

Security
BearerAuth
Path
idinteger(int64)required

Order ID

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>'

Responses

An order

Bodyapplication/json
carrier_preferencestring or nullrequired

The preferred carrier to use for delivering this order

created_atstring(date-time)read-onlyrequired

When the order was created. Will default to current time if omitted.

currencystring(CurrencyCode)^[A-Z]{3}$required
custom_metadataobject or null

A JSON object with custom metadata

customer_order_numberstring or null

The order number which your customer sees. In case this is not the same as merchant_order_id.

external_created_atstring or null(date-time)

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_statusstring(OrderFinancialStatus)required
Enum"failed""paid""pending""refunded"
idinteger(int64)read-onlyrequired

Hive's unique identifier for this order

itemsArray of OrderItem (object)(OrderItem)required

List of items in the order (see OrderItem)

Any of:
items[].​merchant_item_idstringrequired

Identifier for the line item. Needs to be unique among the line items of the order.

items[].​price_per_unit_in_centsinteger(int32)>= 0

The price per unit of this item

items[].​price_per_unit_in_cents_with_discountinteger(int32)>= 0

The discounted price per unit of this item

items[].​quantityinteger(int32)>= 1required

The quantity of this item in the order

items[].​sku_codestring

The merchant's SKU identifier - required if sku_id is not provided

items[].​sku_idinteger(int64)required

Hive's SKU identifier - required if sku_code is not provided

merchant_order_idstringrequired

An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.

payment_methodstring or null

The payment method used for this order

sales_channel_idinteger(int64)required

The ID of the sales channel this order belongs to

shipping_addressAddress (object)(Address)required
Any of:
shipping_address.​citystringnon-emptyrequired

City name

shipping_address.​companystring or null

Company name

shipping_address.​country_codestring(CountryCode)^[A-Z]{2}$required
shipping_address.​emailstring or null(email)

Email address

shipping_address.​first_namestring or nullnon-emptyrequired

Customer's first name - required if last_name and full_name are omitted

shipping_address.​full_namestring or nullnon-empty

Customer's full name - required if first_name and last_name are omitted

shipping_address.​last_namestring or nullnon-empty

Customer's last name - required if first_name and full_name are omitted

shipping_address.​line1stringnon-emptyrequired

Customer's address line 1

shipping_address.​line2string or null

Customer's address line 2

shipping_address.​parcel_point_idstring or null

Parcel point ID - see Sendcloud service points

shipping_address.​phonestring or null

Customer's phone number

shipping_address.​postal_codestringnon-emptyrequired

Customer's postal code

shipping_address.​province_or_state_codestring or null

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)

fulfillment_statusstring(OrderFulfillmentStatus)read-onlyrequired
Enum"waiting_for_picking""processing""partially_shipped""shipped""on_hold""payment_pending""cancelled""ignored"
tagsArray of strings or null

String tags for this order

total_net_refunds_in_centsinteger(int32)>= 0required

Net refunds in cents (total refunded minus taxes)

total_net_revenue_in_centsinteger(int32)>= 0required

Net revenue in cents (amount paid minus taxes)

total_price_in_centsinteger(int32)>= 0required

Total price paid in cents

total_tax_in_centsinteger(int32)>= 0required

Total tax paid in cents

total_tax_refunds_in_centsinteger(int32)>= 0required

Total tax in the refunded amount in cents

updated_atstring(date-time)read-onlyrequired

When the order was last updated

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"
}

Partially update an order

Request

Partially updates an existing order. Only the provided fields will be updated.

Note: The unique identifiers merchant_order_id and sales_channel_id cannot be updated and will be ignored if provided in the request body.

Security
BearerAuth
Path
idinteger(int64)required

Order ID

Bodyapplication/json
carrier_preferencestring or null

The preferred carrier to use for delivering this order

currencystring(CurrencyCode)^[A-Z]{3}$
custom_metadataobject or null

A JSON object with custom metadata

customer_order_numberstring or null

The order number which your customer sees. In case this is not the same as merchant_order_id.

external_created_atstring(date-time)

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_statusstring(OrderFinancialStatus)
Enum"failed""paid""pending""refunded"
itemsArray of OrderItem (object)(OrderItem)

List of items in the order (see OrderItem)

payment_methodstring

The payment method used for this order

shipping_addressAddress (object)(Address)
Any of:
tagsArray of strings

String tags for this order

total_net_refunds_in_centsinteger(int32)>= 0

Net refunds in cents (total refunded minus taxes)

total_net_revenue_in_centsinteger(int32)>= 0

Net revenue in cents (amount paid minus taxes)

total_price_in_centsinteger(int32)>= 0

Total price paid in cents

total_tax_in_centsinteger(int32)>= 0

Total tax paid in cents

total_tax_refunds_in_centsinteger(int32)>= 0

Total tax in the refunded amount in cents

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"
  }'

Responses

Order updated successfully

Bodyapplication/json
carrier_preferencestring or nullrequired

The preferred carrier to use for delivering this order

created_atstring(date-time)read-onlyrequired

When the order was created. Will default to current time if omitted.

currencystring(CurrencyCode)^[A-Z]{3}$required
custom_metadataobject or null

A JSON object with custom metadata

customer_order_numberstring or null

The order number which your customer sees. In case this is not the same as merchant_order_id.

external_created_atstring or null(date-time)

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_statusstring(OrderFinancialStatus)required
Enum"failed""paid""pending""refunded"
idinteger(int64)read-onlyrequired

Hive's unique identifier for this order

itemsArray of OrderItem (object)(OrderItem)required

List of items in the order (see OrderItem)

Any of:
items[].​merchant_item_idstringrequired

Identifier for the line item. Needs to be unique among the line items of the order.

items[].​price_per_unit_in_centsinteger(int32)>= 0

The price per unit of this item

items[].​price_per_unit_in_cents_with_discountinteger(int32)>= 0

The discounted price per unit of this item

items[].​quantityinteger(int32)>= 1required

The quantity of this item in the order

items[].​sku_codestring

The merchant's SKU identifier - required if sku_id is not provided

items[].​sku_idinteger(int64)required

Hive's SKU identifier - required if sku_code is not provided

merchant_order_idstringrequired

An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.

payment_methodstring or null

The payment method used for this order

sales_channel_idinteger(int64)required

The ID of the sales channel this order belongs to

shipping_addressAddress (object)(Address)required
Any of:
shipping_address.​citystringnon-emptyrequired

City name

shipping_address.​companystring or null

Company name

shipping_address.​country_codestring(CountryCode)^[A-Z]{2}$required
shipping_address.​emailstring or null(email)

Email address

shipping_address.​first_namestring or nullnon-emptyrequired

Customer's first name - required if last_name and full_name are omitted

shipping_address.​full_namestring or nullnon-empty

Customer's full name - required if first_name and last_name are omitted

shipping_address.​last_namestring or nullnon-empty

Customer's last name - required if first_name and full_name are omitted

shipping_address.​line1stringnon-emptyrequired

Customer's address line 1

shipping_address.​line2string or null

Customer's address line 2

shipping_address.​parcel_point_idstring or null

Parcel point ID - see Sendcloud service points

shipping_address.​phonestring or null

Customer's phone number

shipping_address.​postal_codestringnon-emptyrequired

Customer's postal code

shipping_address.​province_or_state_codestring or null

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)

fulfillment_statusstring(OrderFulfillmentStatus)read-onlyrequired
Enum"waiting_for_picking""processing""partially_shipped""shipped""on_hold""payment_pending""cancelled""ignored"
tagsArray of strings or null

String tags for this order

total_net_refunds_in_centsinteger(int32)>= 0required

Net refunds in cents (total refunded minus taxes)

total_net_revenue_in_centsinteger(int32)>= 0required

Net revenue in cents (amount paid minus taxes)

total_price_in_centsinteger(int32)>= 0required

Total price paid in cents

total_tax_in_centsinteger(int32)>= 0required

Total tax paid in cents

total_tax_refunds_in_centsinteger(int32)>= 0required

Total tax in the refunded amount in cents

updated_atstring(date-time)read-onlyrequired

When the order was last updated

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"
}

Cancel an order

Request

Cancels an existing order.

Security
BearerAuth
Path
idinteger(int64)required

Order ID

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>'

Responses

Order cancelled successfully

Bodyapplication/json
carrier_preferencestring or nullrequired

The preferred carrier to use for delivering this order

created_atstring(date-time)read-onlyrequired

When the order was created. Will default to current time if omitted.

currencystring(CurrencyCode)^[A-Z]{3}$required
custom_metadataobject or null

A JSON object with custom metadata

customer_order_numberstring or null

The order number which your customer sees. In case this is not the same as merchant_order_id.

external_created_atstring or null(date-time)

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_statusstring(OrderFinancialStatus)required
Enum"failed""paid""pending""refunded"
idinteger(int64)read-onlyrequired

Hive's unique identifier for this order

itemsArray of OrderItem (object)(OrderItem)required

List of items in the order (see OrderItem)

Any of:
items[].​merchant_item_idstringrequired

Identifier for the line item. Needs to be unique among the line items of the order.

items[].​price_per_unit_in_centsinteger(int32)>= 0

The price per unit of this item

items[].​price_per_unit_in_cents_with_discountinteger(int32)>= 0

The discounted price per unit of this item

items[].​quantityinteger(int32)>= 1required

The quantity of this item in the order

items[].​sku_codestring

The merchant's SKU identifier - required if sku_id is not provided

items[].​sku_idinteger(int64)required

Hive's SKU identifier - required if sku_code is not provided

merchant_order_idstringrequired

An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.

payment_methodstring or null

The payment method used for this order

sales_channel_idinteger(int64)required

The ID of the sales channel this order belongs to

shipping_addressAddress (object)(Address)required
Any of:
shipping_address.​citystringnon-emptyrequired

City name

shipping_address.​companystring or null

Company name

shipping_address.​country_codestring(CountryCode)^[A-Z]{2}$required
shipping_address.​emailstring or null(email)

Email address

shipping_address.​first_namestring or nullnon-emptyrequired

Customer's first name - required if last_name and full_name are omitted

shipping_address.​full_namestring or nullnon-empty

Customer's full name - required if first_name and last_name are omitted

shipping_address.​last_namestring or nullnon-empty

Customer's last name - required if first_name and full_name are omitted

shipping_address.​line1stringnon-emptyrequired

Customer's address line 1

shipping_address.​line2string or null

Customer's address line 2

shipping_address.​parcel_point_idstring or null

Parcel point ID - see Sendcloud service points

shipping_address.​phonestring or null

Customer's phone number

shipping_address.​postal_codestringnon-emptyrequired

Customer's postal code

shipping_address.​province_or_state_codestring or null

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)

fulfillment_statusstring(OrderFulfillmentStatus)read-onlyrequired
Enum"waiting_for_picking""processing""partially_shipped""shipped""on_hold""payment_pending""cancelled""ignored"
tagsArray of strings or null

String tags for this order

total_net_refunds_in_centsinteger(int32)>= 0required

Net refunds in cents (total refunded minus taxes)

total_net_revenue_in_centsinteger(int32)>= 0required

Net revenue in cents (amount paid minus taxes)

total_price_in_centsinteger(int32)>= 0required

Total price paid in cents

total_tax_in_centsinteger(int32)>= 0required

Total tax paid in cents

total_tax_refunds_in_centsinteger(int32)>= 0required

Total tax in the refunded amount in cents

updated_atstring(date-time)read-onlyrequired

When the order was last updated

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"
}

Get an order by merchant order ID and sales channel

Request

Returns a specific order using the merchant's order ID and sales channel ID.

Security
BearerAuth
Query
sales_channel_idinteger(int64)required
merchant_order_idstringrequired
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>'

Responses

An order

Bodyapplication/json
carrier_preferencestring or nullrequired

The preferred carrier to use for delivering this order

created_atstring(date-time)read-onlyrequired

When the order was created. Will default to current time if omitted.

currencystring(CurrencyCode)^[A-Z]{3}$required
custom_metadataobject or null

A JSON object with custom metadata

customer_order_numberstring or null

The order number which your customer sees. In case this is not the same as merchant_order_id.

external_created_atstring or null(date-time)

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_statusstring(OrderFinancialStatus)required
Enum"failed""paid""pending""refunded"
idinteger(int64)read-onlyrequired

Hive's unique identifier for this order

itemsArray of OrderItem (object)(OrderItem)required

List of items in the order (see OrderItem)

Any of:
items[].​merchant_item_idstringrequired

Identifier for the line item. Needs to be unique among the line items of the order.

items[].​price_per_unit_in_centsinteger(int32)>= 0

The price per unit of this item

items[].​price_per_unit_in_cents_with_discountinteger(int32)>= 0

The discounted price per unit of this item

items[].​quantityinteger(int32)>= 1required

The quantity of this item in the order

items[].​sku_codestring

The merchant's SKU identifier - required if sku_id is not provided

items[].​sku_idinteger(int64)required

Hive's SKU identifier - required if sku_code is not provided

merchant_order_idstringrequired

An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.

payment_methodstring or null

The payment method used for this order

sales_channel_idinteger(int64)required

The ID of the sales channel this order belongs to

shipping_addressAddress (object)(Address)required
Any of:
shipping_address.​citystringnon-emptyrequired

City name

shipping_address.​companystring or null

Company name

shipping_address.​country_codestring(CountryCode)^[A-Z]{2}$required
shipping_address.​emailstring or null(email)

Email address

shipping_address.​first_namestring or nullnon-emptyrequired

Customer's first name - required if last_name and full_name are omitted

shipping_address.​full_namestring or nullnon-empty

Customer's full name - required if first_name and last_name are omitted

shipping_address.​last_namestring or nullnon-empty

Customer's last name - required if first_name and full_name are omitted

shipping_address.​line1stringnon-emptyrequired

Customer's address line 1

shipping_address.​line2string or null

Customer's address line 2

shipping_address.​parcel_point_idstring or null

Parcel point ID - see Sendcloud service points

shipping_address.​phonestring or null

Customer's phone number

shipping_address.​postal_codestringnon-emptyrequired

Customer's postal code

shipping_address.​province_or_state_codestring or null

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)

fulfillment_statusstring(OrderFulfillmentStatus)read-onlyrequired
Enum"waiting_for_picking""processing""partially_shipped""shipped""on_hold""payment_pending""cancelled""ignored"
tagsArray of strings or null

String tags for this order

total_net_refunds_in_centsinteger(int32)>= 0required

Net refunds in cents (total refunded minus taxes)

total_net_revenue_in_centsinteger(int32)>= 0required

Net revenue in cents (amount paid minus taxes)

total_price_in_centsinteger(int32)>= 0required

Total price paid in cents

total_tax_in_centsinteger(int32)>= 0required

Total tax paid in cents

total_tax_refunds_in_centsinteger(int32)>= 0required

Total tax in the refunded amount in cents

updated_atstring(date-time)read-onlyrequired

When the order was last updated

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"
}

Partially update an order by merchant order ID and sales channel

Request

Partially updates an order using the merchant's order ID and sales channel ID.

Note: The unique identifiers merchant_order_id and sales_channel_id cannot be updated and will be ignored if provided in the request body.

Security
BearerAuth
Query
sales_channel_idinteger(int64)required
merchant_order_idstringrequired
Bodyapplication/json
carrier_preferencestring or null

The preferred carrier to use for delivering this order

currencystring(CurrencyCode)^[A-Z]{3}$
custom_metadataobject or null

A JSON object with custom metadata

customer_order_numberstring or null

The order number which your customer sees. In case this is not the same as merchant_order_id.

external_created_atstring(date-time)

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_statusstring(OrderFinancialStatus)
Enum"failed""paid""pending""refunded"
itemsArray of OrderItem (object)(OrderItem)

List of items in the order (see OrderItem)

payment_methodstring

The payment method used for this order

shipping_addressAddress (object)(Address)
Any of:
tagsArray of strings

String tags for this order

total_net_refunds_in_centsinteger(int32)>= 0

Net refunds in cents (total refunded minus taxes)

total_net_revenue_in_centsinteger(int32)>= 0

Net revenue in cents (amount paid minus taxes)

total_price_in_centsinteger(int32)>= 0

Total price paid in cents

total_tax_in_centsinteger(int32)>= 0

Total tax paid in cents

total_tax_refunds_in_centsinteger(int32)>= 0

Total tax in the refunded amount in cents

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"
  }'

Responses

Order updated successfully

Bodyapplication/json
carrier_preferencestring or nullrequired

The preferred carrier to use for delivering this order

created_atstring(date-time)read-onlyrequired

When the order was created. Will default to current time if omitted.

currencystring(CurrencyCode)^[A-Z]{3}$required
custom_metadataobject or null

A JSON object with custom metadata

customer_order_numberstring or null

The order number which your customer sees. In case this is not the same as merchant_order_id.

external_created_atstring or null(date-time)

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_statusstring(OrderFinancialStatus)required
Enum"failed""paid""pending""refunded"
idinteger(int64)read-onlyrequired

Hive's unique identifier for this order

itemsArray of OrderItem (object)(OrderItem)required

List of items in the order (see OrderItem)

Any of:
items[].​merchant_item_idstringrequired

Identifier for the line item. Needs to be unique among the line items of the order.

items[].​price_per_unit_in_centsinteger(int32)>= 0

The price per unit of this item

items[].​price_per_unit_in_cents_with_discountinteger(int32)>= 0

The discounted price per unit of this item

items[].​quantityinteger(int32)>= 1required

The quantity of this item in the order

items[].​sku_codestring

The merchant's SKU identifier - required if sku_id is not provided

items[].​sku_idinteger(int64)required

Hive's SKU identifier - required if sku_code is not provided

merchant_order_idstringrequired

An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.

payment_methodstring or null

The payment method used for this order

sales_channel_idinteger(int64)required

The ID of the sales channel this order belongs to

shipping_addressAddress (object)(Address)required
Any of:
shipping_address.​citystringnon-emptyrequired

City name

shipping_address.​companystring or null

Company name

shipping_address.​country_codestring(CountryCode)^[A-Z]{2}$required
shipping_address.​emailstring or null(email)

Email address

shipping_address.​first_namestring or nullnon-emptyrequired

Customer's first name - required if last_name and full_name are omitted

shipping_address.​full_namestring or nullnon-empty

Customer's full name - required if first_name and last_name are omitted

shipping_address.​last_namestring or nullnon-empty

Customer's last name - required if first_name and full_name are omitted

shipping_address.​line1stringnon-emptyrequired

Customer's address line 1

shipping_address.​line2string or null

Customer's address line 2

shipping_address.​parcel_point_idstring or null

Parcel point ID - see Sendcloud service points

shipping_address.​phonestring or null

Customer's phone number

shipping_address.​postal_codestringnon-emptyrequired

Customer's postal code

shipping_address.​province_or_state_codestring or null

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)

fulfillment_statusstring(OrderFulfillmentStatus)read-onlyrequired
Enum"waiting_for_picking""processing""partially_shipped""shipped""on_hold""payment_pending""cancelled""ignored"
tagsArray of strings or null

String tags for this order

total_net_refunds_in_centsinteger(int32)>= 0required

Net refunds in cents (total refunded minus taxes)

total_net_revenue_in_centsinteger(int32)>= 0required

Net revenue in cents (amount paid minus taxes)

total_price_in_centsinteger(int32)>= 0required

Total price paid in cents

total_tax_in_centsinteger(int32)>= 0required

Total tax paid in cents

total_tax_refunds_in_centsinteger(int32)>= 0required

Total tax in the refunded amount in cents

updated_atstring(date-time)read-onlyrequired

When the order was last updated

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"
}

orderStatusUpdatedWebhookWebhook

Request

Security
BearerAuth
Headers
x-hive-signaturestringrequired

HMAC-SHA256 signature of the request body using your API token as the key

Bodyapplication/json
event_typestringrequired

The type of webhook event

Value"order.status_updated"
event_idstring(uuid)required

Unique identifier for this webhook event

timestampstring(date-time)required

When the event occurred

dataobject(Order)required
data.​carrier_preferencestring or nullrequired

The preferred carrier to use for delivering this order

data.​created_atstring(date-time)read-onlyrequired

When the order was created. Will default to current time if omitted.

data.​currencystring(CurrencyCode)^[A-Z]{3}$required
data.​custom_metadataobject or null

A JSON object with custom metadata

data.​customer_order_numberstring or null

The order number which your customer sees. In case this is not the same as merchant_order_id.

data.​external_created_atstring or null(date-time)

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.

data.​financial_statusstring(OrderFinancialStatus)required
Enum"failed""paid""pending""refunded"
data.​idinteger(int64)read-onlyrequired

Hive's unique identifier for this order

data.​itemsArray of OrderItem (object)(OrderItem)required

List of items in the order (see OrderItem)

Any of:
data.​items[].​merchant_item_idstringrequired

Identifier for the line item. Needs to be unique among the line items of the order.

data.​items[].​price_per_unit_in_centsinteger(int32)>= 0

The price per unit of this item

data.​items[].​price_per_unit_in_cents_with_discountinteger(int32)>= 0

The discounted price per unit of this item

data.​items[].​quantityinteger(int32)>= 1required

The quantity of this item in the order

data.​items[].​sku_codestring

The merchant's SKU identifier - required if sku_id is not provided

data.​items[].​sku_idinteger(int64)required

Hive's SKU identifier - required if sku_code is not provided

data.​merchant_order_idstringrequired

An ID that uniquely identifies this order within the sales channel. Must be unique per sales channel.

data.​payment_methodstring or null

The payment method used for this order

data.​sales_channel_idinteger(int64)required

The ID of the sales channel this order belongs to

data.​shipping_addressAddress (object)(Address)required
Any of:
data.​shipping_address.​citystringnon-emptyrequired

City name

data.​shipping_address.​companystring or null

Company name

data.​shipping_address.​country_codestring(CountryCode)^[A-Z]{2}$required
data.​shipping_address.​emailstring or null(email)

Email address

data.​shipping_address.​first_namestring or nullnon-emptyrequired

Customer's first name - required if last_name and full_name are omitted

data.​shipping_address.​full_namestring or nullnon-empty

Customer's full name - required if first_name and last_name are omitted

data.​shipping_address.​last_namestring or nullnon-empty

Customer's last name - required if first_name and full_name are omitted

data.​shipping_address.​line1stringnon-emptyrequired

Customer's address line 1

data.​shipping_address.​line2string or null

Customer's address line 2

data.​shipping_address.​parcel_point_idstring or null

Parcel point ID - see Sendcloud service points

data.​shipping_address.​phonestring or null

Customer's phone number

data.​shipping_address.​postal_codestringnon-emptyrequired

Customer's postal code

data.​shipping_address.​province_or_state_codestring or null

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)

data.​fulfillment_statusstring(OrderFulfillmentStatus)read-onlyrequired
Enum"waiting_for_picking""processing""partially_shipped""shipped""on_hold""payment_pending""cancelled""ignored"
data.​tagsArray of strings or null

String tags for this order

data.​total_net_refunds_in_centsinteger(int32)>= 0required

Net refunds in cents (total refunded minus taxes)

data.​total_net_revenue_in_centsinteger(int32)>= 0required

Net revenue in cents (amount paid minus taxes)

data.​total_price_in_centsinteger(int32)>= 0required

Total price paid in cents

data.​total_tax_in_centsinteger(int32)>= 0required

Total tax paid in cents

data.​total_tax_refunds_in_centsinteger(int32)>= 0required

Total tax in the refunded amount in cents

data.​updated_atstring(date-time)read-onlyrequired

When the order was last 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": { … }
  }
}

Responses

Webhook received successfully

RestockingShipments

Operations related to restocking shipments

OperationsWebhooks

Returns

Operations related to returns

OperationsWebhooks

SKUs

Operations related to Stock Keeping Units (SKUs)

Operations

SalesChannels

Operations related to sales channels

Operations

Shipments

Operations related to shipments

OperationsWebhooks

Warehouses

Operations related to warehouses

Operations

Webhooks

Webhook event notifications

Webhooks