# Hive Merchant API ## Introduction This is the documentation for the API which allows merchants to integrate their systems with Hive. Our API is used to integrate stores or ERP systems for which we do not yet have a native integration. You can POST SKUs and orders, as well as retrieve fulfillment and delivery statuses of them. You can also use the Hive API to interact with other features of our WMS software, such as restocking shipments, returns and SKUs. The API currently doesn't give access to all the data and features of the Hive app. That is, if you have multiple integrations, you cannot view or edit data from those integrations (e.g. orders). If your platform of choice is listed in [Hive's integration list](https://www.hive.app/product/integrations) you don't need to use this API. ## Want to jump right in? Feeling like an eager beaver? Jump in to the quick start docs and get making your first request: {% content-ref url="/pages/crWCfM9bLwrumZT3rNwA" %} [Quick Start](/quick-start) {% endcontent-ref %} ## Want to deep dive? Dive a little deeper and start exploring our API reference to get an idea of everything that's possible with the API: {% content-ref url="/pages/flXdNgVtaeL8PkyxsFS1" %} [API Reference](/reference/api-reference) {% endcontent-ref %} # Quick Start ## Get your API key Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error. You can ask your account manager to create an API key for you. The production domain for the HIVE API is , the staging domain is ## Install a REST client The API uses JSON extensively. It only accepts requests where the body is valid JSON (so you need to set the header `content-type: application/json` in your requests). It's easier to interact with it using a REST client. Some options are: * [Insomnia](https://insomnia.rest/) * [Postman](https://www.postman.com/) * [REST client extension](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) for VS code * [curlie](https://curlie.io/) for the command line # Changelog List of API changes by date **2025-07-04** * Document `limit` query parameter for pagination **2025-07-02** * Fix expiry\_date type in the shipping example payload (it's a date, not datetime) **2025-06-18** * Practical advice for out-of-order webhook handling **2025-05-15** * Add `dangerous_good`, `h_codes`, `hazardous_good` and `un_names` to Sku responses **2025-03-27** * Clarification on `merchant_item_id`being `null`for shipment items added later as add-ons (i.e. not part of the order line items) **2024-08-08** * Add `merchant_item_id` property to `items` in `GET /shipments` response **2024-06-26** * Add `items` to `GET /shipments` response **2024-06-24** * Add details about rate limit **2024-06-21** * Edit introduction to clarify data scope of the API vs Hive app **2023-11-22** * Document pagination parameter for collections **2023-09-18** * Add optional `include` parameter to the `GET /orders/{id}` endpoint to retrieve the SKU batches included in the order **2023-08-01** * Add `DELETE /skus/{id}` endpoint * Add `status` property to responses in SKUs endpoints **2023-07-21** * Add optional `include` parameter to the `GET /orders` endpoint to retrieve the SKU batches included in the orders **2023-06-01** * Add `GET /returns` endpoint * Add `GET /returns/{id}` endpoint **2023-05-30** * Add barcode to the [Restocking Shipments](/reference/api-reference/restocking-shipments) resource. **2023-05-29** * Add production and staging domains in the [Quick Start](/quick-start) page. **2023-05-18** * Add batch inventory information to the [Restocking Shipment ](/reference/api-reference/restocking-shipments)resource. **2023-05-03** * Change `quantity` to `announced_quantity` to restocking shipment item in the restocking shipment's response * Add `arrived_quantity` `damaged_quantity` `missing_quantity` to restocking shipment item in the restocking shipment's response **2023-04-26** * Add `POST /skus/bulk_upsert` endpoint **2023-04-19** * Add `fulfilled_by` property to responses in SKUs endpoints **2023-04-18** * Add `batch_tracking_enabled` property in SKUs endpoints' responses and accept it in `POST`/`PATCH` * Add `/restocking_shipments` endpoints * Add `GET /warehouses` endpoint **2023-04-14** * Add `inventory_batches` property to responses in SKUs endpoints **2023-04-11** * Add `currency` property in Orders endpoints' responses and accept it in `POST`/`PATCH` # API Reference Dive into the specifics of each API endpoint by checking out our complete documentation. {% content-ref url="/pages/AA9cFBnAK9xyushNYloy" %} [General](/reference/api-reference/general) {% endcontent-ref %} {% content-ref url="/pages/PWw0aWwOhHXvf5tDsTWk" %} [SKUs](/reference/api-reference/skus) {% endcontent-ref %} {% content-ref url="/pages/Y4ZUkyTXhh3Tih1K7Wik" %} [Orders](/reference/api-reference/orders) {% endcontent-ref %} {% content-ref url="/pages/C2IZKaWwloghZhBO0my2" %} [Shipments](/reference/api-reference/shipments) {% endcontent-ref %} {% content-ref url="/pages/ME6I0b7kGYGOLQkRSB3L" %} [Warehouses](/reference/api-reference/warehouses) {% endcontent-ref %} {% content-ref url="/pages/F31e2GDdQCxSHvmZrPj8" %} [Restocking Shipments](/reference/api-reference/restocking-shipments) {% endcontent-ref %} {% content-ref url="/pages/20oB2PFQpPz0Fr6IlIu2" %} [Webhooks](/reference/api-reference/webhooks) {% endcontent-ref %} # General ## Authentication All API requests need to be authenticated. To do this, you need to always send the HTTP header `Authorization` with your API key as a bearer token: `Authorization: Bearer your_api_key` ## Rate limits To protect our servers from getting overloaded and avoid misuse, we enforce a rate limit of 100 requests per minute. You shouldn't need to poll frequently for status updates as you can get real-time updates via [Webhooks](/reference/api-reference/webhooks). In case you have a valid use case for a higher rate limit, please contact your account manager. The API responds with the following headers to indicate the number of requests used and the maximum available: ``` X-Rate-Limit-Used: 42 X-Rate-Limit-Max: 100 ``` Any requests above the limit will be denied with a 429 response code (too many requests). In that case, the response also includes an extra header which shows how many seconds you need to wait before sending a new request: ``` Retry-After: 3.2 ``` ## Errors When a request is unsuccessful, you will get an HTTP status code of [4xx (for client errors)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses) or [5xx (for server errors)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses). The body then will always contain an `errors` property which contains an array of human-readable errors. ### Common errors If your API key is missing, or wrong, you'd get a 401 Unauthorized with this JSON response: ```json { "success": false, "errors": [ "authentication required" ] } ``` Another example, when the request is malformed, you'd get a 400 Bad request: ```json { "success": false, "errors": [ "bad request" ] } ``` Finally, if the data is not valid, you'd get a 422 Unprocessable Entity: ```json { "success": false, "errors": [ "Name can't be blank", "Merchant sku can't be blank" ] } ``` ## Successful responses When an API request is successful, you will get an HTTP status code of [2xx](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#successful_responses). The response body will either be a single object or a collection of objects. ### Single object When you create or update an object, you will get the final state of the object in the response: ```json { "id": 34, "merchant_sku_id": "HIVE_TSH_BLK_M", "name": "Hive T-Shirt (Black - M)", "created_at": "2022-08-10T17:53:04.438+02:00", "cost_in_cents": null, "country_code_of_origin": null, "hs_code": null, "weight_in_kg": 0.3, "inventory": { "stocked": 10000, "reserved": 0, "total": 10000 } } ``` ### Collection of objects When you get a collection of objects in the response, the response is an object with a `data` property and a `pagination` property. The actual collection of object is in the `data` property: ```json { "data": [ { "id": 9, "merchant_sku_id": "2218061549136", "name": "Morph II", "created_at": "2022-08-10T17:53:04.822+02:00", "cost_in_cents": null, "country_code_of_origin": null, "hs_code": null, "weight_in_kg": 45.37, "inventory": { "stocked": 10000, "reserved": 0, "total": 10000 } }, { "id": 4, "merchant_sku_id": "4976808834423", "name": "Mr Moonstone", "created_at": "2022-08-10T17:53:04.507+02:00", "cost_in_cents": null, "country_code_of_origin": null, "hs_code": null, "weight_in_kg": 24.92, "inventory": { "stocked": 10000, "reserved": 0, "total": 10000 } } ], "pagination": { "current_page": 1, "item_count": 2, "page_count": 1, "items_per_page": 20 } } ``` ### Pagination In order to access all the objects of the collection, you need to send multiple requests to an endpoint. This works by adding the query string parameter `page` to the URL (e.g. ). The `pagination.page_count` property of the response, returns how many pages are available. If no page parameter is provided, it defaults to `1` (that is, the first page of results). The number of objects per page is configured by passing a `limit` in the query parameters (e.g. ). A maximum of `100` is enforced. The default is `20` if it's not provided. # SKUs ## The SKU resource | Property | Type | Description | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | barcode | String | Barcode of the SKU | | batch\_tracking\_enabled | Boolean | Whether batch tracking of this SKU is enabled | | cost\_in\_cents | Integer | Cost in cents (currency of the shop is implied) | | country\_code\_of\_origin | String | 2-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) code of country of origin | | created\_at | ISO8601 datetime (read-only) | When this SKU was created | | dangerous\_good | Boolean (ready-only) | Sku is a dangerous good | | fulfilled\_by | String (read-only) |

Who is fulfilling this SKU. Valid values:
hive, other, new

| | h\_codes | Array of String (read-only) | Hazardous good H Codes | | hazardous\_good | Boolean (ready-only) | Sku is a hazardous good | | hs\_code | String | The general [Harmonized System](https://en.wikipedia.org/wiki/Harmonized_System) (HS) code for the SKU | | id | Integer (read-only) | Hive unique identifier for this SKU | | image\_url | String | Publicly accessible URL of an image for this SKU | | inventory | A [SkuInventory](#the-skuinventory-resource) object (read-only) | Current inventory | | inventory\_batches | Array of [SkuInventoryBatches](#the-skuinventorybatches-resource) object (read-only) | Current inventory per batch | | inventory\_per\_warehouse | Array of [SkuInventoryPerWarehouse](#the-skuinventoryperwarehouse-resource) object (read-only) | Current inventory per warehouse | | merchant\_sku\_id\* | String | SKU code as provided by the merchant | | name\* | String | Name of this SKU | | un\_names | Array of String (ready-only) | Dangerous good UN Numbers | | status | String (read-only) |

Valid values:
active, deleted

| | weight\_in\_kg | Float | Weight of SKU in kilograms | {% hint style="info" %} \*Required properties when creating a new record. {% endhint %} ## The SkuInventory resource | Property | Type | Description | | -------- | ------------------- | ------------------------------------------------------------- | | reserved | Integer (read-only) | Quantity reserved for orders | | stocked | Integer (read-only) | Available for sale (minus any buffer quantity, if configured) | | total | Integer (read-only) | Available (will be equal to stocked if buffer is 0) | ## The SkuInventoryBatches resource | Property | Type | Description | | ------------------- | --------------------------------------------------------------------------------- | -------------------------------- | | expiry\_date | ISO8601 date (read-only) | Expiration date of the batch | | id | Integer (read-only) | Hive unique ID for the batch | | name | String (read-only) | Name of the batch | | stocked\_quantities | A [InventoryPerWarehouse](#the-inventoryperwarehouse-resource) object (read-only) | Available for sale per warehouse | | tracking\_code | String (read-only) | Tracking code | ## The SkuInventoryPerWarehouse resource | Property | Type | Description | | ------------- | ------------------- | ------------------------------------------------------------- | | reserved | Integer (read-only) | Quantity reserved for orders | | stocked | Integer (read-only) | Available for sale (minus any buffer quantity, if configured) | | total | Integer (read-only) | Available (will be equal to stocked if buffer is 0) | | warehouse\_id | Integer (read-only) | Hive's unique warehouse ID | ## The InventoryPerWarehouse resource | Property | Type | Description | | ------------- | ------------------- | -------------------------- | | quantity | Integer (read-only) | Available for sale | | warehouse\_id | Integer (read-only) | Hive's unique warehouse ID | ## List all SKUs `GET` `https://app.hive.app/merchant_api/v1/skus` Returns SKUs ordered by descending creation time. #### Query Parameters | Name | Type | Description | | --------------------- | ---------------- | ----------------------------------------------------------------------------------- | | merchant\_sku\_ids\[] | String\[] | Allow to filters skus by merchant\_sku\_id | | 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": 9, "merchant_sku_id": "2218061549136", "name": "Morph II", "created_at": "2022-08-10T17:53:04.822+02:00", "cost_in_cents": null, "country_code_of_origin": null, "hs_code": null, "barcode": "2218061549136", "batch_tracking_enabled": true, "fulfilled_by": "hive", "weight_in_kg": 45.37, "image_url": "http://example.com/image.png", "status": "active", "dangerous_good": true, "un_numbers": ["UN3481"], "hazardous_good": false, "h_codes": [], "inventory": { "stocked": 10000, "reserved": 0, "total": 10000 }, "inventory_per_warehouse": [ { "warehouse_id": 22, "stocked": 6720, "reserved": 0, "total": 6720 }, { "warehouse_id": 65, "stocked": 3240, "reserved": 0, "total": 3240 }, { "warehouse_id": 38, "stocked": 40, "reserved": 0, "total": 40 } ], "inventory_batches": [ { "id": 827, "name": "Morph II - 827", "tracking_code": "A01234", "expiry_date": "2023-12-30", "stocked_quantities": [ { "warehouse_id": 22, "quantity": 6720 }, { "warehouse_id": 65, "quantity": 3240 } ] }, { "id": 674, "name": "Morph II - 674", "tracking_code": "B56789", "expiry_date": null, "stocked_quantities": [ { "warehouse_id": 38, "quantity": 40 } ] } ] }, { "id": 4, "merchant_sku_id": "4976808834423", "name": "Mr Moonstone", "created_at": "2022-08-10T17:53:04.507+02:00", "cost_in_cents": null, "country_code_of_origin": null, "hs_code": null, "barcode": "2218061549136", "batch_tracking_enabled": false, "fulfilled_by": "hive", "weight_in_kg": 24.92, "image_url": "http://example.com/image.png", "status": "active", "dangerous_good": true, "un_numbers": ["UN3481"], "hazardous_good": false, "h_codes": [], "inventory": { "stocked": 10000, "reserved": 0, "total": 10000 }, "inventory_per_warehouse": [ { "warehouse_id": 22, "stocked": 10000, "reserved": 0, "total": 10000 }, { "warehouse_id": 65, "stocked": 0, "reserved": 0, "total": 0 } ], "inventory_batches": [] } ], "pagination": { "current_page": 1, "item_count": 2, "page_count": 1, "items_per_page": 20 } } ``` {% endtab %} {% endtabs %} ## Create a new SKU `POST` `https://app.hive.app/merchant_api/v1/skus` #### Request Body | Name | Type | Description | | --------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------- | | name\* | String | A human-readable name or title | | merchant\_sku\_id\* | String | An ID that uniquely identifies this SKU | | cost\_in\_cents | Integer | The cost (not price) of this SKU | | country\_code\_of\_origin | String | 2-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) code of country of origin | | hs\_code | String | [Harmonized System](https://en.wikipedia.org/wiki/Harmonized_System) code | | weight\_in\_kg | Float | Weight in kilograms | | image\_url | String | Image of the product, must be publicly accessible. | | barcode | String | The SKU barcode | | batch\_tracking\_enabled | Boolean | Enables inventory tracking per batch (defaults to false if omitted) | {% tabs %} {% tab title="201: Created The SKU was created successfully" %} ```json { "id": 34, "merchant_sku_id": "HIVE_TSH_BLK_M", "name": "Hive T-Shirt (Black - M)", "barcode": "2218061549136", "batch_tracking_enabled": false, "fulfilled_by": "new", "created_at": "2022-08-10T17:53:04.438+02:00", "cost_in_cents": null, "country_code_of_origin": null, "hs_code": null, "weight_in_kg": 0.3, "image_url": "http://example.com/image.png", "status": "active", "dangerous_good": true, "un_numbers": ["UN3481"], "hazardous_good": false, "h_codes": [], "inventory": { "stocked": 10000, "reserved": 0, "total": 10000 }, "inventory_per_warehouse": [ { "warehouse_id": 22, "stocked": 10000, "reserved": 0, "total": 10000 }, { "warehouse_id": 65, "stocked": 0, "reserved": 0, "total": 0 } ], "inventory_batches": [] } ``` {% 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": [ "Name can't be blank", "Merchant sku can't be blank" ] } ``` {% endtab %} {% endtabs %} ## Update an SKU `PATCH` `https://app.hive.app/merchant_api/v1/skus/{id}` #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------- | ---------------------------------- | | id\* | Integer | The (Hive) ID of the SKU to update | #### Request Body | Name | Type | Description | | ------------------------- | ------- | ----------------------------------------------------------------------------------------- | | merchant\_sku\_id | String | An ID that uniquely identifies this SKU | | name | String | A human-readable name or title | | cost\_in\_cents | Integer | The cost (not price) of this SKU | | country\_code\_of\_origin | String | 2-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) code of country of origin | | hs\_code | String | [Harmonized System](https://en.wikipedia.org/wiki/Harmonized_System) code | | weight\_in\_kg | Float | Weight in kilograms | | image\_url | String | Image of the product, must be publicly accessible. | | barcode | String | The SKU barcode | | batch\_tracking\_enabled | Boolean | Enables inventory tracking per batch | {% tabs %} {% tab title="200: OK The SKU was updated successfully" %} ```json { "id": 4, "merchant_sku_id": "SKU_4", "name": "Mr Moonstone", "barcode": "2218061549136", "batch_tracking_enabled": true, "fulfilled_by": "hive", "created_at": "2022-08-10T17:53:04.507+02:00", "cost_in_cents": null, "country_code_of_origin": null, "hs_code": null, "weight_in_kg": 24.92, "image_url": "http://example.com/image.png", "status": "active", "dangerous_good": true, "un_numbers": ["UN3481"], "hazardous_good": false, "h_codes": [], "inventory": { "stocked": 10000, "reserved": 0, "total": 10000 }, "inventory_per_warehouse": [ { "warehouse_id": 22, "stocked": 10000, "reserved": 0, "total": 10000 }, { "warehouse_id": 65, "stocked": 0, "reserved": 0, "total": 0 } ], "inventory_batches": [ { "id": 579, "name": "Mr Moonstone - 579", "tracking_code": "A01234", "expiry_date": "2023-12-30", "stocked_quantities": [ { "warehouse_id": 22, "quantity": 10000 } ] } ] } ``` {% endtab %} {% tab title="404: Not Found There was no SKU matching the given ID" %} ```json { "success": false, "errors": [ "record not found" ] } ``` {% endtab %} {% tab title="422: Unprocessable Entity The data was invalid" %} ```json { "success": false, "errors": [ "Name can't be blank" ] } ``` {% endtab %} {% tab title="400: Bad Request The request was malformed" %} ```json { "success": false, "errors": [ "bad request" ] } ``` {% endtab %} {% endtabs %} ## Batch upsert SKUs `POST` `https://app.hive.app/merchant_api/v1/skus/bulk_upsert` For each item in the provided list, it creates an SKU if it does not exist yet on our side, updates if it already exists. The endpoint accepts up to 100 items in the `skus` key of the request body. At least one should be provided. Each item should have the same structure as in the `POST /skus` endpoint. All fields except `name` and `merchant_sku_id` are optional. If any field of an existing SKU already has a value set on our side (e.g. `cost_in_cents=100`) and you omit that field in the request, it will be set to `null` on our side. However, if `batch_tracking_enabled` is omitted in the request, its existing value will remain unchanged. To update `batch_tracking_enabled`, you must include it explicitly (`true`/`false`) in the request body. #### Request Body | Name | Type | Description | | -------------------------------------- | --------- | ----------------------- | | skus\* | Object\[] | List of SKUs for upsert | {% tabs %} {% tab title="200: OK All SKUs were upserted successfully" %} ```json { "data": [ { "id": 12, "name": "Millenium Falcon", "country_code_of_origin": "DE", "hs_code": "567890", "created_at": "2023-04-25T22:12:16.123+02:00", "cost_in_cents": 110000, "weight_in_kg": 50.0, "merchant_sku_id": "2B", "image_url": "https://example.org/sw_merch/images/1.png", "status": "active", "barcode": "33444", "batch_tracking_enabled": false, "fulfilled_by": "new", "dangerous_good": true, "un_numbers": ["UN3481"], "hazardous_good": false, "h_codes": [], "inventory": { "stocked": 0, "reserved": 0, "total": 0 }, "inventory_per_warehouse": [ { "warehouse_id": 22, "stocked": 0, "reserved": 0, "total": 0 } ], "inventory_batches": [] }, { "id": 11, "name": "Staff of Gandalf", "country_code_of_origin": "FR", "hs_code": "123456", "created_at": "2023-04-25T22:12:16.456+02:00", "cost_in_cents": 42000, "weight_in_kg": 2.0, "merchant_sku_id": "1A", "image_url": "https://example.org/lotr_merch/images/1.png", "status": "active", "barcode": "11222", "batch_tracking_enabled": true, "fulfilled_by": "hive", "dangerous_good": true, "un_numbers": ["UN3481"], "hazardous_good": false, "h_codes": [], "inventory": { "stocked": 0, "reserved": 0, "total": 0 }, "inventory_batches": [] } ] } ``` {% endtab %} {% tab title="400: Bad Request Incorrect request body format" %} ```json { "success": false, "errors": [ "Pass array with at least one item for upsert by 'skus' key" ] } ``` {% endtab %} {% tab title="400: Bad Request Too many items are passed" %} ```json { "success": false, "errors": [ "Disallowed to pass more than 100 items at once" ] } ``` {% endtab %} {% tab title="422: Unprocessable Entity Some of passed SKUs is invalid" %} ```json { "success": false, "errors": [ "Name can't be blank" ] } ``` {% endtab %} {% endtabs %} ## Delete an SKU `DELETE` `https://app.hive.app/merchant_api/v1/skus/{id}` Marks an active SKU as "deleted". Will be set back to "active" on next create, update or batch upsert of that sku. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------- | ---------------------------------- | | id\* | Integer | The (Hive) ID of the SKU to delete | {% tabs %} {% tab title="204: No Content The SKU was deleted successfully" %} {% endtab %} {% tab title="404: Not Found There was no SKU matching the given ID or it is already deleted" %} {% endtab %} {% endtabs %} # Orders ## The Order resource | Property | Type | Description | | ----------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes), 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. For Cash on Delivery orders, use 'COD'. When payment\_method contains 'COD', total\_price\_in\_cents must be greater than 0. | | 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. 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

| | 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 | Destination country code of shipment in [ISO 3166 2-letter format](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | | 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](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes), defaults to "EUR" if not provided | {% tabs %} {% tab title="200: OK The order was updated successfully" %} ```javascript { "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="404: Not Found There was no order matching the given ID" %} ```json { "success": false, "errors": [ "record not found" ] } ``` {% endtab %} {% tab title="422: Unprocessable Entity The data was invalid" %} ```json { "success": false, "errors": [ "Merchant order can't be blank" ] } ``` {% endtab %} {% endtabs %} ## Cancel an order ## Cancels an order `PUT` `https://app.hive.app/merchant_api/v1/orders/{id}/cancel` #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------- | ----------- | | id\* | Integer | | {% tabs %} {% tab title="200: OK The order was cancelled successfully" %} ```javascript { "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="404: Not Found There was no order matching the given ID" %} ```javascript { "success": false, "errors": [ "record not found" ] } ``` {% endtab %} {% endtabs %} # Shipments ## The Shipment resource
PropertyTypeDescription
created_atISO8601 datetimeWhen the shipment was created
delivered_atISO8601 datetimeWhen the shipment was delivered
delivery_statusString

Information transmitted to the carrier - the shipment has been marked as shipped by Hive but no further statuses from the carrier yet

In transit - the parcel is on the way to the carrier hub

Out for delivery - the parcel has left the carrier hub and is in the process of being delivered

Delivered - the parcel has been successfully delivered

Returned to sender - the carrier initiated a return to the sender

Action required - the parcel is going through an unconventional event (e.g. failed delivery attempt, shipment lost, address issues etc.)

idIntegerThe shipment's unique identifier in Hive
itemsArray of ShipmentItem objectsWhich line items this shipment includes
merchant_order_idStringRelated order's unique identifier provided by merchant
order_idIntegerRelated order's unique identifier in Hive
shipment_providerStringName of the shipment provider/carrier
shipped_atISO8601 datetimeWhen the shipment was shipped
statusString

waiting_for_picking - initial status (normally shipment is created with this status during order import)

on_hold - shipment is on hold for now, for example because shop is configured to start fulfillment in future or there are some issues (e.g. incorrect address or not enough inventory amount)

picking_assigned - fulfillment center employee assigned themselves to pick this shipment's items

in_picking - shipment items picking process has been started

picked - shipment items have been picked and are ready for packing

in_packing - shipment items packing process has been started

packed - shipment items have been packed and are ready for shipping

in_shipping - shipping process has been started

shipped - a shipping label has been created for the shipment and it has left the packing station (and now the shipment is awaiting carrier pickup or is already picked up)

cancelled - shipment is cancelled and will not be fulfilled, e.g. because the order was cancelled via Merchant API

tracking_numberStringTracking number assigned by the shipment provider/carrier
tracking_urlStringShipment provider website showing tracking information
updated_atISO8601 datetimeWhen the shipment was updated
## The ShipmentItem resource
PropertyTypeDescription
batchesArray of ShipmentItemBatch objectsWhich batches were sent for this line item
idIntegerThe shipment item's unique identifier in Hive
merchant_item_idStringThe order line item identifier as provided by the merchant. Will be nullfor items added later (e.g. via add-on rules).
quantityIntegerNumber of SKUs in this line item
serial_numbersArray of ShipmentItemSerialNumber objectsWhich serial numbers were sent for this line item
skuA ShipmentItemSku objectSKU identifiers of this line item
## The ShipmentItemBatch resource
PropertyTypeDescription
expiry_dateISO8601 dateExpiration date of the batch
nameStringName of the batch
quantityIntegerNumber of items taken from this batch
tracking_codeStringTracking code of the batch
## The ShipmentItemSerialNumber resource | Property | Type | Description | | -------------- | ------ | ----------------- | | serial\_number | String | The serial number | ## The ShipmentItemSku resource | Property | Type | Description | | ----------------- | ------- | ------------------------------------------ | | id | Integer | Hive unique identifier for the SKU | | merchant\_sku\_id | String | SKU identifier as provided by the merchant | ## List all shipments ## Lists all shipments of an order `GET` `https://app.hive.app/merchant_api/v1/shipments` Returns shipments ordered by descending creation time. #### Query Parameters
NameTypeDescription
order_idIntegerThe (Hive) ID of the order
created_at[lt]ISO8601 datetimeReturn results where the created_at field is less than this value.
created_at[lte]ISO8601 datetimeReturn results where the created_at field is less than or equal to this value.
created_at[gt]ISO8601 datetimeReturn results where the created_at field is greater than this value.
created_at[gte]ISO8601 datetimeReturn results where the created_at field is greater than or equal to this value.
{% tabs %} {% tab title="200: OK " %} ```json { "data": [ { "created_at": "2022-06-04T03:17:25.533+02:00", "delivered_at": "2022-06-06T22:17:46.000+02:00", "delivery_status": "Delivered", "id": 170, "items": [ { "batches": [ { "expiry_date": "2023-06-04", "name": "Batch 1", "quantity": 1, "tracking_code": "ABC123" } ], "id": 201, "merchant_item_id": "QWERTY0987", "quantity": 1, "serial_numbers": [ { "serial_number": "1234567890" } ], "sku": { "id": 123000, "merchant_sku_id": "ABC123" } }, { "batches": [], "id": 202, "merchant_item_id": "QWERTY6543", "quantity": 2, "serial_numbers": [], "sku": { "id": 123001, "merchant_sku_id": "DEF456" } } ], "merchant_order_id": "20220604-383", "order_id": 575, "shipment_provider": "DHL", "shipped_at": "2022-06-04T07:53:20.511+02:00", "status": "shipped", "tracking_number": "CR123456789DE", "tracking_url": "https://www.dhl.de/en/privatkunden/dhl-sendungsverfolgung.html?piececode=CR123456789DE", "updated_at": "2022-07-22T16:53:31.388+02:00" } ], "pagination": { "current_page": 1, "item_count": 2, "page_count": 1, "items_per_page": 20 } } ``` {% endtab %} {% tab title="404: Not Found There was no order matching the given ID" %} ```json { "success": false, "errors": [ "record not found" ] } ``` {% endtab %} {% endtabs %} # Warehouses ## The Warehouse resource
PropertyTypeDescription
cityString (read-only)City where the warehouse is located
countryString (read-only)Country 2-letter ISO 3166-1 code where the warehouse is located
idInteger (read-only)Hive unique ID
nameString (read-only)Name of the warehouse
## List all warehouses ## Lists all warehouses `GET` `https://app.hive.app/merchant_api/v1/warehouses` Returns all merchant's warehouses. {% tabs %} {% tab title="200: OK " %} ```json { "data": [ { "id": 1, "name": "Office", "country": "DE", "city": "Berlin" }, { "id": 71, "name": "Ms. Dale Wyman", "country": "VI", "city": "Rippintown" }, { "id": 72, "name": "Ilana Graham", "country": "ML", "city": "Armstrongshire" } ] } ``` {% endtab %} {% endtabs %} # Restocking Shipments ## The RestockingShipment resource
PropertyTypeDescription
barcodeString (read-only)The barcode of the shipment
delivery_option*StringOne of the following: postal, courier, dropoff, hive_freight
estimated_arrival_date*ISO8601 dateEstimated arrival date
idInteger (read-only)Hive's unique identifier
po_numberStringPurchase order number
restocking_shipment_itemsAn array of RestockingShipmentItem objectsA list of items in the shipment
statusString (read-only)

Possible values:

shipped - initial status meaning that restocking shipment is on the way

delivered - the restocking shipment is delivered to the fulfillment center, but its content is not verified yet

arrived - Hive completed the arrival documentation, checked packing slip, picture of shipment and documents are uploaded

processing - the restocking shipment is getting unpacked and its items are getting restocked into storage boxes and pallets

restocked - the restocking shipment is fully processed in the fulfillment center and its items are completely restocked

cancelled - the restocking shipment is cancelled by merchant

supplier_nameStringSupplier name
tracking_codeStringShipment tracking code
warehouse_id*IntegerThe ID of the Hive destination warehouse
## The RestockingShipmentItem resource
PropertyTypeDescription
announced_quantityIntegerQuantity of this item in the shipment
arrived_quantityInteger (read-only)Arrived quantity of this item (after shipment is received)
restocked_quantityInteger (read-only)Quantity put back into sellable stock. Matches the "restocked" figure shown in Hive's Portal, and equals the sum of the per-batch arrived_quantity values in inventory_batches.
damaged_quantityInteger (read-only)Damaged quantity of this item (after shipment is received)
idInteger (read-only)Hive's unique identifier
inventory_batchesA RestockingShipmentInventoryBatch objectBatches of this item included in the shipment
merchant_sku_idStringThe merchant's SKU identifier - required if sku_id is not provided
missing_quantityInteger (read-only)Missing quantity of this item (after shipment is received)
remarksStringFree text for remarks
sku_idIntegerHive SKU identifier - required if merchant_sku_id is not provided
total_cost_in_centsIntegerCost in cents
## The RestockingShipmentInventoryBatch resource
PropertyTypeDescription
arrived_quantityInteger (read-only)Arrived quantity of this batch (after shipment is received)
expiry_dateISO8601 date (read-only)Expiration date of the batch
idInteger (read-only)Hive's unique identifier
nameString (read-only)Batch name
tracking_codeString (read-only)Batch tracking code
{% hint style="info" %} \*Required properties when creating a new record. {% endhint %} ## List all restocking shipments ## List all Restocking Shipments `GET` `https://app.hive.app/merchant_api/v1/restocking_shipments` Returns restocking shipments ordered by descending creation time. {% tabs %} {% tab title="200: OK " %} note: `arrived_quantity`, `damaged_quantity` and `missing_quantity` are visible only if the status is `restocked` ```json { "data": [ { "id": 13, "merchant_id": 1, "warehouse_id": 71, "estimated_arrival_date": "2022-12-01", "delivery_option": "postal", "tracking_code": "1234567", "po_number": null, "supplier_name": null, "status": "restocked", "barcode": "RS.13", "restocking_shipment_items": [ { "id": 15, "sku_id": 558, "announced_quantity": 10, "arrived_quantity": 2, "damaged_quantity": 1, "missing_quantity": 7, "remarks": null, "total_cost_in_cents": null, "inventory_batches": [ { "id": 827, "name": "Morph II - 827", "tracking_code": "A01234", "expiry_date": "2023-12-30", "arrived_quantity": 3 }, { "id": 828, "name": "Morph II - 828", "tracking_code": "B56789", "expiry_date": "2024-02-15", "arrived_quantity": 1 } ] } ] } ], "pagination": { "current_page": 1, "item_count": 1, "page_count": 1, "items_per_page": 20 } } ``` {% endtab %} {% endtabs %} ## Get one restocking shipment ## Get one restocking shipment `GET` `https://app.hive.app/merchant_api/v1/restocking_shipments/{id}` #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------ | ---------------------------------------- | | id\* | String | The (Hive) ID of the restocking shipment | {% tabs %} {% tab title="200: OK " %} ```json { "id": 13, "merchant_id": 1, "warehouse_id": 71, "estimated_arrival_date": "2022-12-01", "delivery_option": "postal", "tracking_code": "1234567", "po_number": null, "supplier_name": null, "status": "shipped", "barcode": "RS.13", "restocking_shipment_items": [ { "id": 15, "sku_id": 558, "announced_quantity": 10, "arrived_quantity": 2, "damaged_quantity": 1, "missing_quantity": 7, "remarks": null, "total_cost_in_cents": null, "inventory_batches": [ { "id": 827, "name": "Morph II - 827", "tracking_code": "A01234", "expiry_date": "2023-12-30", "arrived_quantity": 3 }, { "id": 828, "name": "Morph II - 828", "tracking_code": "B56789", "expiry_date": "2024-02-15", "arrived_quantity": 1 } ] } ] } ``` {% endtab %} {% tab title="404: Not Found There was no restocking shipment matching the given ID" %} ```json { "success": false, "errors": [ "record not found" ] } ``` {% endtab %} {% endtabs %} ## Create a new restocking shipment ## Creates a new restocking shipment `POST` `https://app.hive.app/merchant_api/v1/restocking_shipments/` #### Request Body | Name | Type | Description | | --------------------------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------- | | warehouse\_id\* | Integer | An ID that uniquely identifies the warehouse | | estimated\_arrival\_date\* | ISO8601 datetime | The estimated arrival date | | delivery\_option\* | String | The delivery option, must be one of: `postal`, `courier`, `dropoff`, `hive_freight` | | tracking\_code | String | The shipment tracking code | | po\_number | String | The po number | | supplier\_name | String | The supplier name | | restocking\_shipment\_items.sku\_id\* | Integer | The (Hive) ID of the sku | | restocking\_shipment\_items.announced\_quantity\* | Integer | The sku quantity | | restocking\_shipment\_items.remarks | String | The remarks | | restocking\_shipment\_items.total\_cost\_in\_cents | Integer | The total cost in cents of the | {% tabs %} {% tab title="201: Created The restocking shipment was created successfully" %} ```json { "id": 16, "merchant_id": 1, "warehouse_id": 71, "estimated_arrival_date": "2022-12-01", "delivery_option": "postal", "tracking_code": null, "po_number": null, "supplier_name": null, "status": "shipped", "barcode": "RS.16", "restocking_shipment_items": [ { "id": 18, "sku_id": 558, "announced_quantity": 12, "remarks": null, "total_cost_in_cents": 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": [ "Warehouse can't be blank" ] } ``` {% endtab %} {% endtabs %} ## Update a restocking shipment ## Update a restocking shipment `PUT` `https://app.hive.app/merchant_api/v1/restocking_shipments/{id}/` Replaces the whole resource. \ The restocking shipment can be updated only if the status is `shipped` or `created` #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------- | ---------------------------------------- | | id\* | Integer | The (Hive) ID of the restocking shipment | #### Request Body | Name | Type | Description | | --------------------------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------- | | warehouse\_id\* | Integer | An ID that uniquely identifies the wharehouse | | estimated\_arrival\_date\* | ISO8601 datetime | The estimated arrival date | | delivery\_option\* | String | The delivery option, must be one of: `postal`, `courier`, `dropoff`, `hive_freight` | | tracking\_code | String | The shipment tracking code | | po\_number | String | The po number | | supplier\_name | String | The supplier name | | restocking\_shipment\_items.sku\_id\* | Integer | The (Hive) ID of the sku | | restocking\_shipment\_items.announced\_quantity\* | Integer | The sku quantity | | restocking\_shipment\_items.remarks | String | The remarks | | restocking\_shipment\_items.total\_cost\_in\_cents | Integer | The total cost in cents of the | {% tabs %} {% tab title="200: OK The restocking shipment was updated successfully" %} ```json { "id": 16, "merchant_id": 1, "warehouse_id": 71, "estimated_arrival_date": "2022-12-01", "delivery_option": "postal", "tracking_code": null, "po_number": null, "supplier_name": null, "status": "shipped", "barcode": "RS.16", "restocking_shipment_items": [ { "id": 18, "sku_id": 558, "announced_quantity": 12, "remarks": null, "total_cost_in_cents": 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": [ "Warehouse can't be blank" ] } ``` {% endtab %} {% endtabs %} ## Cancel a restocking shipment ## Cancel a restocking shipment `PUT` `https://app.hive.app/merchant_api/v1/restocking_shipments/{id}/cancel` The restocking shipment can be canceled only if the status is `shipped` or `created` #### Query Parameters | Name | Type | Description | | ------------------------------------ | ------- | ---------------------------------------- | | id\* | Integer | The (Hive) ID of the restocking shipment | {% tabs %} {% tab title="200: OK The restocking shipment was canceled successfully" %} {% endtab %} {% tab title="422: Unprocessable Entity The data was invalid" %} ```json { "success": false, "errors": [ "Cannot cancel a restocking shipment with status arrived" ] } ``` {% endtab %} {% endtabs %} # Returns ## The Return resource
PropertyTypeDescription
carrierStringCarrier name
completed_handling_atISO8601 datetimeWhen the return handling finished
created_atISO8601 datetimeWhen the return was created
idIntegerHive's unique identifier
orderA ReturnOrder objectDetails of the associated order
photosAn array of ReturnPhoto objectsPhotos of the returned items
received_atISO8601 datetimeWhen the return was received
return_itemsAn array of ReturnItem objectsList of items announced by the customer (via the Customer Portal). Can be empty if the return is not a Customer Portal return.
return_line_itemsAn array of ReturnLineItem objectsList of items that were actually handled in the FC. Can be empty if return items have not been handled in the FC yet.
return_reasonString

Possible values:

customer_return

not_picked_up

invalid_address

rejected_by_customer

customs_documents_missing

other

null or empty string

return_reason_typeString

Possible values:
active - customer return (the end-customer actively shipped the return)

passive - carrier return (the end-customer never touched the parcel - it was shipped back by the carrier for reasons such as invalid address, the customer didn’t pick up their parcel from the shop or requested that it be sent back before receiving it, damages, customs documents missing, etc.)

null or empty string - this happens in the rare case that a return is created before it’s processed and it is not a Customer Portal return, all Customer Portal returns are "active"

started_processing_atISO8601 datetimeWhen processing at the fulfillment center started
statusString

Possible values:
on_the_way - is on the way to a fulfillment center

arrived - arrived to a fulfillment center

processing - the return processing is in progress

action_required - waiting for merchant guidance

handling_completed - the return processing is in completed

tracking_codeStringTracking number assigned by the carrier
tracking_urlStringCarrier website showing tracking information
## The ReturnItem resource | Property | Type | Description | | ------------------------- | ----------------------------------------------- | --------------------------------------- | | customer\_return\_message | String | Reason details provided by the customer | | customer\_return\_reason | String | Reason provided by the customer | | id | Integer | Hive's unique identifier | | quantity | Integer | Quantity of items announced | | sku | A [ReturnSku](#the-returnedsku-resource) object | SKU details of the item | ## The ReturnLineItem resource
PropertyTypeDescription
conditionStringPossible values:
A - Unused and in original packaging.
B - Unused with missing/damaged packaging.
C - Product is used or damaged.
follow_up_actionStringAction to be performed on the returned item. Possible values: restock, dispose and send_back
Those actions are pre-selected based on return rules (Hive account manager inserts return rules into the system after negotiation with a merchant).
idIntegerHive's unique identifier
inventory_batch_idIntegerUnique identifier in Hive system of the inventory batch (if present) into which returned item is going to be restocked (relevant only when "follow_up_action": "restock")
photosArray of ReturnLineItemPhoto objectsPhotos of the returned item
return_item_idIntegerAnnounced return item's unique identifier in Hive system (can be blank, e.g. when the return is not a Customer Portal return)
skuA ReturnSku objectSKU details of the item
quantityIntegerThe quantity of items returned for the same SKU
## The ReturnSku resource | Property | Type | Description | | ----------------- | ------- | -------------------------------- | | id | Integer | Hive's unique SKU identifier | | merchant\_sku\_id | String | Merchant's unique SKU identifier | ## The ReturnOrder resource
PropertyTypeDescription
idIntegerHive's unique order identifier
merchant_order_idStringMerchant's unique order identifier
nameStringCustomer's order identifier
## The ReturnPhoto resource
PropertyTypeDescription
idIntegerHive's unique identifier
image_urlStringPublicly accessible URL (for 15 minutes)
photo_typeStringType of photo. Usual values: inside or outside
## The ReturnLineItemPhoto resource
PropertyTypeDescription
idIntegerHive's unique identifier
image_urlStringPublicly accessible URL (for 15 minutes)
## List all returns ## Lists all order returns `GET` `https://app.hive.app/merchant_api/v1/returns` Returns paginated order returns 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": 70047, "return_reason_type": "active", "return_reason": "customer_return", "status": "handling_completed", "created_at": "2023-05-18T09:38:18.999+02:00", "received_at": "2023-05-19T10:38:18.999+02:00", "started_processing_at": "2023-05-20T11:38:18.999+02:00", "completed_handling_at": "2023-05-21T12:38:18.999+02:00", "tracking_code": "TC123456789", "tracking_url": "https://example.org/package?trackingNumber=TC123456789", "carrier": "ExampleCarrier", "order": { "id": 1230221, "merchant_order_id": "60423b95-23b5-4e5b-aa1c-6a71bd90b106", "name": "#DE12345" }, "photos": [ { "id": 115234, "photo_type": "outside", "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703678.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591" }, { "id": 115235, "photo_type": "inside", "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703679.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591" } ], "return_items": [ { "id": 27890, "quantity": 1, "customer_return_reason": "incorrect_product_arrived", "customer_return_message": "I ordered red pencil but got green one", "sku": { "id": 123085, "merchant_sku_id": "ABC123" } } ], "return_line_items": [ { "id": 10456, "inventory_batch_id": 123, "return_item_id": 27890, "condition": "A", "follow_up_action": "restock", "photos": [ { "id": 117781, "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703467.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591" } ], "sku": { "id": 123085, "merchant_sku_id": "ABC123" }, "quantity": 1 } ] } ], "pagination": { "current_page": 1, "item_count": 1, "items_per_page": 20, "page_count": 1 } } ``` {% endtab %} {% endtabs %} ## Get one return ## Get one specific order return `GET` `https://app.hive.app/merchant_api/v1/returns/{id}` Returns specific order return belonging to the merchant and with matching Hive ID #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------- | --------------------------- | | id\* | Integer | The (Hive) ID of the return | {% tabs %} {% tab title="200: OK " %} ```json { "id": 70047, "return_reason_type": "active", "return_reason": "customer_return", "status": "handling_completed", "created_at": "2023-05-18T09:38:18.999+02:00", "received_at": "2023-05-19T10:38:18.999+02:00", "started_processing_at": "2023-05-20T11:38:18.999+02:00", "completed_handling_at": "2023-05-21T12:38:18.999+02:00", "tracking_code": "TC123456789", "tracking_url": "https://example.org/package?trackingNumber=TC123456789", "carrier": "ExampleCarrier", "order": { "id": 1230221, "merchant_order_id": "60423b95-23b5-4e5b-aa1c-6a71bd90b106" }, "photos": [ { "id": 115234, "photo_type": "outside", "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703678.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591" }, { "id": 115235, "photo_type": "inside", "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703679.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591" } ], "return_items": [ { "id": 27890, "quantity": 1, "customer_return_reason": "incorrect_product_arrived", "customer_return_message": "I ordered red pencil but got green one", "sku": { "id": 123085, "merchant_sku_id": "ABC123" } } ], "return_line_items": [ { "id": 10456, "inventory_batch_id": 123, "return_item_id": 27890, "condition": "A", "follow_up_action": "restock", "photos": [ { "id": 117781, "image_url": "https://hive-production-images.s3.eu-central-1.amazonaws.com/a67e41b5fbfcf12264b3b4f704703467.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIA4LNZPVPUBMDZA65F%2F20230525%2Feu-central-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20230525T083045Z\u0026X-Amz-Expires=900\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d8e308229c3ee3e48d637f45e1594c5e47cf69e6b3b69c008e29685b8fcd3591" } ], "sku": { "id": 123085, "merchant_sku_id": "ABC123" }, "quantity": 1 } ] } ``` {% endtab %} {% endtabs %} # Webhooks Webhooks allow merchants to be notified of significant events. For example, when the delivery status of a shipment changes. When an webhook-supporting event happens, an HTTP POST request will be sent to the URL of your choice. To set up webhooks, ask your account manager. You need to provide the URL which handles the webhooks. The following table shows the supported events and the type of payload which will be sent in the request:
Event typeDescriptionPayload
delivery_status_updatedThe delivery status of a shipment has changedShipment object
shipment_status_updatedThe status of a shipment has changedShipment object
restocking_shipment_status_updatedThe delivery status of a restocking shipment has changedRestocking shipment object
return_status_updatedThe delivery status of a return has changedReturn object
{% hint style="info" %} The provided webhook URLs should be idempotent. We cannot guarantee the order of the calls neither the retries attempts for the same call. What this means in practice, is that you should check the timestamp of the object in the payload. Ignore payloads with a timestamp older than the last update you saved. Only process the webhook if the updated timestamp is newer than the one you have on file. {% endhint %} ## Security Hive signs all webhook requests to prevent malicious actors from sending invalid requests. Requests without the `x-hive-signature` HTTP request should be ignored. If the header is present, it should match the hex-encoded HMAC-SHA256 digest of the request body, with your API token as the key. Here's an example of how one would calculate the HMAC-SHA256 digest: {% tabs %} {% tab title="Ruby" %} ```ruby def request_valid?(req) # req is an instance of Rack::Request return false if !req.post? request_sig = req.get_header("x-hive-signature") expected_sig = OpenSSL::HMAC.hexdigest("sha256", ENV["API_TOKEN"], req.body) Rack::Utils.secure_compare(request_sig, expected_sig) end ``` {% endtab %} {% endtabs %}