Skip to content

Cancel an order

Request

Cancels an order that Hive has not started fulfilling yet. The order's status becomes unfulfillable.

Answers with 422 Unprocessable Entity when fulfillment has already started, or when Hive has not processed the order yet.

Security
BearerAuth
Path
idinteger, (int64)required

The Hive ID of the order.

curl -i -X PUT \
  'https://developers.hive.app/_mock/merchant-api-v1/mapi_v1_oas31/orders/{id}/cancel' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The cancelled 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
}