Orders

The Order resource

Properties

id - the order's unique identifier in Hive system

merchant_order_id - the order's unique identifier provided by merchant

status - the order's status on Hive side in terms of fulfillment. Possible values:

Status options

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

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.

200: OK

{
    "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

Name	Type	Description
id*	Integer	The (Hive) ID of the order

200: OK

{
    "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
}

404: Not Found There was no order matching the given ID

{
  "success": false,
  "errors": [
    "record not found"
  ]
}

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, defaults to "EUR" if not provided

201: Created The order was created successfully

{
    "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
}

400: Bad Request The request was malformed

{
  "success": false,
  "errors": [
    "bad request"
  ]
}

422: Unprocessable Entity The data was invalid

{
    "success": false,
    "errors": [
        "Merchant order can't be blank",
        "Shipping address can't be blank",
        "Items can't be blank"
    ]
}

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
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

200: OK The order was updated successfully

{
    "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
}

400: Bad Request The request was malformed

{
  "success": false,
  "errors": [
    "bad request"
  ]
}

404: Not Found There was no order matching the given ID

{
  "success": false,
  "errors": [
    "record not found"
  ]
}

422: Unprocessable Entity The data was invalid

{
    "success": false,
    "errors": [
        "Merchant order can't be blank"
    ]
}

Cancel an order

Cancels an order

PUT https://app.hive.app/merchant_api/v1/orders/{id}/cancel

Path Parameters

Name	Type	Description
id*	Integer

200: OK The order was cancelled successfully

{
    "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
}

404: Not Found There was no order matching the given ID

{
  "success": false,
  "errors": [
    "record not found"
  ]
}