Skip to main content
API docs by Redocly

Availabilities Export API (1.0.0)

Download OpenAPI specification:Download

team-order-management: team-order-management@newstore.com

Represents the available to promise (ATP) quantity for products.

ATP is calculated by subtracting the sum of all allocations, reservations, and safety stock quantity, from the stock on hand. That value is present ATP. Future ATP is exported separately and is not included in atp.

Use this resource to perform a global export of ATP for every location, or a location group export of Grouped ATP for a location group. Grouped ATP is per-product ATP summed across every location in the group.

Notes:

  • Each ATP export includes the external identifiers for the referenced product ID.
  • If no value is provided for the last_updated_at property when starting an export, a full export of ATP is performed.
  • When last_updated_at cursor is set, the zip archive contains products whose ATP changed after that cursor, plus products present at capacity-toggled stores. A product that did not change ATP and is not present at a capacity-toggled store is omitted. If nothing qualifies, the ATP list is empty.
  • For a location group export, if ATP changed in a location after the cursor, or a location in the group is a capacity toggled store, Grouped ATP for the whole location group is exported. A capacity toggled store outside the group is ignored.
  • Job last_updated_at is a cursor, not a timestamp. It is the highest ATP upsert_sequence in the zip. With Effective ATP on, it is at least the requested cursor, so an export that only re-sends capacity toggled stores does not move the cursor backwards. It is 0 when Effective ATP is off and the archive has no ATP updates.

For example, if the ATP for a product is 3 in Store A and 4 in Store B, Grouped ATP exported by the resource is 7. If ATP for Store A changes to 0 and the ATP for Store B stays the same, Grouped ATP is 4, and not 0.

This resource contains the following sub-resources:

  • bulk: Represents an availability export job.
  • groups: Represents a location group for which you can start a location group export.

For example, a location group can represent a region in your business.

Start global ATP export

Starts a global export of ATP for every location.

To retrieve the exported ATP, use the Get availability export job method.

Authorizations:
newStoreAccessToken
Request Body schema: application/json
last_updated_at
integer or null

A full availability export is performed when this value is not provided. When this value is provided, the incremental export contains ATP that changed after the cursor, plus products present at capacity toggled stores. Use the last_updated_at from the previous GET /availabilities/bulk job.

Responses

Request samples

Content type
application/json
{
  • "last_updated_at": 59837741
}

Response samples

Content type
application/json
{
  • "availability_export_id": "34vj3g4i325k23hkrnekrnkq"
}

Start location group export

Starts a location group export of Grouped ATP for a location group. To retrieve the exported ATP, use the Get availability export job method.

Authorizations:
newStoreAccessToken
path Parameters
group_name_or_availability_export_id
required
string

The identifier for the location group for which you want to start a location group export. See Create a location group.

Request Body schema: application/json
last_updated_at
integer or null

A full availability export is performed when this value is not provided. When this value is provided, the incremental export contains ATP that changed after the cursor, plus products present at capacity toggled stores. Use the last_updated_at from the previous GET /availabilities/bulk job.

Responses

Request samples

Content type
application/json
{
  • "last_updated_at": 59837741
}

Response samples

Content type
application/json
{
  • "availability_export_id": "34vj3g4i325k23hkrnekrnkq"
}

Get availability export job

Returns the result of the availability export job for the provided availability_export_id.

As part of the response payload, the link property contains a secure link that points to a zip file containing the ATP data. The zip file contains a file named availability.json, which contains the ATP data.

Important: Copying or pasting the link may damage it. The link to the archive expires after a week.

For a global export, see the schema for the payload of the availability.json file. Global exports are a JSON array of per-location rows.

For a location group export, see the schema. Location group exports are a JSON object with an atps array of per-product rows (Grouped ATP, no fulfillment_node_id), plus last_updated_at and group_revision.

The zip file has a naming pattern of availability_export-<export_id>, where <export_id> refers to the unique ID corresponding to the ATP export request that produced the zip file.

Authorizations:
newStoreAccessToken
path Parameters
group_name_or_availability_export_id
required
string

The identifier for the availability export job contained in the response to the Start global ATP export or the Start location group export methods.

Responses

Response samples

Content type
application/json
{}

List location groups

Returns all location groups for which you can start a location group export.

Authorizations:
newStoreAccessToken

Responses

Response samples

Content type
application/json
{
  • "availability_groups": [
    ]
}

Create location group

Creates a location group.

Use the group_name contained in the response, in your request to Start location group export.

Authorizations:
newStoreAccessToken
Request Body schema: application/json
group_name
required
string^[-_0-9a-zA-Z]+$

The identifier for the location group that can be used to request ATP for a location group.

fulfillment_nodes
required
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "group_name": "group_name",
  • "fulfillment_nodes": [
    ]
}

Response samples

Content type
application/json
{
  • "group_name": "group_name",
  • "fulfillment_nodes": [
    ]
}

Update location group

Updates the details of the specified location group.

Authorizations:
newStoreAccessToken
path Parameters
group_name
required
string

The identifier for the location group. Use the List location groups method to retrieve the ID.

Request Body schema: application/json
fulfillment_nodes
required
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "group_name": "group_name",
  • "fulfillment_nodes": [
    ]
}

Response samples

Content type
application/json
{
  • "group_name": "group_name",
  • "fulfillment_nodes": [
    ]
}

Delete location group

Deletes the specified location group.

Authorizations:
newStoreAccessToken
path Parameters
group_name
required
string

The identifier for the location group. Use the List location groups method to retrieve the ID.

Responses

Response samples

Content type
application/problem+json
{
  • "error_code": "unexpected_error",
  • "message": "Internal error has occurred.",
  • "request_id": "123.4567"
}