USusenash
Store Catalog

Create or update inventory

Changed on

Create or update inventory levels for products at specific store locations. Rows referencing an unknown product or store location are skipped and returned in the same array with errorCode/errorMessage set; the rest of the batch still commits.

post/v1/inventory

Request

Request body

Example request

{
  "inventory": [
    {
      "externalProductId": "ext_001",
      "externalStoreLocationId": "store_001",
      "quantity": 50,
      "valueCents": 299,
      "currency": "USD",
      "available": true,
      "location": {
        "aisle": "Aisle 5",
        "bay": "Bay 3",
        "shelf": "Shelf 2"
      },
      "details": {
        "weightedItemInfo": {
          "valueCentsPerMeasurementUnit": 120
        },
        "taxPercentage": 0.1
      },
      "providerConfigs": [
        {
          "currency": "USD",
          "details": {
            "weightedItemInfo": {
              "valueCentsPerMeasurementUnit": 135
            }
          },
          "discount": {
            "endTime": "2025-12-17T00:00:00Z",
            "startTime": "2025-12-10T00:00:00Z",
            "valueCents": 270
          },
          "provider": "X",
          "serviceType": "pick_and_deliver",
          "valueCents": 299
        }
      ]
    }
  ]
}

Response

OK

idstring nullable required

Null when the row was skipped.

productIdstring nullable required

The product ID associated with this inventory item. Null when the row was skipped.

externalProductIdstring nullable required

The external product ID from an external system

storeLocationIdstring nullable required

The store location ID where this inventory is located. Null when the row was skipped.

externalStoreLocationIdstring nullable required

The external store ID from an external system

quantityinteger nullable required

The quantity of the product in stock. Null when the row was skipped.

valueCentsinteger nullable

The price of the product in cents

currencystring nullable

The currency code for the product price

availableboolean nullable required

Whether the product is available for purchase. Null when the row was skipped.

errorCodestring nullable required

Set when this row was skipped (unknown product or store location); null on success.

errorMessagestring nullable required

Why the row was skipped; null on success.

Example response

[
  {
    "id": "inv_123",
    "productId": "prod_123",
    "externalProductId": "ext_001",
    "storeLocationId": "store_001",
    "externalStoreLocationId": "ext_store_002",
    "quantity": 50,
    "valueCents": 299,
    "currency": "USD",
    "available": true,
    "location": {
      "aisle": "Aisle 5",
      "bay": "Bay 3",
      "shelf": "Shelf 2"
    },
    "details": {
      "weightedItemInfo": {
        "valueCentsPerMeasurementUnit": 120
      },
      "taxPercentage": 0.1
    },
    "providerConfigs": [
      {
        "provider": "X",
        "serviceType": "pick_and_deliver",
        "valueCents": 299,
        "currency": "USD",
        "details": {
          "weightedItemInfo": {
            "valueCentsPerMeasurementUnit": 120
          },
          "taxPercentage": 0.1
        },
        "available": true,
        "discount": {
          "valueCents": 270,
          "startTime": "2025-12-10T00:00:00Z",
          "endTime": "2025-12-17T00:00:00Z"
        },
        "taxPercentage": 0.1
      }
    ],
    "errorCode": "MISSING_RESOURCE",
    "errorMessage": "Product 'ext_001' not found."
  }
]

Changes

  • e3713837c5c9Revision changes
    • breaking

      response property items/available list-of-types was widened by adding types null to media type application/json of response 200

    • breaking

      response property items/id list-of-types was widened by adding types null to media type application/json of response 200

    • breaking

      response property items/productId list-of-types was widened by adding types null to media type application/json of response 200

    • breaking

      response property items/quantity list-of-types was widened by adding types null to media type application/json of response 200

    • breaking

      response property items/storeLocationId list-of-types was widened by adding types null to media type application/json of response 200

    • info

      the response property / became required for the status

    • info

      the response property / became required for the status

    • info

      added the required property / to the response with the status

    • info

      added the required property / to the response with the status