Skip to content

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
b2b_instructionsOrderB2bInstructions (object) or null
One of:

B2B packing and shipping instructions (read-only, returned in order responses)

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

3-letter ISO 4217 currency code. Examples: EUR, USD, GBP, JPY

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.

documentsArray of objects(OrderDocument)

Documents attached to this order (excluding system-generated documents). Only present for B2B orders.

financial_statusstring(OrderFinancialStatus)required

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"
idinteger, (int64)read-onlyrequired

Hive's unique identifier for this order

itemsArray of objects(OrderItemResponse)required

List of items in the order

merchant_notestring or null

Internal note from the merchant about this order

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

po_numberstring or null

Purchase order number for B2B orders

recipient_instructionsstring or null

Delivery or handling instructions for the recipient

sales_channel_idinteger, (int64)required

The ID of the sales channel this order belongs to

shipping_addressAddress (object) or null
One of:
fulfillment_statusstring(OrderFulfillmentStatus)read-onlyrequired

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

has_blocking_issuesbooleanread-only

Whether the order has any unresolved external issues blocking fulfillment.

Response
{
  "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",
  "has_blocking_issues": false,
  "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"
}