Skip to content

Create a new order

Request

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

Security
BearerAuth
Bodyapplication/jsonrequired
b2b_instructionsobject(OrderB2bInstructionsInput)

B2B packing and shipping instructions. Only applicable to B2B orders (see order_type).

carrier_preferencestring or null

The preferred carrier to use for delivering this order

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

3-letter ISO 4217 currency code. Defaults to the merchant's primary currency if omitted.

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.

documentsArray of objects, <= 5 items(OrderDocumentInput)

Documents to attach to the order. Only applicable to B2B orders. Maximum 5 documents. Ignored for non-B2B orders.

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)

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"
itemsArray of objects, non-empty(OrderItem)required

List of items in the order (see OrderItem)

merchant_notestring or null

Internal note from the merchant about this order

merchant_order_idstring, non-emptyrequired

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

order_typeOrderType (string) or null
One of:

How Hive fulfils the order. Possible values:

  • B2B: a business order. It can carry b2b_instructions, documents and inventory_batches on its items, and Hive picks, packs and ships it as a B2B order
  • B2C: a consumer order
string(OrderType)
Enum:"B2B""B2C"
payment_methodstring or null

The payment method used for this order. For Cash on Delivery orders, use 'COD'. When payment_method contains 'COD', total_price_in_cents must be greater than 0.

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_addressobject(Address)required
Any of:
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. Required and must be greater than 0 for COD (Cash on Delivery) orders, as this value is transmitted to the carrier as the amount to collect from the customer at delivery.

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://developers.hive.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
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.

order_typestring(OrderType)required

How Hive fulfils the order. Possible values:

  • B2B: a business order. It can carry b2b_instructions, documents and inventory_batches on its items, and Hive picks, packs and ships it as a B2B order
  • B2C: a consumer order
Enum:"B2B""B2C"
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_addressOrderShippingAddress (object) or null
One of:

Shipping address as returned on an order. Same fields as Address, plus the deprecated province_code, which is only returned; sending it on create or update has no effect.

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

Response
{
  "id": 123456,
  "items": [
    { … }
  ],
  "merchant_order_id": "ORD-1001",
  "order_type": "B2C",
  "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"
}