Instock API reference(0.1.0)

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.

Overview

Conventions

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

Authentication

Instock API offers authentication in form of Bearer token. Bearer token must be present in each request header. The token provides 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 \

Errors

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

Request IDs

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

Correlation IDs

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 \

Pagination

Endpoints that return a list of objects use pagination. Instock API uses cursor-based pagination. This approach allows the 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.

Unique identifiers

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

• provide site_id to specify the 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 the source (which system issues UID) and scope (at what level UID must be unique).

Additional attributes

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

Available API methods

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

Sites

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

List all sites

get/sites

https://api.instock.com/v1/sites

Returns a list of sites available to your organization and their properties.

Authorizations:

bearerAuth

Responses

200 Successful operation

Request samples

curl -X GET 'https://api.instock.com/v1/sites' \
-H 'Authorization: Bearer {ACCESS_TOKEN}'

Response samples

• 200
• 400
• 401
• 403
• 500

{
  "sites": [
    {
      "site_id": "1.1.0-1",
      "is_virtual": true
    },
    {
      "site_id": "1.1.0-2",
      "is_virtual": false 
    }
  ]
}

Articles

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.

Upload article(s)

post/articles

https://api.instock.com/v1/articles

Uploads single or multiple articles to your Instock organization account.

Note:

• if a particular article is not uploaded to your organization, warehouse operators won't be able to receive it into Instock ASRS (decant).
• if bulk article upload contains at least one article that cannot be validated, Incloud will yield 400 and the entire request will fail.
• bulk article upload has a limit of maximum 1000 articles per request.

Authorizations:

bearerAuth

Request Body schema: application/json

Responses

200 Successful operation.

Request samples

{
  "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": {
        "product_category_name": "Cereals & Bars",
        "temp_zone": "ambient"
      }
    }
  ]
}

List all articles

get/articles

https://api.instock.com/v1/articles

Returns a paginated list of all articles known within your organization account.

Authorizations:

bearerAuth

Request samples

curl -X GET 'https://api.instock.com/v1/articles' \
-H 'Authorization: Bearer {ACCESS_TOKEN}'

Response samples

• 200
• 400
• 401
• 403
• 500

{
  "has_more": false,
  "next_cursor": "",
  "articles": [
    {
      "article_id": "1003000031678",
      "name": "Quaker Apples and Cinnamon Instant Oatmeal Packets",
      "is_serial_numbered": false,
      "dimensions": {
        "x": "4.9",
        "y": "7.9",
        "z": "3.1",
        "uom": "m"
      },
      "attributes": {
        "product_category_name": "Cereals & Bars",
        "temp_zone": "ambient",
        "promotion_price": "2.99"
      }
    }
  ]
}

Get article

get/articles/{article_id}

https://api.instock.com/v1/articles/{article_id}

Retrieves a single existing article. Supply article_id either from article upload or articles list request, and Instock will return the corresponding article data.

Authorizations:

bearerAuth

Response samples

• 200
• 400
• 401
• 403
• 404
• 500

{
  "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": {
    "product_category_name": "Cereals & Bars",
    "temp_zone": "ambient"
  }
}

Update article

put/articles/{article_id}

https://api.instock.com/v1/articles/{article_id}

Updates a single existing article by setting the values of parameters passed.

Note:

• article update operation is performed via PUT method — when updating an article, a complete order record (all fields) must be passed.
• if article_id has inventory moves, Incloud will yield 400 error. In other words, if an article has already been decanted into ASRS, its properties cannot be updated as Incloud already relies on its properties.

Authorizations:

bearerAuth

Request Body schema: application/json

Responses

200 Successful operation.

Request samples

{
  "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": {
    "product_category_name": "Cereals & Bars",
    "temp_zone": "ambient",
    "promotion_price": "1.69"
  }
}

Orders

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:

Create customer order

post/{site_id}/orders

https://api.instock.com/v1/{site_id}/orders

Creates a single new customer order within a particular site of your organization.

Note: if lines object contains a line with an article that is not uploaded, Incloud will yield 404 and request will fail.

Responses

200 Successful operation.

Request samples

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

List all orders

get/{site_id}/orders

https://api.instock.com/v1/{site_id}/orders

Returns a paginated list of all orders within a specific site of an organization.

Response samples

• 200
• 400
• 401
• 403
• 404
• 500

{
  "has_more": false,
  "next_cursor": "",
  "org_id": "org_id_001",
  "site_id": "1.1.0-1",
  "orders": [
    {
      "order_id": "00132457",
      "site_id": "1.1.0-1",
      "kind": "customer",
      "placed_at": "2022-03-06T12:45:09Z",
      "attributes": {
        "property1": "string",
        "property2": "string"
      },
      "lines": [{
        "line_id": "00132457-1",
        "article_id": "116000275270",
        "qty": 1
      }]
    }
  ]
}

Update customer order

put/{site_id}/orders/{order_id}

https://api.instock.com/v1/{site_id}/orders/{order_id}

Updates a single existing order with kind customer. Only registered orders can be updated.

Request samples

{
  "org_id": "org_id_001",
  "site_id": "1.1.0-1",
  "order_id": "00132455",
  "kind": "customer",
  "placed_at": "2022-03-05T07:38:39Z",
  "attributes": {
    "property1": "string",
    "property2": "string"
  },
  "lines": [{
    "line_id": "00132455-1",
    "article_id": "1003000031678",
    "qty": 2
  }]
}

Retrieve order status

get/{site_id}/orders/{order_id}/status

https://api.instock.com/v1/{site_id}/orders/{order_id}/status

Retrieves a single existing order data and its ordertask status.

Request samples

curl -X GET 'https://api.instock.com/v1/{site_id}/orders/{order_id}/status' \
-H 'Authorization: Bearer {ACCESS_TOKEN}'

Response samples

• 200
• 400
• 401
• 403
• 404

todo