This reference is a comprehensive guide to understanding of Instock API and is aimed to help developers to integrate their Host system with Instock Cloud (Incloud).

Instock API is REST-based. It has predictable resource URLs, accepts JSON in the HTTP body, returns JSON-encoded responses, and uses standard HTTP response codes to indicate errors, methods and authentication. Our API uses GET, POST, PUT methods to perform all operations. GET method is both used for retrieval of a single or listing multiple objects at once.

• HTTPS is required for all requests. Requests over plain HTTP will fail.
• All requests without authentication will fail.
• Bulk request is supported only to upload articles into Incloud.
• Property names are in snake_case (not camelCase or kebab-case).
• Temporal values (datetimes) are encoded in RFC 3339 strings, e.g. 2022-06-06T12:37:00Z.
• All path parameters are always returned in response body, except for POST and PUT methods.

Instock API offers authentication in form of Bearer token. Bearer token must be present in each request header. The token provides a full access to all resources and methods of Instock API to its client.

Note: currently Bearer token is issued by Instock and supplied to API users during onboarding.

For example, if you'd like to retrieve sites available to your organization, your request will look like:

curl -X GET 
  -H 'Content-Type: application/json' \
  -H 'Authorization: {access_token}' \
  https://api.instock.com/v1/sites \

Instock API always returns errors in a common format. For example:

{
  "code": "bad_request",
  "message": "Request body/path/query params cannot be validated."
}

The code indicates the general class of error read by your Host system. The message is a human-readable explanation of what went wrong.

Common HTTP error code responses

Note: each endpoint below has samples of errors it may return.

Instock API auto-generates request identifier with each API response. You can find this value in the response headers as Instock-Request-ID. Use it to refer to a specific request when debugging or reaching out to Instock for support.

Instock-Request-ID: request_id

You can optionally extend your request and add Instock-Correlation-ID to the header. Use it to analyze incorrect and faulty behavior across your Host system. For example, if you'd like to retrieve sites available to your organization and pass Instock-Correlation-ID, your request will look like:

curl -X GET 
  -H 'Content-Type: application/json' \
  -H 'Authorization: your-token' \
  -H 'Instock-Correlation-ID: your-correlation-id' \
  https://api.instock.com/v1/sites \

Endpoints that return a list of objects use pagination. Instock API uses cursor-based pagination. This approach allows Host system to request a part of the list, receiving results and next_cursor in the response. The latter could be used to access the next part of the list.

Note: setting page_size lesser than 10 or greater than 1000 will yield an error.

Throughout API reference below, you will encounter multiple unique identifiers (UIDs) that are required to perform certain operations. For example, to create customer order, your Host system must:

• provide site_id to specify exact instance of Instock ASRS installation,
• and supply order_id. Usually order_id value corresponds to the ID of an order that Host system has.

The table below indicates source (which system issues UID) and scope (at what level UID must be unique).

Every article and order contain attributes, which are reserved for custom and pre-defined parameters that your organization may require for fulfillment-related operations.

Custom attributes

Before integration, your IT and Instock teams should agree upon attributes that will be configured specifically for your site(s). Incloud will consume these attributes to perform certain operations throughout fulfillment process, e.g. decanting, picking. Attributes can be added or updated in two ways: via API during operations such as customer order creation or through the workstation UI during operation at ASRS, like decanting.

Order attributes

For example, cutoff_time for a customer order — the time when order fulfillment starts, i.e. change its status from registered to reserved.

{
  "org_id": "org_id_001",
  "site_id": "1.1.0-1",
  "order_id": "order_id_001",
  "kind": "customer",
  "placed_at": "2022-03-05T07:38:39Z",
  "attributes": {
    "cutoff_time": "2022-03-05T16:00:00Z",
  },
  "lines": [
    {
      "line_id": "00132455-1",
      "article_id": "1003000031678",
      "qty": 1
    }
  ]
}

Another example involves adding an Advanced Shipping Notice ID (ASN ID) by an associate during decanting. This attribute can be retrieved via API in a reception order. This way, you'll be able to track reception in your system using the order attribute during decanting.

{
  "org_id": "org_id_001",
  "site_id": "1.1.0-1",
  "order_id": "8b72a983-c909-4dd6-b5d4-01d1f4b2a608",
  "kind": "reception",
  "placed_at": "2024-03-27T13:22:47Z",
  "attributes": {
      "org_id_001:asn": "ASN-1818AE4RF"
  },
  "lines": [
      {
          "line_id": "af7e23f7-08e7-4cf1-b644-1b0cf329e574",
          "article_id": "99.21004",
          "qty": 15
      }
  ]
}

Article attributes

Another example involves the use of product identifiers. While article_id serves as the standard unique identifier, our system allows organizations to incorporate alternative identifiers, such as EAN, SKU, UPC, ISBN within the article object as attributes (see the example below). These identifiers enable warehouse associates to scan products using those specific codes designated by your organization during decanting.

{
  "articles": [
    {
      "article_id": "116000487727",
      "name": "Cheerios Original Cereal, 12 Oz",
      "is_serial_numbered": false,
      "dimensions": {
        "x": "7.75",
        "y": "12",
        "z": "2.75",
        "uom": "in"
      },
      "attributes": {
        "upc": "016000275287",
        "sku": "CHRC-120Z-001"
      }
    }
  ]
}

Pre-defined attributes

Pre-defined attributes are parameters set by the system to cater to common requirements across different organizations. These attributes are standardized and offer functionalities that are frequently needed in the fulfillment process.

The table below contains the summary of available API methods for the Instock API client.

Each Instock site (or just site) represents a single instance of Instock ASRS. Such instance can represent either physical installation of ASRS or a simulation in sandbox environment. Organization may own many sites. A single physical site may have many sandboxes and each sandbox will be characterized by its own site_id.

Note: site_id is required to perform operations with orders, ordertasks, inventory and moves.

Instock is using the term article to describe unique product or SKU managed by Instock ASRS. Articles resource is mostly managed by you as a client of Instock API. Article data is shared across all sites that belong to your organization.

Note:

• currently articles with is_serial_numbered: true value cannot be uploaded or updated, Incloud will yield an error.
• attributes object can contain both custom and pre-defined values. Custom attributes defined upon initial integration with Incloud.

Intentions of users of Instock ASRS are represented by orders structure.

Orders resource allows:

• create/update/retrieve records for picking of goods from the ASRS (customer orders)
• retrieve-only access to records for induction/adjustment/extraction of inventory (adjustment, reception, extraction orders)

All operations with orders are performed in scope of a particular site and require site_id as a path parameter.

The following kinds and statuses of orders are in use:

Note:

• only customer orders can be updated, and only while they are in status registered. Once order fulfillment has started Instock ASRS freezes (makes read-only) customer orders.
• custom attributes object values are optional and defined upon initial integration with Incloud.

Fulfillment of orders by associates and ASRS is split into chunks called ordertasks. An ordertask can represent a picking of several lines of customer order, for example. Each ordertask corresponds to exactly one order and one order can have multiple ordertasks. On the other side, each action of robots of ASRS can be attributed back to exactly one ordertask.

Incloud promises, once order gets into one of the terminal statuses (done or canceled) the set of corresponding ordertasks is immutable, i.e. no new ordertasks to be added, and each ordertask record is immutable.

Ordertasks corresponding to customer order are created after order fulfillment is planned, i.e. after order status changes from registered to reserved. Once customer order is done or canceled, a client of API can reconstruct full picture of fulfillment of order by retrieving ordertasks data. Ordertasks may be presented by Incloud for all type of orders (customer, reception, adjustment, extraction).

Inventory resource returns data on the current quantity of article(s) that your organization has uploaded, use it to track articles that are low in stock or out-of-stock and require replenishment in scope of particular site.

Moves allow to retrieve data on article(s) flow in and out of of a particular site owned by your organization. List moves of all articles or retrieve them for a single article.

Note: Refine your search with from_timestamp and to_timestamp — most recent moves will be on top of the list.