Stock Operations

Stock operations can be created via the API to make adjustments to multiple SKU stock levels in a single request. You might POST to this API endpoint when an e-commerce order arrives and you want to reduce stock levels in Stitchex by the amount that is required to fulfill the online order.

Creating a stock operation

You can create a stock operation by sending a POST request to /stock_operations. The caller should provide the following headers along with the request:

Content-Type : application/json
Authorization: Bearer ACCESS_TOKEN

The body of your request should be a JSON document formatted as below.

{
  "stock_operation": {
    "source": "WooCom EU",
    "external_ref": "ORDER-123",
    "external_url": "https://store.example.com/admin/orders/123",
    "comments": "optional notes",
    "line_quantities": [
      {
        "sku_id": 1087631,
        "quantity": 1
      },
      {
        "sku_id": 1087632,
        "quantity": 2
      }
    ]
  },
  "idempotency_key" : "94e344e2-a766-4e73-8dfa-242aabf3de19"
}

The idempotency_key is used to avoid accidentally creating the same stock operation twice (as a result of an interrupted network connection or other unexpected error). If a second request is made for the same stock operation, with the same idempotency_key value, the second (and any subsequent) requests will return a success message but no additional stock operations will be created. The idempotency_key can be any value (up to 128 characters) that is unique to the operation you are performing. For example, if you are creating a stock operation as a result of an incoming e-commerce order, then the idempotency_key could be new-order-10032 where 10032 is the order number/identifier.

Populate the following values thoughtfully as they will be available for the users to see in the Stitchex stock operations page.

source
If you have transactions from different sources, source will help identify the origin of the transaction. A common example is orders from two different web stores.

external_ref
This can be any reference you would like to store with this stock operation. A good example is an order ID or order number.

external_url
This can be used to provide a link in the Stitchex stock operation back to any page that relates to the transaction. For example, you might provide the URL of the order page on your online store relating to the stock adjustment.

Responses

You will receive a 201 Created HTTP response if the entire stock operation was successfully created and the stock levels adjusted. A success response would look like this:

{ "status" : "created" }

If an error occurs (for example, a SKU wasn't found), no operation will be created and stock level adjustments will take place. You will receive a 422 HTTP response code and the body of the response will contain one or more error messages describing the problem. For example:

{ "errors" : ["first error message", "second error message"] }

You may receive a 5XX response in the case of connectivity problems or general server error. You should assume that this is a temporary error and retry the request later.

Next steps

Did this answer your question?