Stock transfers

Use stock-transfer endpoints to create, track, send, receive, and delete inventory transfers between locations.

The stock transfer object

Field	Type	Description
`id`	string	Unique stock-transfer UUID.
`object`	string	Always `stock_transfer`.
`stock_transfer_number`	integer	Account-scoped transfer number.
`assigned_user_id`	string or null	UUID of the assigned SalesBinder user.
`status_id`	integer	Current transfer status identifier.
`status`	string or null	Current transfer status label.
`origin_location`	object	Compact `id` and `name` for the origin location.
`destination_location`	object	Compact `id` and `name` for the destination location.
`issue_date`	string or null	Transfer issue date in `YYYY-MM-DD` format.
`estimated_arrival_date`	string or null	Estimated arrival date in `YYYY-MM-DD` format.
`date_sent`	string or null	Date the transfer was sent.
`date_received`	string or null	Date the transfer was received.
`shipping_provider`	string or null	Carrier or shipping provider stored on the transfer.
`shipping_tracking_code`	string or null	Tracking code stored on the transfer.
`created_at`	string or null	ISO 8601 creation timestamp.
`updated_at`	string or null	ISO 8601 update timestamp.
`lines`	array	Transfer lines returned by retrieve and write operations. Omitted from list results.

Each retrieve-only line includes id, object, item_id, item_variation_location_id, name, description, variation, quantity, and unit_id. Prices and costs are not included.

List stock transfers

GET/api/v3/stock-transfers

Required scope: stock_transfers:read

Returns stock transfers belonging to the authenticated SalesBinder account, ordered by transfer number from newest to oldest.

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`.
`q`	string	No	Exact transfer-number or partial tracking-code search.
`assigned_user_id`	string	No	Filter by assigned-user UUID.
`origin_location_id`	string	No	Filter by origin-location UUID.
`destination_location_id`	string	No	Filter by destination-location UUID.
`status_id`	integer	No	Filter by transfer status.
`issue_date_from`	string	No	Earliest issue date in `YYYY-MM-DD` format.
`issue_date_to`	string	No	Latest issue date in `YYYY-MM-DD` format.

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

{
  "object": "list",
  "url": "/api/v3/stock-transfers",
  "has_more": false,
  "data": [
    {
      "id": "784ab346-7951-47a3-91e4-950f032d9c62",
      "object": "stock_transfer",
      "stock_transfer_number": 102,
      "assigned_user_id": "ed5dc21f-c8c8-44aa-9840-9dfd9a821164",
      "status_id": 27,
      "status": "In Transit",
      "origin_location": {"id": "50dd916b-42f1-4d7e-a38c-b4eb72df9c19", "name": "Main Warehouse"},
      "destination_location": {"id": "0ac150f5-19d5-451d-8076-7126508a7fc5", "name": "Retail Store"},
      "issue_date": "2026-07-10",
      "estimated_arrival_date": "2026-07-20",
      "date_sent": "2026-07-12",
      "date_received": null,
      "shipping_provider": "Carrier",
      "shipping_tracking_code": "TRACK-123",
      "created_at": "2026-07-10T10:00:00+00:00",
      "updated_at": "2026-07-12T09:00:00+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_records": 1
  }
}

Retrieve a stock transfer

GET/api/v3/stock-transfers/{stock_transfer_id}

Required scope: stock_transfers:read

Returns one stock transfer plus its stored lines. A transfer from another account returns 404 resource_missing.

curl "https://yourbusiness.salesbinder.com/api/v3/stock-transfers/784ab346-7951-47a3-91e4-950f032d9c62" \
  --header "Authorization: Bearer YOUR_API_KEY"

{
  "id": "784ab346-7951-47a3-91e4-950f032d9c62",
  "object": "stock_transfer",
  "stock_transfer_number": 102,
  "assigned_user_id": "ed5dc21f-c8c8-44aa-9840-9dfd9a821164",
  "status_id": 27,
  "status": "In Transit",
  "origin_location": {"id": "50dd916b-42f1-4d7e-a38c-b4eb72df9c19", "name": "Main Warehouse"},
  "destination_location": {"id": "0ac150f5-19d5-451d-8076-7126508a7fc5", "name": "Retail Store"},
  "issue_date": "2026-07-10",
  "estimated_arrival_date": "2026-07-20",
  "date_sent": "2026-07-12",
  "date_received": null,
  "shipping_provider": "Carrier",
  "shipping_tracking_code": "TRACK-123",
  "created_at": "2026-07-10T10:00:00+00:00",
  "updated_at": "2026-07-12T09:00:00+00:00",
  "lines": [
    {
      "id": "d96286ce-69ce-46e2-bde7-f4917aa7f155",
      "object": "stock_transfer_line",
      "item_id": "dc6dfe07-96f9-4e52-b87f-d743db9b8f13",
      "item_variation_location_id": 42,
      "name": "Widget",
      "description": "Blue widget",
      "variation": "Color: Blue",
      "quantity": 3,
      "unit_id": 1
    }
  ]
}

Create a stock transfer

POST/api/v3/stock-transfers

Required scope: stock_transfers:write

Creates a pending stock transfer assigned to the API key's current SalesBinder user. SalesBinder assigns the transfer number and uses the user's current local date as issue_date.

Field	Type	Required	Description
`origin_location_id`	string	Yes	Active origin-location UUID in the current account.
`destination_location_id`	string	Yes	Active destination-location UUID in the current account.
`estimated_arrival_date`	string or null	No	Date in `YYYY-MM-DD` format.
`shipping_provider`	string	No	Carrier or shipping provider.
`shipping_tracking_code`	string	No	Tracking code.
`lines`	array	Yes	One to 100 inventory lines located at the origin.

Each line requires item_id and a positive quantity. Use item_variation_location_id when the item has variations; that row must belong to the item, account, and origin location. description is optional and otherwise uses the inventory item's current description. Unique items are stored with quantity 1.

curl "https://yourbusiness.salesbinder.com/api/v3/stock-transfers" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: create-transfer-2026-07-21-1" \
  --data '{
    "origin_location_id": "50dd916b-42f1-4d7e-a38c-b4eb72df9c19",
    "destination_location_id": "0ac150f5-19d5-451d-8076-7126508a7fc5",
    "estimated_arrival_date": "2026-07-30",
    "lines": [
      {
        "item_id": "dc6dfe07-96f9-4e52-b87f-d743db9b8f13",
        "quantity": 4
      }
    ]
  }'

Returns the created stock transfer with 201 Created.

Update a stock transfer

PATCH/api/v3/stock-transfers/{stock_transfer_id}

Required scope: stock_transfers:write

Updates a pending or in-transit transfer. Completed transfers return 409 stock_transfer_update_not_allowed.

Supported top-level fields are issue_date, estimated_arrival_date, shipping_provider, shipping_tracking_code, and lines. Dates use YYYY-MM-DD; an empty estimated_arrival_date clears that optional date.

When lines is supplied, it is the complete replacement line set and must contain one to 100 lines. Include an existing line's id to update that stored line. Omit its id to add a line, and omit a previously stored line from the array to remove it. When an in-transit transfer changes, SalesBinder adjusts the affected inventory quantities automatically.

curl "https://yourbusiness.salesbinder.com/api/v3/stock-transfers/784ab346-7951-47a3-91e4-950f032d9c62" \
  --request PATCH \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: edit-transfer-784ab346-1" \
  --data '{
    "shipping_tracking_code": "TRACK-UPDATED",
    "lines": [
      {
        "id": "d96286ce-69ce-46e2-bde7-f4917aa7f155",
        "item_id": "dc6dfe07-96f9-4e52-b87f-d743db9b8f13",
        "item_variation_location_id": 42,
        "quantity": 5
      }
    ]
  }'

The origin, destination, assigned user, transfer number, send and receive dates, and status cannot be changed through this endpoint.

Send a stock transfer

POST/api/v3/stock-transfers/{stock_transfer_id}/send

Required scope: stock_transfers:send

Moves a pending transfer into transit. SalesBinder removes each transferred quantity from its origin variation location, records that quantity as in transit at the destination, and updates inventory history. Only a pending transfer can be sent; any other state returns 409 stock_transfer_send_not_allowed.

Field	Type	Required	Description
`date_sent`	string	No	Sent date in `YYYY-MM-DD` format. Defaults to the current user's local date.
`estimated_arrival_date`	string or null	No	Estimated arrival date in `YYYY-MM-DD` format. An empty value clears it.
`shipping_provider`	string	No	Carrier or shipping provider.
`shipping_tracking_code`	string	No	Tracking code.

curl "https://yourbusiness.salesbinder.com/api/v3/stock-transfers/784ab346-7951-47a3-91e4-950f032d9c62/send" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: send-transfer-784ab346-1" \
  --data '{
    "date_sent": "2026-07-21",
    "estimated_arrival_date": "2026-07-25",
    "shipping_provider": "Carrier",
    "shipping_tracking_code": "TRACK-123"
  }'

Returns the updated transfer with 200 OK and status_id 27.

Receive a stock transfer

POST/api/v3/stock-transfers/{stock_transfer_id}/receive

Required scope: stock_transfers:receive

Completes an in-transit transfer. SalesBinder removes each quantity from the destination's in-transit balance, adds it to available destination inventory, and updates inventory history. Only an in-transit transfer can be received; any other state returns 409 stock_transfer_receive_not_allowed.

Field	Type	Required	Description
`date_received`	string	No	Received date in `YYYY-MM-DD` format. Defaults to the current user's local date.
`estimated_arrival_date`	string or null	No	Estimated arrival date in `YYYY-MM-DD` format. An empty value clears it.
`shipping_provider`	string	No	Carrier or shipping provider.
`shipping_tracking_code`	string	No	Tracking code.

curl "https://yourbusiness.salesbinder.com/api/v3/stock-transfers/784ab346-7951-47a3-91e4-950f032d9c62/receive" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: receive-transfer-784ab346-1" \
  --data '{"date_received": "2026-07-22"}'

Returns the updated transfer with 200 OK and status_id 28.

Delete a stock transfer

DELETE/api/v3/stock-transfers/{stock_transfer_id}

Required scope: stock_transfers:delete

Deletes a pending, in-transit, or transferred stock transfer. Deleting an in-transit transfer restores its quantities to the origin and removes them from the destination's in-transit balance. Deleting a transferred record also removes its completed destination quantities before restoring the origin.

curl "https://yourbusiness.salesbinder.com/api/v3/stock-transfers/784ab346-7951-47a3-91e4-950f032d9c62" \
  --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY"

{
  "id": "784ab346-7951-47a3-91e4-950f032d9c62",
  "object": "stock_transfer",
  "deleted": true
}

This operation cannot be undone through API v3. A transfer whose existing inventory references can no longer be safely reversed returns 409 stock_transfer_delete_not_allowed without deleting the record.

Permissions and behavior

Read operations require stock_transfers:read and the current inventory-management permission. Create and update require stock_transfers:write; sending requires stock_transfers:send; receiving requires stock_transfers:receive; and deletion requires stock_transfers:delete. Every change also requires the current inventory-modification permission. Stock transfers use account-wide location visibility. Assigned user, origin location, and destination location do not further restrict access.