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

b2b_instructionsobject(OrderB2bInstructionsPatch)

B2B packing and shipping instructions. Only applicable to B2B orders.

carrier_preferencestring or null

The preferred carrier to use for delivering this order

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

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.

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, (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(OrderItem)

List of items in the order (see OrderItem)

merchant_notestring or null

Internal note from the merchant about this order

payment_methodstring

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

shipping_addressAddress (object) or null

One 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. 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 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

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

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