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
The international 3-letter code as defined by the ISO 4217 standard, defaults to "EUR" if not provided
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
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
phone
String
Customer's phone number
postal_code*
String
Customer's postal code
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.
{
"data": [
{
"id": 4962,
"merchant_order_id": "60423b95-23b5-4e5b-aa1c-6a71bd90b106",
"customer_order_number": null,
"status": "fulfillable",
"carrier_preference": null,
"created_at": "2022-11-01T17:42:07.409+01:00",
"financial_status": null,
"payment_method": null,
"currency": "EUR",
"total_price_in_cents": 0,
"total_net_revenue_in_cents": 0,
"total_tax_in_cents": 0,
"total_net_refunds_in_cents": 0,
"total_tax_refunds_in_cents": 0,
"shipping_address": {
"first_name": "John",
"last_name": "Doe",
"full_name": "John Doe",
"email": null,
"phone": null,
"company": null,
"line1": "Kassaveti 69",
"line2": null,
"city": "Volos",
"country_code": "GR",
"postal_code": "38221",
"parcel_point_id": "12345"
},
"items": [
{
"sku_id": 9,
"quantity": 1,
"merchant_item_id": "1",
"price_per_unit_in_cents": 0,
"price_per_unit_in_cents_with_discount": 0,
"merchant_sku_id": "28595522549341"
}
],
"tags": ["first_order"],
"custom_metadata": null
}
],
"pagination": {
"current_page": 1,
"item_count": 1,
"page_count": 1,
"items_per_page": 20
}
}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
{
"id":4962,
"merchant_order_id":"60423b95-23b5-4e5b-aa1c-6a71bd90b106",
"customer_order_number":null,
"status":"fulfillable",
"carrier_preference":null,
"created_at":"2022-11-01T17:42:07.409+01:00",
"financial_status":null,
"payment_method":null,
"currency": "EUR",
"total_price_in_cents":0,
"total_net_revenue_in_cents":0,
"total_tax_in_cents":0,
"total_net_refunds_in_cents":0,
"total_tax_refunds_in_cents":0,
"shipping_address":{
"first_name":"John",
"last_name":"Doe",
"full_name":"John Doe",
"email":null,
"phone":null,
"company":null,
"line1":"Kassaveti 69",
"line2":null,
"city":"Volos",
"country_code":"GR",
"postal_code":"38221",
"parcel_point_id":"12345"
},
"items":[
{
"sku_id":9,
"quantity":1,
"merchant_item_id":"1",
"price_per_unit_in_cents":0,
"price_per_unit_in_cents_with_discount":0,
"merchant_sku_id":"28595522549341"
}
],
"tags":["first_order"],
"custom_metadata":null
}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
The international 3-letter code as defined by the ISO 4217 standard, defaults to "EUR" if not provided
{
"id":4962,
"merchant_order_id":"60423b95-23b5-4e5b-aa1c-6a71bd90b106",
"customer_order_number":null,
"status":"fulfillable",
"carrier_preference":null,
"created_at":"2022-11-01T17:42:07.409+01:00",
"financial_status":null,
"payment_method":null,
"currency": "EUR",
"total_price_in_cents":0,
"total_net_revenue_in_cents":0,
"total_tax_in_cents":0,
"total_net_refunds_in_cents":0,
"total_tax_refunds_in_cents":0,
"shipping_address":{
"first_name":"John",
"last_name":"Doe",
"full_name":"John Doe",
"email":null,
"phone":null,
"company":null,
"line1":"Kassaveti 69",
"line2":null,
"city":"Volos",
"country_code":"GR",
"postal_code":"38221",
"parcel_point_id":"12345"
},
"items":[
{
"sku_id":9,
"quantity":1,
"merchant_item_id":"1",
"price_per_unit_in_cents":0,
"price_per_unit_in_cents_with_discount":0,
"merchant_sku_id":"28595522549341"
}
],
"tags":[],
"custom_metadata":null
}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.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
The international 3-letter code as defined by the ISO 4217 standard, defaults to "EUR" if not provided
{
"id":4962,
"merchant_order_id":"60423b95-23b5-4e5b-aa1c-6a71bd90b106",
"customer_order_number":null,
"status":"fulfillable",
"carrier_preference":null,
"created_at":"2022-11-01T17:42:07.409+01:00",
"financial_status":null,
"payment_method":null,
"currency": "EUR",
"total_price_in_cents":0,
"total_net_revenue_in_cents":0,
"total_tax_in_cents":0,
"total_net_refunds_in_cents":0,
"total_tax_refunds_in_cents":0,
"shipping_address":{
"first_name":"John",
"last_name":"Doe",
"full_name":"John Doe",
"email":null,
"phone":null,
"company":null,
"line1":"Kassaveti 69",
"line2":null,
"city":"Volos",
"country_code":"GR",
"postal_code":"38221",
"parcel_point_id":"12345"
},
"items":[
{
"sku_id":9,
"quantity":1,
"merchant_item_id":"1",
"price_per_unit_in_cents":0,
"price_per_unit_in_cents_with_discount":0,
"merchant_sku_id":"28595522549341"
}
],
"tags":[],
"custom_metadata":null
}Cancel an order
Cancels an order
PUT https://app.hive.app/merchant_api/v1/orders/{id}/cancel
Path Parameters
id*
Integer
{
"id":4962,
"merchant_order_id":"60423b95-23b5-4e5b-aa1c-6a71bd90b106",
"customer_order_number":null,
"status":"fulfillable",
"carrier_preference":null,
"created_at":"2022-11-01T17:42:07.409+01:00",
"financial_status":null,
"payment_method":null,
"currency": "EUR",
"total_price_in_cents":0,
"total_net_revenue_in_cents":0,
"total_tax_in_cents":0,
"total_net_refunds_in_cents":0,
"total_tax_refunds_in_cents":0,
"shipping_address":{
"first_name":"John",
"last_name":"Doe",
"full_name":"John Doe",
"email":null,
"phone":null,
"company":null,
"line1":"Kassaveti 69",
"line2":null,
"city":"Volos",
"country_code":"GR",
"postal_code":"38221",
"parcel_point_id":"12345"
},
"items":[
{
"sku_id":9,
"quantity":1,
"merchant_item_id":"1",
"price_per_unit_in_cents":0,
"price_per_unit_in_cents_with_discount":0,
"merchant_sku_id":"28595522549341"
}
],
"tags":[],
"custom_metadata":null
}Last updated