Skip to content

Create an order

Request

Creates an order. Hive fulfills it unless its destination country is blocked for the sales channel.

merchant_order_id must be unique within the sales channel. Sending one that already exists is answered with 409 Conflict, and the metadata.id of the error is the Hive ID of the existing order.

Security
BearerAuth
Bodyapplication/jsonrequired
carrier_preferencestring or null

The carrier you prefer for delivering this order.

created_atstring or null

When the order was placed, as an ISO 8601 date-time. Must not be in the future; defaults to the current time.

currencystring or null

The 3-letter ISO 4217 currency code of the order's amounts. Defaults to EUR.

custom_metadataobject or null

Any JSON object you want to store with the order.

customer_order_numberstring or null

The order number the customer sees, if it differs from merchant_order_id, which is the default.

financial_statusstring or null

The financial status of the order.

Enum:"paid""refunded""pending""failed"null
idany

Accepted and ignored; Hive assigns the ID.

itemsArray of objects(OrderItemInput)required

The order's line items. At least one is required, and each merchant_item_id must be unique within the order.

merchant_order_idstringrequired

Your unique identifier for the order, unique within the sales channel.

payment_methodstring or null

The payment method of the order. For a Cash on Delivery order, send a value containing COD; total_price_in_cents must then be greater than 0, because it is the amount the carrier collects at delivery.

shipping_addressobject(AddressInput)required

The order's shipping address and recipient.

statusstring or null

The order status to store. Leave it out; orders are created as fulfillable.

Enum:"fulfillable""unfulfillable""fulfilled""on_hold"null
tagsArray of strings or string or null

Tags for the order, for example to trigger add-on rules. A single string is accepted as one tag.

total_net_refunds_in_centsinteger or string or null^-?[0-9]+$

Refunds without tax, in cents. A string of digits is accepted too.

total_net_revenue_in_centsinteger or string or null^-?[0-9]+$

Revenue without tax, in cents. A string of digits is accepted too.

total_price_in_centsinteger or string or null^-?[0-9]+$

The total price paid, in cents. Required and greater than 0 for Cash on Delivery orders. A string of digits is accepted too.

total_tax_in_centsinteger or string or null^-?[0-9]+$

The tax paid, in cents. A string of digits is accepted too.

total_tax_refunds_in_centsinteger or string or null^-?[0-9]+$

The tax part of the refunds, in cents. A string of digits is accepted too.

curl -i -X POST \
  https://developers.hive.app/_mock/merchant-api-v1/mapi_v1_oas31/orders \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant_order_id": "60423b95-23b5-4e5b-aa1c-6a71bd90b106",
    "customer_order_number": "#1042",
    "currency": "EUR",
    "financial_status": "paid",
    "total_price_in_cents": 2500,
    "tags": [
      "first_order"
    ],
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "line1": "Kassaveti 69",
      "city": "Volos",
      "country_code": "GR",
      "postal_code": "38221"
    },
    "items": [
      {
        "merchant_item_id": "1",
        "merchant_sku_id": "28595522549341",
        "quantity": 1,
        "price_per_unit_in_cents": 2500
      }
    ]
  }'

Responses

The created order

Bodyapplication/json
carrier_preferencestring or nullrequired

The carrier the merchant prefers for delivering this order.

created_atstring, (date-time)required

When the order was placed, as sent by the merchant; the time Hive received it if none was sent.

currencystringrequired

The 3-letter ISO 4217 currency code of the order's amounts.

custom_metadataobject or nullrequired

The custom metadata object sent by the merchant.

customer_order_numberstring or nullrequired

The order number the customer sees; the merchant_order_id when none was sent.

financial_statusstring or nullrequired

The financial status of the order.

Enum:"paid""refunded""pending""failed"null
idinteger, (int64)read-onlyrequired

Hive's unique identifier for the order.

itemsArray of objects(OrderItem)required

The order's line items, including items cancelled by an update.

merchant_order_idstringrequired

The merchant's unique identifier for the order, unique within the sales channel.

payment_methodstring or nullrequired

The payment method of the order. COD marks a Cash on Delivery order.

shipping_addressobject(Address)required

The order's shipping address and recipient.

statusstringrequired

The order status:

  • fulfillable: Hive will fulfill the order. Orders created through the API are fulfillable by default.
  • unfulfillable: Hive will not fulfill the order, for example because it was cancelled or its destination country is blocked for the sales channel.
  • fulfilled: the order is fulfilled.
  • on_hold: fulfillment of the order is on hold.
Enum:"fulfillable""unfulfillable""fulfilled""on_hold"
tagsArray of stringsrequired

The order's tags.

total_net_refunds_in_centsinteger or nullrequired

Refunds without tax, in cents.

total_net_revenue_in_centsinteger or nullrequired

Revenue without tax (amount paid minus tax), in cents.

total_price_in_centsintegerrequired

The total price paid, in cents.

total_tax_in_centsinteger or nullrequired

The tax paid, in cents.

total_tax_refunds_in_centsinteger or nullrequired

The tax part of the refunds, in cents.

Response
{
  "id": 4962,
  "merchant_order_id": "60423b95-23b5-4e5b-aa1c-6a71bd90b106",
  "customer_order_number": "#1042",
  "status": "fulfillable",
  "carrier_preference": null,
  "created_at": "2022-11-01T17:42:07.409+01:00",
  "currency": "EUR",
  "financial_status": "paid",
  "payment_method": null,
  "total_price_in_cents": 2500,
  "total_net_revenue_in_cents": 2101,
  "total_tax_in_cents": 399,
  "total_net_refunds_in_cents": 0,
  "total_tax_refunds_in_cents": 0,
  "tags": [
    "first_order"
  ],
  "shipping_address": {
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "email": "john.doe@example.com",
    "phone": null,
    "company": null,
    "line1": "Kassaveti 69",
    "line2": null,
    "city": "Volos",
    "country_code": "GR",
    "postal_code": "38221",
    "parcel_point_id": null,
    "province_or_state_code": null
  },
  "items": [
    { … }
  ],
  "custom_metadata": null
}