Creating stock orders via the API


Latest update: - Mikey Jarvis

Creating stock orders via the API requires a few steps to be completed successfully. This article presents those steps along with API endpoints and payload that need to be used. A corresponding article describing the same process from retailers perspective can be found here: How to order and receive stock.

This article includes:


New consignment

Step 1. Create a new consignment

A POST request to the /api/consignment endpoint.

Request payload:

{
	"name": "Order test 14th June 2015 API",
	"outlet_id": "b1e04bd8-f019-11e3-a0f5-b8ca3a64f8f4",
	"status": "OPEN",
	"type": "SUPPLIER"
}

Response payload:

{
	"id": "06bf537b-c783-11e6-f6b9-31cfaa5dcde8",
	"name": "Order test 14th June 2015 API",
	"consignment_date": "2016-06-14 01:31:06",
	"due_at": null,
	"received_at": null,
	"retailer_id": "b1c50056-f019-11e3-a0f5-b8ca3a64f8f4",
	"outlet_id": "b1e04bd8-f019-11e3-a0f5-b8ca3a64f8f4",
	"supplier_id": null,
	"source_outlet_id": null,
	"status": "OPEN",
	"type": "SUPPLIER",
	"accounts_transaction_id": null
}

Step 2. Add products to the consignment

A POST request to the /api/consignment_product endpoint for each product that you want to add.

Request payload:

{
	"consignment_id": "06bf537b-c783-11e6-f6b9-31cfaa5dcde8",
	"product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
	"count": 10,
	"cost": 1
}

Response payload:

{
    "id": "06bf537b-c783-11e6-f6b9-31d0cf5797c4",
    "consignment_id": "06bf537b-c783-11e6-f6b9-31cfaa5dcde8",
    "product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
    "count": 10,
    "received": null,
    "cost": 1,
    "sequence_number": 0
}

At this point it should be possible to check what products are added to the consignment by making a GET request to /api/consignment_product?consignment_id={id} endpoint with the consignment_id as a parameter.

{
    "consignment_products": [
        {
            "id": "06bf537b-c783-11e6-f6b9-31d0cf5797c4",
            "consignment_id": "06bf537b-c783-11e6-f6b9-31cfaa5dcde8",
            "product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
            "count": "10.00000",
            "received": null,
            "cost": 1,
            "sequence_number": 0
        }
    ]
}

Consignment sent

Step 3. Mark consignment as sent

A PUT request to the /api/consignment/:id endpoint.

Request payload:

{
	"id": "06bf537b-c783-11e6-f6b9-31cfaa5dcde8",
	"name": "Order test 14th June 2015 API",
	"consignment_date": "2016-06-14 01:31:06",
	"due_at": null,
	"received_at": null,
	"retailer_id": "b1c50056-f019-11e3-a0f5-b8ca3a64f8f4",
	"outlet_id": "b1e04bd8-f019-11e3-a0f5-b8ca3a64f8f4",
	"supplier_id": null,
	"source_outlet_id": null,
	"status": "SENT",
	"type": "SUPPLIER",
	"accounts_transaction_id": null
}

Response payload:

{
    "id": "06bf537b-c783-11e6-f6b9-31cfaa5dcde8",
    "name": "Order test 14th June 2015 API",
    "consignment_date": "2016-06-14 01:31:06",
    "due_at": null,
    "received_at": null,
    "retailer_id": "b1c50056-f019-11e3-a0f5-b8ca3a64f8f4",
    "outlet_id": "b1e04bd8-f019-11e3-a0f5-b8ca3a64f8f4",
    "supplier_id": null,
    "source_outlet_id": null,
    "status": "SENT",
    "type": "SUPPLIER",
    "accounts_transaction_id": null
}

Consignment received

Step 4. Set the received quantity

Note: This step can be skipped if all the steps are performed in quick succession. If that's the case the received attribute should be populated in step 2 when the product is added to the consignment. This step is only required if the time between marking the consignment as SENT and receiving it is substantial and the current state of the consignment needs to be correctly represented in the UI.

A PUT request to the /api/consignment_product/:id endpoint.

Request payload:

{
 	"id": "06bf537b-c783-11e6-f6b9-31d0cf5797c4",
 	"consignment_id": "06bf537b-c783-11e6-f6b9-31cfaa5dcde8",
 	"product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
 	"count": 10,
 	"received": 12,
 	"cost": 1,
 	"sequence_number": 0
 }

Note: Notice that the received attribute may be different than count.

Response payload:

{
	"id": "06bf537b-c783-11e6-f6b9-31d0cf5797c4",
	"consignment_id": "06bf537b-c783-11e6-f6b9-31cfaa5dcde8",
	"product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
	"count": 10,
	"received": 12,
	"cost": 1,
	"sequence_number": 0
}

Step 5. Mark the consignment as received

A PUT request to the /api/consignment/:id endpoint.

Request payload:

{
    "id": "06bf537b-c783-11e6-f6b9-31cfaa5dcde8",
    "name": "Order test 14th June 2015 API",
    "consignment_date": "2016-06-14 01:31:06",
    "due_at": null,
    "received_at": null,
    "retailer_id": "b1c50056-f019-11e3-a0f5-b8ca3a64f8f4",
    "outlet_id": "b1e04bd8-f019-11e3-a0f5-b8ca3a64f8f4",
    "supplier_id": null,
    "source_outlet_id": null,
    "status": "RECEIVED",
    "type": "SUPPLIER",
    "accounts_transaction_id": null
}

Response payload:

{
    "id": "06bf537b-c783-11e6-f6b9-31cfaa5dcde8",
    "name": "Order test 14th June 2015 API",
    "consignment_date": "2016-06-14 01:31:06",
    "due_at": null,
    "received_at": "2016-06-14 02:10:38",
    "retailer_id": "b1c50056-f019-11e3-a0f5-b8ca3a64f8f4",
    "outlet_id": "b1e04bd8-f019-11e3-a0f5-b8ca3a64f8f4",
    "supplier_id": null,
    "source_outlet_id": null,
    "status": "RECEIVED",
    "type": "SUPPLIER",
    "accounts_transaction_id": null
}

Note: Please, note that this status change triggers a background job which processes all the consignment products included in the consignment and in case of large consignments it can take even a few minutes to complete. If a GET request is made to the /api/consignment/:id endpoint before the background job completes, the status on in that payload may still be SENT.

Powered by Zendesk