Squarespace Inventory API

openapi: 3.2.0
info:
  title: Squarespace Inventory API
  version: '1.0'
  description: 'Operations tagged Inventory across 2 of this provider''s published API definitions: squarespace-commerce-api-v2-openapi.json, squarespace-inventory-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.squarespace.com
  description: Commerce API
- url: https://api.squarespace.com/1.0
  description: Production Server
tags:
- name: Inventory
  x-zudoku-collapsed: true
paths:
  /1.0/commerce/inventory:
    get:
      description: Retrieves real-time stock information for all product variants. Stock information is stored in an InventoryItem for each product variant. The response contains up to 50 InventoryItems and supports dynamic cursors for pagination.
      operationId: getInventoryItems
      parameters:
      - description: Identifies where the next page of results should begin. Should be the value of pagination.nextPageCursor from a previous response. If not present or empty, the endpoint returns up to 50 InventoryItems.
        in: query
        name: cursor
        required: false
        schema:
          type: string
      - in: header
        name: Authorization
        required: true
        description: API key or OAuth access token
        schema:
          type: string
          default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
      - in: header
        name: User-Agent
        required: true
        description: User Agent
        schema:
          type: string
          default: YOUR_CUSTOM_APP_DESCRIPTION
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedInventoryItemListResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorPayload'
          description: 'Bad Request. Type: INVALID_REQUEST_ERROR. The cursor parameter contains an invalid value.'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorPayload'
          description: Not found. The API version is not supported.
      summary: List inventory
      tags:
      - Inventory
      security:
      - Authorization: []
    servers:
    - url: https://api.squarespace.com
      description: Commerce API
  /1.0/commerce/inventory/adjustments:
    post:
      description: Adjusts stock quantities for product variants. Stock quantities can be added or subtracted, set with a given number, or marked as "unlimited". All quantity information is stored in InventoryItems.
      operationId: adjustInventoryStockLevels
      parameters:
      - description: Required for idempotent requests. Refer to the idempotency key guide for requirements.
        in: header
        name: Idempotency-Key
        required: true
        schema:
          type: string
      - in: header
        name: Authorization
        required: true
        description: API key or OAuth access token
        schema:
          type: string
          default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
      - in: header
        name: User-Agent
        required: true
        description: User Agent
        schema:
          type: string
          default: YOUR_CUSTOM_APP_DESCRIPTION
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInventoryAdjustmentRequest'
      responses:
        '204':
          description: No content. The request was successful. If this is a request with a previously used Idempotency-Key, the previous operation was successful and no new changes were made.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorPayload'
          description: 'Bad Request. Type: INVALID_REQUEST_ERROR. The request body is missing a required field or a field is an incorrect type; no operations were specified; greater than 50 operations were specified; one or more InventoryItems were not found; the same InventoryItem was referenced in more than one operation; a specified quantity is invalid; or the Idempotency-Key header is missing or invalid.'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorPayload'
          description: Not found. The API version is not supported.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorPayload'
          description: 'Conflict. Type: CONFLICT. Possible subtypes: CONCURRENT_MODIFICATION (a request using the provided Idempotency-Key is already in progress, or a request modifying one or more of the specified InventoryItems could not be completed due to an overlapping request), INSUFFICIENT_STOCK (a decrement operation cannot be completed because the referenced InventoryItem does not have sufficient stock), STOCK_EXCEEDS_MAX (an increment operation cannot be completed because the referenced InventoryItem will exceed the maximum allowed stock), STOCK_NOT_TRACKED (an increment or decrement operation cannot be completed because the referenced InventoryItem has unlimited inventory).'
      summary: Adjust stock quantities
      tags:
      - Inventory
      security:
      - Authorization: []
    servers:
    - url: https://api.squarespace.com
      description: Commerce API
  /1.0/commerce/inventory/{variantIdCsvs}:
    get:
      description: Retrieves real-time stock information for specific product variants. Stock information is stored in an InventoryItem and up to 50 InventoryItems can be retrieved per request.
      operationId: getSpecificInventoryItems
      parameters:
      - description: 'Specifies the InventoryItems to retrieve. Multiple InventoryItems can be retrieved by providing a comma-separated list: {id1},{id2}..., though the same sequence is not guaranteed in the response.'
        in: path
        name: variantIdCsvs
        required: true
        schema:
          type: string
      - in: header
        name: Authorization
        required: true
        description: API key or OAuth access token
        schema:
          type: string
          default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
      - in: header
        name: User-Agent
        required: true
        description: User Agent
        schema:
          type: string
          default: YOUR_CUSTOM_APP_DESCRIPTION
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryItemListResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorPayload'
          description: 'Bad Request. Type: INVALID_REQUEST_ERROR. ids specifies greater than 50 InventoryItems.'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorPayload'
          description: 'Not Found. Type: INVALID_REQUEST_ERROR. Subtype: INVALID_ARGUMENT. One or more requested InventoryItems were not found.'
      summary: Get inventory
      tags:
      - Inventory
      security:
      - Authorization: []
    servers:
    - url: https://api.squarespace.com
      description: Commerce API
  /commerce/inventory:
    get:
      operationId: listInventory
      summary: Retrieve All Inventory
      description: Returns real-time stock information for all product variants on the merchant site. The response contains up to 50 InventoryItem objects per page, with dynamic cursor-based pagination for iterating through all records. Each InventoryItem corresponds to a single product variant and includes its current stock quantity and tracking settings.
      tags:
      - Inventory
      parameters:
      - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: Successful response with paginated list of inventory items
          content:
            application/json:
              schema:
                type: object
                properties:
                  inventory:
                    type: array
                    description: List of inventory items for product variants
                    items:
                      $ref: '#/components/schemas/InventoryItem_2'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
    servers:
    - url: https://api.squarespace.com/1.0
      description: Production Server
  /commerce/inventory/{variantIds}:
    get:
      operationId: getInventoryByVariants
      summary: Retrieve Specific Inventory
      description: Retrieves real-time stock information for up to 50 specific product variants by their variant IDs. Variant IDs should be provided as a comma-separated list in the path. This endpoint is useful for checking stock levels on specific items without paginating through the full inventory.
      tags:
      - Inventory
      parameters:
      - $ref: '#/components/parameters/variantIds'
      responses:
        '200':
          description: Successful response with inventory items for the specified variants
          content:
            application/json:
              schema:
                type: object
                properties:
                  inventory:
                    type: array
                    description: Inventory items for the requested product variants
                    items:
                      $ref: '#/components/schemas/InventoryItem_2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
    servers:
    - url: https://api.squarespace.com/1.0
      description: Production Server
  /commerce/inventory/adjustments:
    post:
      operationId: adjustInventory
      summary: Adjust Stock Quantities
      description: Applies incremental stock quantity adjustments to one or more product variants. Adjustments are relative changes, not absolute values. Positive values increase stock and negative values decrease it. Bulk adjustments across multiple variants can be submitted in a single request. Each adjustment can optionally include a reason for audit tracking.
      tags:
      - Inventory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdjustInventoryRequest'
      responses:
        '200':
          description: Inventory adjustments applied successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  inventory:
                    type: array
                    description: Updated inventory items after adjustments were applied
                    items:
                      $ref: '#/components/schemas/InventoryItem_2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
    servers:
    - url: https://api.squarespace.com/1.0
      description: Production Server
components:
  schemas:
    InventoryQuantityExpression:
      type: object
      properties:
        quantity:
          type: integer
          description: Quantity value for the inventory operation.
          format: int32
        variantId:
          type: string
          description: Unique id for the InventoryItem.
      description: Optional; array of objects. Sets the exact stock quantity for InventoryItems.
    CreateInventoryAdjustmentRequest:
      type: object
      properties:
        decrementOperations:
          type: array
          description: Optional; array of objects. Subtracts stock quantity for InventoryItems.
          items:
            $ref: '#/components/schemas/InventoryQuantityExpression'
        incrementOperations:
          type: array
          description: Optional; array of objects. Increments stock quantity for InventoryItems.
          items:
            $ref: '#/components/schemas/InventoryQuantityExpression'
        setFiniteOperations:
          type: array
          description: Optional; array of objects. Sets the exact stock quantity for InventoryItems.
          items:
            $ref: '#/components/schemas/InventoryQuantityExpression'
        setUnlimitedOperations:
          type: array
          description: Optional; array of InventoryItem ids. Marks stock quantity as "unlimited" for the given InventoryItems.
          items:
            type: string
            description: Optional; array of InventoryItem ids. Marks stock quantity as "unlimited" for the given InventoryItems.
    PaginatedInventoryItemListResponse:
      type: object
      properties:
        inventory:
          type: array
          description: Array of InventoryItem resources. If the merchant site doesn't have any physical or service product variants, this array is empty.
          items:
            $ref: '#/components/schemas/InventoryItem'
        pagination:
          examples:
          - hasNextPage: true
            nextPageCursor: ewogICJhIiA6ICI2OWNhOWExZjgxNGMwYTY0MmIwMTIzYzkiLAogICJiIiA6ICJJRCIKfQ
            nextPageUrl: /1.0/commerce/inventory?cursor=ewogICJhIiA6ICI2OWNhOWExZjgxNGMwYTY0MmIwMTIzYzkiLAogICJiIiA6ICJJRCIKfQ
          type: object
          properties:
            hasNextPage:
              type: boolean
            nextPageCursor:
              type: string
            nextPageUrl:
              type: string
    InventoryItem:
      type: object
      properties:
        descriptor:
          type: string
          description: Generated description using the product's title and any available variant attributes including, but not limited to, color and size.
        isUnlimited:
          type: boolean
          description: Indicates whether stock is currently tracked for the item.
        quantity:
          type: integer
          description: Current amount in stock, or the last known stock amount prior to becoming unlimited. This value is modified by purchases and returns only when `isUnlimited` is `false`.
          format: int32
        sku:
          type: string
          description: Stock keeping unit (SKU) code assigned by the Squarespace merchant for the variant; used to identify an exact variant of a product using a naming scheme preferred by the merchant.
        variantId:
          type: string
          description: The product variant id, which also serves as a unique id for the InventoryItem.
      description: Array of InventoryItem resources. If the merchant site doesn't have any physical or service products, this array is empty.
    StandardErrorPayload:
      type: object
      properties:
        contextId:
          type: string
        details:
          type: object
        message:
          type: string
        subtype:
          type: string
          enum:
          - MISSING_ARGUMENT
          - INVALID_ARGUMENT
          - INVALID_CONTENT_TYPE
          - CONCURRENT_MODIFICATION
          - INSUFFICIENT_STOCK
          - STOCK_NOT_TRACKED
          - STOCK_EXCEEDS_MAX
          - CURRENCY_MISMATCH
          - MEASUREMENT_STANDARD_MISMATCH
          - INSUFFICIENT_PRODUCT_VARIANTS
          - URL_SLUG_UNAVAILABLE
          - SKU_UNAVAILABLE
          - STORE_PAGE_NOT_FOUND
          - STORE_PAGE_PRODUCT_LIMIT_REACHED
          - IMAGE_LIMIT_REACHED
          - WEBHOOK_SUBSCRIPTION_LIMIT_REACHED
          - MISSING_SCOPE
          - PROFILE_CANNOT_ACCEPT_MARKETING
          - ENTITY_LIMIT_REACHED
          - PRODUCT_UPDATE_CONFLICT
          - DUPLICATE_USER_CONFLICT
          - PROMO_CODE_CONFLICT
          - INVENTORY_ITEM_NOT_FOUND
          - PRODUCT_IMAGE_NOT_FOUND
          - PRODUCT_VARIANT_NOT_FOUND
          - OAUTH_TOKEN_REQUIRED
          - FORBIDDEN_RESOURCE
          - OPERATION_NOT_ALLOWED_FOR_PRODUCT_TYPE
        type:
          type: string
          enum:
          - INVALID_REQUEST_ERROR
          - AUTHORIZATION_ERROR
          - WEBSITE_EXPIRED
          - METHOD_NOT_ALLOWED
          - CONFLICT
          - TOO_MANY_REQUESTS
          - SERVER_ERROR
          - SERVICE_UNAVAILABLE
    InventoryItemListResponse:
      type: object
      properties:
        inventory:
          type: array
          description: Array of InventoryItem resources. If the merchant site doesn't have any physical or service products, this array is empty.
          items:
            $ref: '#/components/schemas/InventoryItem'
    Pagination:
      type: object
      description: Pagination metadata included with list responses
      properties:
        hasNextPage:
          type: boolean
          description: Indicates whether additional pages of results are available
        nextPageCursor:
          type: string
          description: Cursor value to pass in the next request to retrieve the next page
        nextPageUrl:
          type: string
          format: uri
          description: Full URL for retrieving the next page of results
    InventoryAdjustment:
      type: object
      description: A single stock quantity adjustment for a product variant
      required:
      - variantId
      - quantity
      properties:
        variantId:
          type: string
          description: Unique identifier of the product variant to adjust
        quantity:
          type: integer
          description: Relative quantity change to apply. Positive values increase stock, negative values decrease it.
    Error:
      type: object
      description: Standard error response returned by the Squarespace API
      properties:
        type:
          type: string
          description: Machine-readable error type identifier
        subtype:
          type: string
          description: Optional more specific error subtype
        message:
          type: string
          description: Human-readable description of the error
        statusCode:
          type: integer
          description: HTTP status code associated with the error
    AdjustInventoryRequest:
      type: object
      description: Request body for applying inventory adjustments
      required:
      - increments
      properties:
        increments:
          type: array
          description: List of inventory adjustments to apply
          items:
            $ref: '#/components/schemas/InventoryAdjustment'
    InventoryItem_2:
      type: object
      description: Stock information for a single product variant
      properties:
        variantId:
          type: string
          description: Unique identifier of the product variant
        sku:
          type: string
          description: Stock keeping unit identifier for the variant
        descriptor:
          type: string
          description: Human-readable description of the variant including option values
        isUnlimited:
          type: boolean
          description: When true, the variant has unlimited stock and quantity values are not meaningful
        isTracked:
          type: boolean
          description: Whether stock tracking is enabled for this variant
        quantity:
          type: integer
          description: Current stock quantity available for the variant
          minimum: 0
        infiniteStock:
          type: boolean
          description: Alias for isUnlimited indicating the variant never goes out of stock
  parameters:
    cursor:
      name: cursor
      in: query
      description: Pagination cursor from a previous response's pagination.nextPageCursor field. Omit or leave empty to retrieve the first page.
      required: false
      schema:
        type: string
    variantIds:
      name: variantIds
      in: path
      description: Comma-separated list of up to 50 product variant IDs for which to retrieve inventory information
      required: true
      schema:
        type: string
  responses:
    BadRequest:
      description: The request was malformed or contained invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The authenticated user does not have permission to access this resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    Authorization:
      in: header
      scheme: bearer
      type: http
    bearerAuth:
      type: http
      scheme: bearer
      description: Authenticate using an API key or OAuth access token. Include the token in the Authorization header as "Bearer YOUR_TOKEN".
externalDocs:
  description: Squarespace Commerce API Documentation
  url: https://developers.squarespace.com/commerce-apis/overview
x-refined-from:
- squarespace-commerce-api-v2-openapi.json
- squarespace-inventory-api-openapi.yml