Inventory locations

Inventory location endpoints provide the stable UUIDs required by item, variation, purchase-order, and sales-order requests. Locations and their zones can be discovered and created through the API. All operations follow the API key user's current inventory permissions.

The location object

Field	Type	Description
`id`	string	Unique inventory-location UUID.
`object`	string	Always `location`.
`name`	string	Full location name.
`short_name`	string	Short location label configured in SalesBinder.

The response includes only the location fields listed above.

List inventory locations

GET/api/v3/locations

Required scope: items:read

Returns active inventory locations belonging to the current account, ordered by name. Users restricted to one inventory location receive only their assigned location.

Query parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number. Defaults to `1`.
`limit`	integer	No	Records per page from `1` to `100`. Defaults to `20`.

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

{
  "object": "list",
  "url": "/api/v3/locations",
  "has_more": false,
  "data": [
    {
      "id": "828e6967-55f6-4b92-81b0-af53979211f8",
      "object": "location",
      "name": "Main Warehouse",
      "short_name": "Main"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_records": 1
  }
}

The endpoint uses the standard page-based pagination format. Inactive locations and locations belonging to another account are never returned.

Create an inventory location

POST/api/v3/locations

Required scope: items:write

Creates an inventory location for the current account and returns the canonical location object with 201 Created. The request requires an Idempotency-Key header; retries with the same key and body return the original location.

Field	Type	Required	Description
`name`	string	Yes	Full location name, up to 100 characters.
`short_name`	string	Yes	Short location label, up to 25 characters.
`address_1`	string	No	Street address, up to 100 characters.
`address_2`	string	No	Apartment, suite, unit, building, or floor, up to 100 characters.
`city`	string	No	City, up to 100 characters.
`region`	string	No	Province or state, up to 100 characters.
`postal_code`	string	No	Postal or ZIP code, up to 20 characters.
`country`	string	No	Country, up to 100 characters.
`manager`	string	No	Manager's name, up to 255 characters.
`email`	string	No	Valid contact email address, up to 255 characters.
`phone`	string	No	Contact phone number, up to 255 characters.
`fax`	string	No	Fax number, up to 255 characters.

curl "https://yourbusiness.salesbinder.com/api/v3/locations" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 61f757a1-cc57-41f7-90af-fe79444419f1" \
  --data '{"name":"North Warehouse","short_name":"North","city":"Vancouver","region":"BC","country":"Canada","manager":"Alex Rivera","email":"alex@example.com"}'

The caller must have live inventory-modify permission and must not be restricted to one assigned location. Account ownership and system-managed fields are always supplied by SalesBinder. Invalid fields return the standard validation error response.

The zone object

Field	Type	Description
`id`	string	Unique zone UUID.
`object`	string	Always `zone`.
`location_id`	string	UUID of the zone's parent inventory location.
`name`	string	Full zone name.
`short_name`	string	Short zone label configured in SalesBinder.
`description`	string or null	Optional zone description.

List zones at a location

GET/api/v3/locations/{location_id}/zones

Required scope: items:read

Returns zones belonging to one active, accessible inventory location, ordered by name. The endpoint accepts the standard page and limit query parameters.

curl "https://yourbusiness.salesbinder.com/api/v3/locations/828e6967-55f6-4b92-81b0-af53979211f8/zones?page=1&limit=20" \
  --header "Authorization: Bearer YOUR_API_KEY"

{
  "object": "list",
  "url": "/api/v3/locations/828e6967-55f6-4b92-81b0-af53979211f8/zones",
  "has_more": false,
  "data": [
    {
      "id": "63325b59-c6c3-4586-94ca-ce8ba2a47d85",
      "object": "zone",
      "location_id": "828e6967-55f6-4b92-81b0-af53979211f8",
      "name": "Aisle A",
      "short_name": "A",
      "description": "Primary picking aisle"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_records": 1
  }
}

A location without zones returns an empty list. An inactive location, a location in another account, or a location outside the user's assigned-location boundary returns 404 resource_missing.

Create a zone

POST/api/v3/locations/{location_id}/zones

Required scope: items:write

Creates a zone within one active, accessible inventory location and returns the canonical zone object with 201 Created. The request requires an Idempotency-Key header; retries with the same key and body return the original zone.

Field	Type	Required	Description
`name`	string	Yes	Zone name, up to 100 characters.
`short_name`	string	Yes	Short label, up to 25 characters.
`description`	string	No	Optional zone description.

curl "https://yourbusiness.salesbinder.com/api/v3/locations/828e6967-55f6-4b92-81b0-af53979211f8/zones" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 1d22ce3e-e5a2-4a45-a011-d2f8bdd2ce96" \
  --data '{"name":"Aisle B","short_name":"B","description":"Overflow picking aisle"}'

The caller must have live inventory-modify permission. An inaccessible parent location returns 404 resource_missing; invalid fields return the standard validation error response.

Update a zone

PATCH/api/v3/locations/{location_id}/zones/{zone_id}

Required scope: items:write

Updates a zone within its current location and returns the canonical zone object. Send the complete name, short_name, and optional description fields using the same field limits as zone creation. The request requires an Idempotency-Key header.

The zone must belong to the location in the route, and that location must be active and accessible to the caller. Otherwise the endpoint returns 404 resource_missing. The location relationship cannot be changed through this endpoint.

Zone deletion remains managed in SalesBinder.