Inventory items

An inventory item represents a quantity-tracked product or an individually tracked unique item in SalesBinder.

The item object

For unique items, completed invoice inventory processing sets status 14 when quantity reaches zero. Removing the invoice quantity through an edit, line deletion, cancellation, or invoice deletion restores status 12. Archived items remain status 13, including while invoice inventory is processed. Quantity-tracked items remain available when their quantity reaches zero because out of stock is not the same as sold.

The item variation object

Variation totals are calculated from current location inventory. For a user assigned to one inventory location, totals and location_count include only that location.

The variation location object

The response includes only the variation-location fields listed above.

Use the inventory locations endpoints to discover active location and zone UUIDs before creating or configuring location-aware inventory records.

List inventory items

GET/api/v3/items

Required scope: items:read

Returns visible items ordered by name. The default list contains active quantity-tracked items and active unique items that have not been sold.

Query parameters

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/items?q=widget&type=quantity&page=1&limit=20" \
  --header "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "object": "list",
  "url": "/api/v3/items",
  "has_more": false,
  "data": [
    {
      "id": "4bb16375-9674-4e38-bab0-bcb15b97b76d",
      "object": "item",
      "item_number": 1042,
      "name": "Example Widget",
      "description": "A quantity-tracked example item",
      "sku": "WIDGET-01",
      "barcode": "0123456789012",
      "serial_number": null,
      "inventory_type": "quantity",
      "category_id": "c9164a6b-8c81-4162-b2f4-e8a241a203a6",
      "category_name": "Widgets",
      "status_id": 12,
      "location_id": null,
      "zone_id": null,
      "unit_of_measure_id": null,
      "unit_of_measure": null,
      "price": "19.9500",
      "cost": "8.2500",
      "quantity": 25,
      "quantity_reserved": 2,
      "quantity_incoming": 10,
      "quantity_estimates": 1,
      "threshold": 5,
      "variation_count": 0,
      "weight": 0,
      "published": true,
      "archived": false,
      "purchase_date": null,
      "sold_date": null,
      "created_at": "2026-07-18T18:42:19+00:00",
      "updated_at": "2026-07-18T18:42:19+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_records": 1
  }
}

Retrieve an inventory item

GET/api/v3/items/{item_id}

Required scope: items:read

Returns one item within the current user's account and location-visibility boundary. A sold unique item or archived item can still be retrieved directly when its UUID is known and the user can access it.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d" \
  --header "Authorization: Bearer YOUR_API_KEY"

The response is an item object. If the item is unavailable to the current user, the API returns 404 resource_missing.

List an item's variation attributes

GET/api/v3/items/{item_id}/variation-attributes

Required scope: items:read

Returns the variation attributes assigned to one visible inventory item and the allowed values for each attribute. Use the returned attribute and value UUIDs when constructing variation requests.

Query parameters

curl "https://yourbusiness.salesbinder.com/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d/variation-attributes?limit=20" \
  --header "Authorization: Bearer YOUR_API_KEY"

{
  "object": "list",
  "url": "/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d/variation-attributes",
  "has_more": false,
  "data": [
    {
      "id": "cb213f7a-fd4c-4f66-8c23-231563f9d49f",
      "object": "item_variation_attribute",
      "name": "Color",
      "display_name": "Colour",
      "values": [
        {
          "id": "e4f16a1f-d10a-4a0e-ab20-603211a86dd3",
          "object": "item_variation_attribute_value",
          "value": "Blue"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_records": 1
  }
}

Attributes follow the order configured on the item, and values follow their configured order. An item without assigned variation attributes returns an empty list. The parent item must be inside the current account and inventory-location visibility boundary; inaccessible items return 404 resource_missing.

Create an item variation

POST/api/v3/items/{item_id}/variations

Required scope: items:write

Creates one variation for a visible, active inventory item. Use the attribute and value UUIDs returned by the variation-attributes endpoint.

Writable fields

curl "https://yourbusiness.salesbinder.com/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d/variations" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: create-example-variation-001" \
  --data '{
    "attributes": [
      {
        "attribute_id": "cb213f7a-fd4c-4f66-8c23-231563f9d49f",
        "value_id": "e4f16a1f-d10a-4a0e-ab20-603211a86dd3"
      }
    ],
    "barcode": "WIDGET-BLUE",
    "unit_price_override": "21.50"
  }'

Returns the detailed variation object and its visible locations array with 201 Created. SalesBinder creates location rows automatically with zero quantity: all active account locations for an unrestricted user, or only the user's assigned location for a location-restricted user. Use the variation-location adjustment endpoint to add stock and the variation-location update endpoint to configure thresholds and zones afterward.

When creating the first variation for a single-location item, SalesBinder transfers the item's existing quantity, threshold, and zone to the matching variation location. Existing document and order line references remain connected, and the parent item's total quantity is preserved.

Every supplied value must belong to its specified attribute, every attribute must be assigned to the item, and the complete combination must be unique. Items without attributes can have only one variation. Duplicate combinations return 409 duplicate_variation. Quantity, threshold, zone, image, location, and other server-managed fields are rejected.

Immediate retries can reuse the same short-lived Idempotency-Key. Reusing the key with different request data returns 409 idempotency_key_reused.

List an item's variations

GET/api/v3/items/{item_id}/variations

Required scope: items:read

Returns a page of compact variation objects for one visible inventory item. The list includes totals calculated from the location rows visible to the current user, but it does not include the locations array.

Query parameters

curl "https://yourbusiness.salesbinder.com/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d/variations?limit=20" \
  --header "Authorization: Bearer YOUR_API_KEY"

The response uses the standard list and page-based pagination format. An item without variations returns an empty list rather than an error.

Retrieve an item variation

GET/api/v3/items/{item_id}/variations/{variation_id}

Required scope: items:read

Returns one variation with its visible locations array:

curl "https://yourbusiness.salesbinder.com/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d/variations/80c52be1-5ed8-4496-a5a6-48966e4956d7" \
  --header "Authorization: Bearer YOUR_API_KEY"

The variation must belong to the item in the URL. A variation from another item, account, or location boundary returns 404 resource_missing. Archived items and their variations remain readable when the parent item is visible.

Update an item variation

PATCH/api/v3/items/{item_id}/variations/{variation_id}

Required scope: items:write

Updates supported metadata shared by a variation across its inventory locations. The variation must belong to the item in the URL and be visible within the user's current inventory-location permission.

Writable fields

At least one supported field is required. Numeric overrides must be finite numbers or numeric strings. Quantity, images, location rows, zones, thresholds, reserved or incoming quantities, and other variation-structure fields cannot be changed through this endpoint.

When attributes is included, it replaces the complete current combination rather than merging individual values. Use GET/api/v3/items/{item_id}/variation-attributes to discover assigned attribute and value UUIDs. The API rejects incomplete selections, values belonging to another attribute, and combinations already used by a sibling variation.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d/variations/80c52be1-5ed8-4496-a5a6-48966e4956d7" \
  --request PATCH \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: update-example-variation-001" \
  --data '{
    "attributes": [
      {
        "attribute_id": "17804968-fb06-4ac6-9c79-1cdcb2456b48",
        "value_id": "9099279e-a650-4e03-93ef-f7a4fc619ba0"
      },
      {
        "attribute_id": "c1218d2a-3493-4e82-9672-b5e5afdadb9e",
        "value_id": "28fc93e1-a9cb-45b0-91e4-129e86269706"
      }
    ],
    "barcode": "WIDGET-BLUE-LARGE",
    "unit_price_override": "21.50",
    "unit_cost_override": null
  }'

Returns the updated detailed variation object with 200 OK. The response includes visible location quantities but omits unit_cost_override when the current user cannot view unit costs.

Variation metadata and attributes are updated together. Previously saved document lines keep the variation description captured when they were created. Immediate retries can use the same short-lived Idempotency-Key; reusing that key with different request data returns 409 idempotency_key_reused.

Archived items are read-only. A mismatched or inaccessible item or variation returns 404 resource_missing. Location-assigned users can update only variations stocked at their assigned location, even though barcode and override values are shared across the variation.

Delete an item variation

DELETE/api/v3/items/{item_id}/variations/{variation_id}

Required scope: items:delete

Permanently deletes an unused variation and its empty inventory-location rows. The current user must also have SalesBinder's inventory-delete permission. If that permission is not configured, SalesBinder may use the inventory-modification permission. An explicit denial is always enforced.

curl "https://yourbusiness.salesbinder.com/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d/variations/80c52be1-5ed8-4496-a5a6-48966e4956d7" \
  --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY"

Deletion is refused with 409 when the variation is used by any saved document or sales-order line, is used as a kit or bundle component, or has a nonzero on-hand, reserved, incoming, or in-transit balance at any location. Document references block deletion regardless of document status. Adjustment history by itself does not block an otherwise eligible deletion.

The variation and its related empty location data are deleted together. If the operation cannot be completed, no related data is removed. A successful request returns:

{
  "id": "80c52be1-5ed8-4496-a5a6-48966e4956d7",
  "object": "item_variation",
  "deleted": true
}

Archived items are read-only. A location-assigned user cannot delete a variation containing location rows outside their current permission boundary. A mismatched or inaccessible item or variation returns 404 resource_missing.

Add a variation location

POST/api/v3/items/{item_id}/variations/{variation_id}/locations

Required scope: items:write

Makes an existing variation available at one additional active inventory location. This endpoint creates configuration only: on-hand, reserved, incoming, and in-transit quantities always start at zero and cannot be supplied by the client.

Request fields

curl "https://yourbusiness.salesbinder.com/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d/variations/80c52be1-5ed8-4496-a5a6-48966e4956d7/locations" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: add-example-variation-location-001" \
  --data '{
    "location_id": "828e6967-55f6-4b92-81b0-af53979211f8",
    "zone_id": "63325b59-c6c3-4586-94ca-ce8ba2a47d85",
    "threshold": 5
  }'

Returns the detailed variation object and its visible locations array with 201 Created. The new location contains zero for every inventory balance, while parent and variation quantities remain unchanged.

Creating a second location entry for the same variation and location returns 409 variation_location_exists, including when concurrent requests attempt the same change. Immediate retries can reuse the same short-lived Idempotency-Key; reusing that key with different request data returns 409 idempotency_key_reused.

The item, variation, and active location must belong to the current account. The zone must belong to the selected location. Archived items are read-only, and location-assigned users can add only their assigned location.

Update a variation location

PATCH/api/v3/items/{item_id}/variations/{variation_id}/locations/{location_id}

Required scope: items:write

Updates supported configuration for an existing variation location. This endpoint does not create, move, or delete locations and cannot change inventory quantities.

Writable fields

At least one supported field is required. Quantity, location identifiers, reserved or incoming quantities, in-transit quantities, attributes, prices, and other fields are rejected.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d/variations/80c52be1-5ed8-4496-a5a6-48966e4956d7/locations/828e6967-55f6-4b92-81b0-af53979211f8" \
  --request PATCH \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: configure-example-variation-location-001" \
  --data '{
    "threshold": 5,
    "zone_id": "63325b59-c6c3-4586-94ca-ce8ba2a47d85"
  }'

Returns the updated detailed variation object and its visible locations array with 200 OK. On-hand, reserved, incoming, in-transit, variation-total, and parent-item quantities are not changed by this operation.

The item, variation, existing location row, and active location must belong together in the current account. The zone must belong to the location in the URL. Archived items are read-only, and location-assigned users can configure only their assigned location. Inaccessible or mismatched resources return 404 resource_missing.

Immediate retries can reuse the same short-lived Idempotency-Key. Reusing that key with different request data returns 409 idempotency_key_reused.

Delete a variation location

DELETE/api/v3/items/{item_id}/variations/{variation_id}/locations/{location_id}

Required scope: items:delete

Permanently removes one unused inventory location from a variation. The current user must also have SalesBinder's inventory-delete permission. If that permission is not configured, SalesBinder may use the inventory-modification permission. An explicit denial is always enforced.

curl "https://yourbusiness.salesbinder.com/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d/variations/80c52be1-5ed8-4496-a5a6-48966e4956d7/locations/828e6967-55f6-4b92-81b0-af53979211f8" \
  --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY"

Deletion is refused with 409 when the location has a nonzero on-hand, reserved, incoming, or in-transit balance; is referenced by any saved document or sales-order line; or is the variation's last remaining location. Adjustment history by itself does not block an otherwise eligible deletion. To remove the final location, use the variation deletion endpoint when the entire variation is eligible.

The location and its related configuration are deleted together. If the operation cannot be completed, no related data is removed. A successful request returns:

{
  "object": "item_variation_location",
  "item_id": "4bb16375-9674-4e38-bab0-bcb15b97b76d",
  "variation_id": "80c52be1-5ed8-4496-a5a6-48966e4956d7",
  "location_id": "828e6967-55f6-4b92-81b0-af53979211f8",
  "deleted": true
}

Archived items are read-only. The item, variation, and location row must belong together in the current account, and a location-assigned user can delete only their assigned location. An inaccessible or mismatched resource returns 404 resource_missing. DELETE requests do not use Idempotency-Key; retrying after a successful deletion returns 404 resource_missing.

Create an inventory item

POST/api/v3/items

Required scope: items:write

The name, inventory_type, and category_id fields are required. inventory_type must be quantity or unique. SalesBinder assigns the item UUID, account, item number, timestamps, source, variation count, archived state, and lifecycle status. New active items receive status 12 (available); clients cannot set status_id directly.

Writable fields

Starting quantity is recorded in SalesBinder's item activity and adjustment history. Later quantity changes are not made through the item update endpoint.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/items" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: create-example-item-001" \
  --data '{
    "name": "Example Widget",
    "inventory_type": "quantity",
    "category_id": "c9164a6b-8c81-4162-b2f4-e8a241a203a6",
    "sku": "WIDGET-01",
    "price": "19.95",
    "cost": "8.25",
    "quantity": 25,
    "threshold": 5
  }'

Returns the created item object with 201 Created. See idempotent requests before automatically retrying creates.

Update an inventory item

PATCH or PUT/api/v3/items/{item_id}

Required scope: items:write

Send only the fields that should change. The writable fields are the same as creation except inventory_type and quantity, which cannot be changed through this endpoint.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d" \
  --request PATCH \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Updated Example Widget",
    "price": "21.50",
    "threshold": 8
  }'

Returns the updated item object with 200 OK. Archived items are read-only. status_id is server-managed and cannot be supplied. For items with variations, this endpoint can update ordinary descriptive and commercial fields but does not relocate the item or change its variation structure.

Adjust an inventory item's quantity

POST/api/v3/items/{item_id}/adjustments

Required scope: items:write

Creates one audited quantity adjustment for a basic quantity-tracked item. Send a positive quantity_delta to add stock or a negative value to remove stock. The API locks the item while calculating and saving the new quantity so concurrent adjustments cannot overwrite one another.

Request fields

Other fields, including an absolute quantity, are rejected. This prevents a stale client from overwriting adjustments made by another user or integration.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d/adjustments" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: adjust-example-item-001" \
  --data '{
    "quantity_delta": -2,
    "reason": "Damaged during handling"
  }'

Returns the updated item object with 201 Created. Adjustment requests support short-lived idempotency so immediate retries do not apply the same quantity change twice.

This operation requires the user's current inventory-modification permission and follows the user's assigned inventory-location boundary. Archived items cannot be adjusted. API v3 does not support quantity adjustments for unique items.

Adjust a variation's quantity at a location

POST/api/v3/items/{item_id}/variations/{variation_id}/locations/{location_id}/adjustments

Required scope: items:write

Creates one audited quantity adjustment for a variation at a specific inventory location. The variation must belong to the item, and the location must already be assigned to that variation. Concurrent adjustments are protected from overwriting one another.

Request fields

Absolute quantities and additional fields are rejected. The item, variation, and location identifiers are supplied by the URL and cannot be overridden in the request body.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d/variations/80c52be1-5ed8-4496-a5a6-48966e4956d7/locations/828e6967-55f6-4b92-81b0-af53979211f8/adjustments" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: adjust-example-variation-001" \
  --data '{
    "quantity_delta": -2,
    "reason": "Damaged during handling"
  }'

Returns the updated item variation object, including its recalculated visible totals and locations array, with 201 Created. SalesBinder recalculates the parent item and variation totals and records the adjustment in item activity and inventory history.

Adjustment requests support short-lived idempotency so immediate retries do not apply the same location quantity change twice. A location-assigned user can adjust only the location assigned by their current SalesBinder permissions. Archived items cannot be adjusted. A mismatched item, variation, or location returns 404 resource_missing without revealing an inaccessible record.

Archive an inventory item

POST/api/v3/items/{item_id}/archive

Required scope: items:write

Archives an inventory item without permanently deleting it. The item's quantity and other inventory data are preserved. Archiving an item that is already archived succeeds without changing account record usage again. This endpoint does not accept a request body.

curl "https://yourbusiness.salesbinder.com/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d/archive" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY"

Returns the item object with archived set to true and 200 OK.

Unarchive an inventory item

POST/api/v3/items/{item_id}/unarchive

Required scope: items:write

Restores an archived inventory item. Unarchiving increases the account's active record usage, so the operation returns 403 record_limit_exceeded when the account has reached its effective record limit. An item that is already active succeeds without consuming another record slot. This endpoint does not accept a request body.

curl "https://yourbusiness.salesbinder.com/api/v3/items/4bb16375-9674-4e38-bab0-bcb15b97b76d/unarchive" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY"

Returns the item object with archived set to false and 200 OK.

Archive and unarchive operations require the user's current inventory-modification permission and follow account and assigned-location boundaries. Both operations set a final state and are safe to repeat without an Idempotency-Key.