Template Docs Commerce APIs Tools
Get Started
Get Started

Adjusting Stock Levels

POST https://api.squarespace.com/1.0/commerce/inventory/adjustments

Supports stock adjustment operations on specified product variants. Stock adjustments can be incremental, decremental, finite ("I have exactly n of this variant in stock"), or unlimited ("This variant has limitless stock").

This endpoint requires an idempotency key to allow for repeated requests in the event of a client, server, or network error leading to an unsuccessful or ambiguous outcome. Thus, requests may be retried using the same idempotency key and parameters, and you can be sure the requested inventory adjustments will occur only once.

Additional Headers

In addition to the headers common to all Commerce API requests, the following must also be present:

  • Idempotency-Key
    • Type: Any alphanumeric string (also, optionally, containing dashes and underscores) of up to 64 characters.
    • A unique identifier to enforce idempotency: a request sent multiple times will only be executed once (the first time) and will receive the same response.
      • Note: Idempotency keys are recycled on an unspecified interval, however they are guaranteed effective for 48 hours from the time they’re used.

Request Format & Example

curl "https://api.squarespace.com/1.0/commerce/inventory/adjustments" \
  -H "Authorization: Bearer YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: B7630F15-0D95-442E-8295-1E74BE73A255" \
  -X POST \
  -d '{
    "incrementOperations": [{
      "variantId": "185db2da-c3cf-47f3-8aff-0485082792a5",
      "quantity": 1
    }],
    "decrementOperations": [{
      "variantId": "7eb25f50-4a0a-4e86-ac7c-cc1d49347bb4",
      "quantity": 1
    }],
    "setFiniteOperations": [{
      "variantId": "cdf29b1e-01c2-4931-a3f9-7c0568daff23",
      "quantity": 40
    }],
    "setUnlimitedOperations": [
      "3afec275-5c9e-4167-93a7-17c01bba1ae2",
      "f4334e47-b517-4291-8bcc-1e11dfc51a4f"
    ]
  }'
  • incrementOperations optional: An array of objects specifying a variant id and the amount to add to that variant's stock quantity.
    • Quantity values must be greater than or equal to 1.
  • decrementOperations optional: An array of objects specifying a variant id and the amount to subtract from that variant's stock quantity.
    • Quantity values must be greater than or equal to 1.
  • setFiniteOperations optional: An array of objects specifying a variant id and the exact quantity in stock for that variant.
    • Quantity values must be greater than or equal to 0.
  • setUnlimitedOperations optional: An array of variants ids representing one or more variants that should be marked as having unlimited stock.

Note that although all four operation arrays are optional, at least one must be provided containing at least one valid value for a request to be considered valid. Requests may also provide empty arrays for these fields, but again, at least one must contain an valid value.

Response Format

A response to a successful request will not contain any data.

Status Codes & Error Conditions

  • 204 NO CONTENT
    • The request was successful. The message body does not contain any data. If this is a replayed request using an already consumed idempotency key, the operations will have occurred previously and no new changes will have taken place.
  • 400 BAD REQUEST
    • Type: INVALID_REQUEST_ERROR
    • Subtype: null
      1. The request body is missing required attribute(s), or a present attribute is an incorrect type.
      2. No operations were specified.
      3. More than 50 operations were specified.
      4. One or more variants were not found.
      5. The same variant was referenced in more than one operation.
      6. A specified quantity is invalid.
      7. The Idempotency-Key header is missing, empty, larger than 64 characters, or includes invalid characters.
      8. The provided idempotency key has already been used by another request bearing a different body.
  • 409 CONFLICT
    • Type: CONFLICT
    • Subtype: CONCURRENT_MODIFICATION
      1. A request using the provided idempotency key is already in progress. If the request should be attempted independently of the other request, specify a new idempotency key and try again.
      2. A request modifying one or more provided variants could not be completed due to a very recent state change. You may retry your request.
    • Subtype: INSUFFICIENT_STOCK
      1. A decrement operation cannot be completed because the referenced variant does not have sufficient stock.
    • Subtype: STOCK_EXCEEDS_MAX
      1. An increment operation cannot be completed because the referenced variant will exceed the maximum allowed stock.
    • Subtype: STOCK_NOT_TRACKED
      1. An increment or decrement operation cannot be completed because the referenced variant has unlimited inventory.