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. 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\_cents | Integer | Total tax paid in cents | | total\_tax\_refunds\_in\_cents | Integer | Total tax in the refunded amount in cents | ## The OrderLineItem resource | Property | Type | Description | | ------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. Defaults to 0 if omitted. Recommended for customs documents and declarations, return label generation, and required for accurate COD (Cash on Delivery) order amounts. | | 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 | Property | Type | Description | | ----------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- | | city\* | String | City name | | company | String | Company name | | country\_code\* | String | 2-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) code of country | | email | 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 | Parcel point ID - see [Sendcloud service points](https://api.sendcloud.dev/docs/sendcloud-public-api/branches/v2/service-points) | | phone | String | Customer's phone number | | postal\_code\* | String | Customer's postal code | | province\_or\_state\_code | String | 2-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-2) code of province/state code | {% hint style="info" %} \*Required properties when creating a new record. {% endhint %} ## List all orders ## Lists all orders `GET` `https://app.hive.app/merchant_api/v1/orders` Returns orders ordered by descending creation time. #### Query Parameters | Name | Type | Description | | ----------------- | ---------------- | ----------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200: OK " %} ```json { "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 } } ``` {% endtab %} {% endtabs %} ## Get one order ## Gets one order `GET` `https://app.hive.app/merchant_api/v1/orders/{id}` #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------- | -------------------------- | | id\* | Integer | The (Hive) ID of the order | {% tabs %} {% tab title="200: OK " %} ```json { "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 } ``` {% endtab %} {% tab title="404: Not Found There was no order matching the given ID" %} ```json { "success": false, "errors": [ "record not found" ] } ``` {% endtab %} {% endtabs %} ## Create a new order ## Creates a new order `POST` `https://app.hive.app/merchant_api/v1/orders` #### Request Body | Name | Type | Description | | ---------------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes), defaults to "EUR" if not provided | {% tabs %} {% tab title="201: Created The order was created successfully" %} ```json { "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 } ``` {% endtab %} {% tab title="400: Bad Request The request was malformed" %} ```json { "success": false, "errors": [ "bad request" ] } ``` {% endtab %} {% tab title="422: Unprocessable Entity The data was invalid" %} ```json { "success": false, "errors": [ "Merchant order can't be blank", "Shipping address can't be blank", "Items can't be blank" ] } ``` {% endtab %} {% endtabs %} ## Update an order ## Updates an order `PATCH` `https://app.hive.app/merchant_api/v1/orders/{id}` #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------- | -------------------------- | | id\* | Integer | The (Hive) ID of the order | #### Request Body | Name | Type | Description | | ------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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