Orders
The Order resource
carrier_preference
String
The preferred carrier to use for delivering this order
created_at
ISO8601 datetime
When the order was created. Will default to current time if omitted.
currency
String
custom_metadata
JSON object
A JSON object with custom metadata
customer_order_number
String
The order number which your customer sees. In case this is not the same as merchant_order_id.
financial_status
String
Financial status of this order, can be one of the following: paid, refunded, pending, failed
id
Integer (read-only)
Hive's unique identifier for this order
items*
An array of OrderLineItem objects
A collection of order items
merchant_order_id*
String
An ID that uniquely identifies this order
payment_method
String
The payment method used for this order
shipping_address*
An Address object
The shipping address
status
String (read-only)
Order status. Possible values:
fulfillable - will be fulfilled by Hive, normally all orders created via Merchant API are treated as fulfillable by default
unfulfillable - will not be fulfilled by Hive; such a status could be assigned to an order for example when shipping address's country is among blacklisted countries (configured on Hive side by Account Manager) for that shop; also order will have this status after cancellation
fulfilled - order is fulfilled
tags
An array of Strings
String tags for this order
total_net_refunds_in_cents
Integer
Net refunds in cents (total refunded minus taxes)
total_net_revenue_in_cents
Integer
Net revenue in cents (amount paid minus taxes)
total_price_in_cents
Integer
Total price paid in cents
total_tax_in_cents
Integer
Total tax paid in cents
total_tax_refunds_in_cents
Integer
Total tax in the refunded amount in cents
The OrderLineItem resource
merchant_item_id*
String
Identifier for the line item. Needs to be unique among the line items of the order.
merchant_sku_id
String
The merchant's SKU identifier - required if sku_id is not provided
price_per_unit_in_cents*
Integer
The price per unit of this item
price_per_unit_in_cents_with_discount
Integer
The discounted price per unit of this item
quantity*
Integer
The quantity of this item in the order
sku_id
Integer
Hive's SKU identifier - required if merchant_sku_id is not provided
The Address resource
city*
String
City name
company
String
Company name
country_code*
String
String
Email address
first_name
String
Customer's first name - required if last_name is omitted
full_name*
String
Customer's full name
last_name
String
Customer's last name - required if first_name is omitted
line1*
String
Customer's address line 1
line2
String
Customer's address line 2
parcel_point_id
String
phone
String
Customer's phone number
postal_code*
String
Customer's postal code
province_or_state_code
String
List all orders
Lists all orders
GET https://app.hive.app/merchant_api/v1/orders
Returns orders ordered by descending creation time.
Query Parameters
created_at[lt]
ISO8601 datetime
Return results where the created_at field is less than this value.
created_at[lte]
ISO8601 datetime
Return results where the created_at field is less than or equal to this value.
created_at[gt]
ISO8601 datetime
Return results where the created_at field is greater than this value.
created_at[gte]
ISO8601 datetime
Return results where the created_at field is greater than or equal to this value.
Get one order
Gets one order
GET https://app.hive.app/merchant_api/v1/orders/{id}
Path Parameters
id*
Integer
The (Hive) ID of the order
Create a new order
Creates a new order
POST https://app.hive.app/merchant_api/v1/orders
Request Body
merchant_order_id*
String
An ID that uniquely identifies this order
shipping_address*
Object
A shipping address
items*
[]Object
A collection of order items
customer_order_number
String
The order number which your customer sees. In case this is not the same as merchant_order_id.
carrier_preference
String
The preferred carrier to use for delivering this order
tags
[]String
An optional list of strings. Can be used to perform actions on the order (e.g. with add-on rules).
custom_metadata
Object
A JSON object with custom metadata
shipping_address.first_name
String
First name of recipient - either this, or last_name is required
shipping_address.last_name
String
Last name of recipient - either this, or first_name is required
shipping_address.line2
String
Destination address line 2 of shipment
shipping_address.line1*
String
Destination address line 1 of shipment
shipping_address.full_name*
String
Full name of recipient
shipping_address.city*
String
Destination city of shipment
shipping_address.postal_code*
String
Destination postal code of shipment
shipping_address.country_code*
String
Destination country code of shipment
shipping_address.company
String
Company name of recipient
shipping_address.phone
String
Phone number of recipient
shipping_address.email
String
Email of recipient
items[].quantity*
Integer
The quantity of this item in the order
items[].price_per_unit_in_cents*
Integer
The price per unit of this item
items[].merchant_item_id*
String
An unique identifier (in the scope of this order) for this item. Items are matched by this ID, when updating an order.
items[].sku_id
Integer
The (Hive) SKU ID for this item - required if merchant_sku_id is missing
items[].merchant_sku_id
String
The merchant SKU ID for this item - required if sku_id is missing
items[].price_per_unit_in_cents_with_discount
Integer
The discounted price per unit of this item
shipping_address.parcel_point_id
String
Parcel point ID - currently only Sendcloud parcel points are supported
payment_method
String
The payment method used for this order
financial_status
String
Financial status of this order, can be one of the following: paid, refunded, pending, failed
shipping_address.province_or_state_code
String
Destination province or state code of shipment
created_at
ISO8601 datetime
The creation date of this order
total_price_in_cents
Integer
Total price of the order, in cents.
total_net_revenue_in_cents
Integer
Total revenue of the order, tax excluded, in cents.
total_tax_in_cents
Integer
Total tax od the order, in cents.
total_net_refunds_in_cents
Integer
Total refunds of the order, tax excluded, in cents.
total_tax_refunds_in_cents
Integer
Total tax refunds of the order, in cents.
currency
String
Update an order
Updates an order
PATCH https://app.hive.app/merchant_api/v1/orders/{id}
Path Parameters
id*
Integer
The (Hive) ID of the order
Request Body
merchant_order_id
String
An ID that uniquely identifies this order
shipping_address
Object
A shipping address
shipping_address.first_name
String
First name of recipient
shipping_address.last_name
String
Last name of recipient
items[].sku_id
Integer
The (Hive) SKU ID for this item
items[].merchant_item_id*
String
The unique identifier of the item to update
items
[]Object
A collection of order items to update
shipping_address.postal_code
String
Destination postal code of shipment
shipping_address.country_code
String
shipping_address.city
String
Destination city of shipment
shipping_address.line2
String
Destination address line 2 of shipment
shipping_address.line1
String
Destination address line 1 of shipment
shipping_address.company
String
Company name of recipient
shipping_address.phone
String
Phone number of recipient
shipping_address.email
String
Email of recipient
shipping_address.full_name
String
Full name of recipient
customer_order_number
String
The order number which your customer sees. In case this is not the same as merchant_order_id.
items[].price_per_unit_in_cents
Integer
The price per unit of this item
items[].quantity
Integer
The quantity of this item in the order
items[].merchant_sku_id
String
The merchant SKU ID for this item
tags
[]String
An optional list of strings. Can be used to perform actions on the order (e.g. with add-on rules).
custom_metadata
Object
A JSON object with custom metadata
carrier_preference
String
The preferred carrier to use for delivering this order
items[].price_per_unit_in_cents_with_discount
Integer
The discounted price per unit of this item
shipping_address.parcel_point_id
String
Parcel point ID - currently only Sendcloud parcel points are supported
payment_method
String
The payment method used for this order
financial_status
String
Financial status of this order, can be one of the following: paid, refunded, pending, failed Responses 201: Created
shipping_address.province_or_state_code
String
Destination province or state code of shipment
created_at
ISO8601 datetime
The creation date of this order
total_price_in_cents
Integer
Total price of the order, in cents.
total_net_revenue_in_cents
Integer
Total revenue of the order, tax excluded, in cents.
total_tax_in_cents
Integer
Total tax od the order, in cents.
total_net_refunds_in_cents
Integer
Total refunds of the order, tax excluded, in cents.
total_tax_refunds_in_cents
Integer
Total tax refunds of the order, in cents. Responses 201: Created
currency
String
Cancel an order
Cancels an order
PUT https://app.hive.app/merchant_api/v1/orders/{id}/cancel
Path Parameters
id*
Integer
Last updated