Xpand Autonomous Store Management API (1.0)

The Xpand Autonomous Store Management API provides all the necessary functionality for operating and integrating with the Xpand Autonomous Store.

The Xpand API can be seen as broadly covering the following topics:

• Product catalog
• Systems, grouped into Sites
• Stock
• Orders
• Webhooks
• Media

An Xpand Autonomous Store deployment is composed of one or more sites, with each site containing one or more Xpand Autonomous Warehouse systems. Sites are identified by a unique siteId, while systems are identified by a unique systemId.

The Xpand Cloud API provides endpoints for managing or synchronizing the product catalog, as well as viewing and managing systems, inventory & orders. Webhooks can also be used to receive real-time events such as new orders or system state changes.

API calls to the Xpand Autonomous Store Management API are authenticated using an API Key provided by Xpand. The API key should be present in the Authorization header on all API calls.

GET /products
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxx

A few principles are maintained across the API:

GET endpoints that return a list of objects support a simple format for filtering their results, using either the query string or the request body:

GET /products?categoryId=7

GET /products
{
    "categoryId": 7
}

ALL PUT endpoints across the API accept partial JSON structures.

For example an endpoint like this:

GET /products/{id}
{
    "id": <string>,
    "name": <string>,
    "description": <string>,
    ...
}

That has a corresponding PUT endpoint for updating the product details, would allow updating only some of even just one of the fields:

# Update the product name only
PUT /products/{id}
{
    "name": <string>
}

# Update the product description only
PUT /products/{id}
{
    "description": <string>
}

Traditionally such update endpoints that accept a partial payload are often denoted using the HTTP PATCH method. However for simplicity's sake, the Xpand API simply accepts partial payloads under the PUT method.

Note that this partiality only applies to top-level properties. Object properties, if present, would be taken to mean a complete update of the whole sub-object. However in most such cases sub-endpoints would be provided for more granular updates (see below).

Some endpoints support sub-endpoints, for example:

GET /products/{id}
{
    # Product details
    ...

    "identifiers": [
        # Product identifiers
        ...
    ],

    ...
}

GET /products/{id}/identifiers
{
    # Product identifiers
    ...
}

When this happens, the request and response payloads of the sub-endpoints would match exactly the schema of the corresponding property of the parent resource. So in the above example the JSON structure of the response of the GET /products/{id}/identifiers endpoint is the same as the value of the identifiers property in the JSON response of the parent GET /products/{id} endpoint.

The behaviour for PUT and POST endpoints therefore follows a similar logic:

# Set the product identifiers
PUT /products/{id}
{
    "identifiers": [...]
}

# Set the product identifiers
PUT /products/{id}/identifiers
[
    {
        "type": "...",
        "value": "..."
    },
    ...
]

# Add a product identifier
POST /products/{id}/identifiers
{
    "type": "...",
    "value": "..."
}

# Update a single product identifier
# (this endpoints doesn't exist in practice for product identifiers
#  as it doesn't make sense. It is only present here for illustration 
#  purposes).
PUT /products/{id}/identifiers/{identifier}
{
    "type": "...",
    "value": "..."
}

# Remove a single product identifier.
DELETE /products/{id}/identifiers/{identifier}

Products support an optional externalId field that allows clients/integrators to provide their own unique identifier (e.g., their database row ID). This external ID:

• Must be unique across all products if provided
• Is stored as an arbitrary string by the Xpand API
• Can be used in place of the Xpand internal product ID in API endpoints

To use an external ID in API endpoints, prefix it with ext: in the path parameter:

# Using internal product ID
GET /products/123
PUT /products/123

# Using external ID (if product was created with externalId "J57S")
GET /products/ext:J57S
PUT /products/ext:J57S

This applies to all product endpoints including sub-resources like images, identifiers, and modifiers.

Note that the Xpand internal product id is still generated and present regardless of externalId.

Also note that if using product external IDs the product PUT endpoints becomes an UPSERT (create or update). e.g:

# Using internal product ID
POST /products            <--- Create product
PUT  /products/123        <--- Update product

# Using external ID
PUT  /products/ext:J57S   <--- Create or update product

Most key endpoints in the Xpand API support arbitrary key/value pairs that can be attached to any resource under the metadata property:

PUT /products/{id}
{
    "metadata": {
        "foo": "bar"
    }
}

In such cases corresponding GET endpoints can use these metadata keys to filter results using a metadata.<key> notation, or as keys of the metadata object property if using the GET body object method for querying:

GET /products?metadata.foo=bar

GET /products
{
    "metadata": {
        "foo": "bar"
    }
}

The metadata is meant for the sole use of customer or 3rd party integrations, and not used internally by the Xpand API in any logic flows.

The values for metadata are limited to simple scalar values (string, bool, number) and arrays of strings or numbers.

Note that on update operations, the metadata object is also taken as a partial update. This means that an explicit null value is required in order to delete a key. In other words, this JSON example is interpreted to mean set key foo to value "bar":

"metadata": {
    "foo": "bar"
}

While this JSON snippet appearing in a PUT request would mean set key foo to value "bar" and delete the value of key baz:

"metadata": {
    "foo": "bar",
    "baz": null
}

Product portfolio management

Product identifier management

Product modifier management