Skip to content

Sortly API

The Sortly API lets you work with your inventory from your own systems: add and update items, keep stock levels in sync, and track what goes out on a job.

Available on the Sortly Enterprise Plan. All requests go to https://api.sortly.co over HTTPS and return JSON. Email dev-support@sortly.com with questions or issues.

New here? Start with Getting Started, then read Items and Folders so the vocabulary in the endpoint reference makes sense. Once you know what you're building, jump to the matching Use Case Guide.

Download OpenAPI description
index.json
index.yaml
Languages
Servers
https://api.sortly.co

Getting Started

Make your first Sortly API call in about five minutes.

Guides

The mechanics every integration needs, whatever you are building: how to authenticate, how to page through results, what the rate limit costs you, and what Sortly sends back when something goes wrong.

Core Concepts

The vocabulary the endpoint reference assumes you already have. Read these once and the field names in the reference stop needing explanation.

Build Your Inventory

Goal: get your existing inventory into Sortly from a spreadsheet, database or another system.

Every command below runs as-is once you swap in your own secret key.

Manage Your Inventory

Goal: keep the inventory you have already loaded accurate as it changes: what it looks like, how much of it there is, and where it sits.

Track Stock Levels

Goal: be told when something is running low, instead of watching it yourself.

Sync Inventory

Goal: keep another system (an ERP, a warehouse tool, a dashboard) in step with Sortly.

Sync Jobs

Goal: keep Sortly jobs in step with the work orders in your external system, from the moment one is raised to the moment it closes, so field staff work against accurate inventory and nobody keys the same movement in twice.

A job is a work order. Creating one also creates a folder to hold the items assigned to it. Jobs move through three statuses: not_started, in_progress, completed.

Each subsection below maps to one event in your system. Your system owns the job lifecycle and drives each of these calls; where you need to see the state on the Sortly side, read it with GET /api/v1/jobs on whatever schedule suits you.

Sync Purchase Orders

Goal: keep Sortly purchase orders in step with the accounting or ordering system you buy through, so both sides agree on what was ordered, what it costs and where it has got to.

A purchase order records what you ordered from a vendor and on what terms, with a list of line items drawn from your inventory. You don't need to send amount, sub_total, total or line_number: Sortly works them out from the lines.

How an order moves:

  • draft, ready_for_review and approved can each move to one another, or on to ordered
  • From ordered you can request voided or closed
  • From ordered, receiving stock also moves the order to partially_received and then received, through the receive flow rather than a status call
  • From partially_received or received, the only status you can request is closed
  • voided and closed are final

For the transitions themselves, see Manage PO Statuses.

Manage PO Statuses

Goal: move a Sortly purchase order to match where it has got to in your own process, whether that decision was made in another system or over email.

Every transition uses the same endpoint and the same two fields: the target status and the version you got from your last read.

  • A stale version is rejected with 409. Read immediately before writing, and retry with the new one.
  • Sending a status the order already has changes nothing, so a retried delivery is safe.
FromCan move to
draft, ready_for_review, approvedeach other, or ordered
orderedvoided or closed
partially_received, receivedclosed
voided, closedfinal

Anything outside that returns 400. received and partially_received cannot be requested here at all: Sortly sets them when a delivery is recorded against the order, either in the app or through the receive endpoint.

Items

Items are the things you track: stock, tools, assets, supplies. Each one has a quantity and can carry a price, photos, tags and custom fields.

Items and folders share these endpoints; type is what tells them apart. Pass "type": "item" here. For the folder side of the same endpoints, see Folders.

Operations

Update

Request

Updates fields on an existing item or folder. Only fields you include in the request body are changed. Omitted fields keep their current values. To clear a field, pass it explicitly as null. Returns 204 No Content on success.

Security
BearerAuth
Path
item_idstringrequired

Item ID

Example: 1
Body
namestring

Name of the item or folder. Max 190 characters.

Example: "Standing Desk"
pricenumber or null

Unit price.

Example: 599
quantitynumber or null

How many you have. For items measured in something other than units, see measured_quantity.

Example: 4
min_quantitynumber or null

Minimum level. When quantity reaches this, a Quantity alert on the item can notify your team. See Track Stock Levels.

Example: 2
notesstring or null

Free-text notes.

parent_idnumber or null

ID of the folder this lives in. Pass null (or omit) to place it at the top level.

Example: 10
typestring

Whether this is a trackable item or a folder that contains other things.

Enum"item""folder"
Example: "item"
label_urlstring or null

Value encoded in the item's primary QR code or barcode.

Example: "AB123AB45"
label_url_typestring or null(BarcodeType)

Symbology of the linked QR code or barcode. Use com.sortly.sortlyLabel for labels Sortly generates, or com.sortly.textEntry for a manually typed value.

Enum"org.gs1.UPC-E""org.iso.Code39""org.iso.Code39Mod43""org.gs1.EAN-13""org.gs1.EAN-8""com.intermec.Code93""org.iso.Code128""org.iso.PDF417""org.iso.Aztec""org.iso.QRCode"
Example: "org.iso.QRCode"
label_url_extrastring or null

Value encoded in the item's secondary QR code or barcode.

Example: "9780066620992"
label_url_extra_typestring or null(BarcodeType)

Symbology of the linked QR code or barcode. Use com.sortly.sortlyLabel for labels Sortly generates, or com.sortly.textEntry for a manually typed value.

Enum"org.gs1.UPC-E""org.iso.Code39""org.iso.Code39Mod43""org.gs1.EAN-13""org.gs1.EAN-8""com.intermec.Code93""org.iso.Code128""org.iso.PDF417""org.iso.Aztec""org.iso.QRCode"
Example: "org.iso.QRCode"
tagsArray of objects(Tag)

Tags on this item. Tags organize inventory across folders: by brand, colour, condition or status. Accepted on writes and returned on reads.

custom_attribute_valuesArray of objects(CustomFieldValue)

Values for your account's custom fields. Call GET /custom_fields first to get each field's custom_attribute_id.

photo_idsArray of numbers

IDs of photos that already exist in your account. To upload a new file instead, send it as photos[] with multipart/form-data.

measured_quantityobject

type and name can only be set when the item is created. On an update they are silently ignored and the item keeps the unit it was created with, so a unit change has to go through the Sortly app. Only value is writable afterwards.

option_value_idsArray of strings(uuid)

For a variant item, the option values that identify which combination this is (for example the Black and XL option IDs). Required together with item_group_id.

item_group_idstring(uuid)

The item group this variant belongs to. Required together with option_value_ids.

curl -X PUT 'https://api.sortly.co/api/v1/items/12345' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Standing Desk", "quantity": 5, "min_quantity": 2}'

Responses

No Content

Headers
Locationstring
Sortly-Rate-Limit-Maxstring
Sortly-Rate-Limit-Remainingstring
Sortly-Rate-Limit-Resetstring
Bodyapplication/json
object
Response
application/json
{}

Move

Request

Moves a quantity of an item to a different folder. The moved portion becomes a separate item in the destination, with its own id and the same sid.

  • folder_id is the destination. Pass null to move to the root level.
  • leave_zero_quantity: true keeps a zero-quantity record in the source folder. The default, false, removes the source item once its quantity reaches 0.
Security
BearerAuth
Path
item_idnumberrequired

Item ID

Example: 2
Bodyapplication/json
quantitynumberrequired

Move quantity of item

folder_idnumber

Target folder ID. If not defined then will be moved to root

leave_zero_quantityboolean

Determines wether items with zero quantity are kept or not. Default is false.

curl -X POST 'https://api.sortly.co/api/v1/items/12345/move' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"quantity": 2, "folder_id": 55, "leave_zero_quantity": false}'

Responses

OK

Headers
Sortly-Rate-Limit-Maxstring
Sortly-Rate-Limit-Remainingstring
Sortly-Rate-Limit-Resetstring
Bodyapplication/json
dataobject
Response
application/json
{
  "data": {
    "id": 1,
    "name": "with photo id2",
    "price": 10,
    "quantity": 2,
    "notes": "some notes",
    "parent_id": 2,
    "sid": "S000XT3976",
    "tag_names": [ … ],
    "tags": [ … ],
    "type": "item",
    "created_at": "2026-07-20T16:49:55.006Z",
    "updated_at": "2026-07-21T11:11:11.167Z"
  }
}

Clone

Request

Creates a copy of an item or folder with identical attributes.

  • The clone gets a new id and, by default, the same sid as the original. Pass new_sid: true to give it one of its own.
  • folder_id places the clone in a specific folder. Omit it to clone to the root level.
  • include_subtree: true recursively copies all nested items when cloning a folder.
Security
BearerAuth
Path
item_idnumberrequired

Item ID

Example: 2
Bodyapplication/json
quantitynumber

Copy item and set this quantity

folder_idnumber

Target folder ID. If not defined then will be moved to root

include_subtreeboolean

Copy with nested items or not

new_sidboolean

Copy with new SID generation or not

curl -X POST 'https://api.sortly.co/api/v1/items/12345/copy' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"quantity": 1, "folder_id": 55, "include_subtree": true, "new_sid": true}'

Responses

OK

Headers
Sortly-Rate-Limit-Maxstring
Sortly-Rate-Limit-Remainingstring
Sortly-Rate-Limit-Resetstring
Bodyapplication/json
dataobject
Response
application/json
{
  "data": {
    "id": 3,
    "name": "itemName",
    "price": 10,
    "quantity": 1,
    "notes": "newNotes",
    "type": "folder",
    "parent_id": 1,
    "created_at": "2026-07-14T09:12:04Z",
    "updated_at": "2026-07-14T09:12:04Z",
    "sid": "S01QSR0002",
    "tag_names": [ … ],
    "tags": [ … ],
    "photos": [ … ],
    "custom_attribute_values": [ … ]
  }
}

Folders

Folders are how you organize inventory by location, category, job, or whatever fits how you work. They can be nested, and items live inside them.

Folders use the same endpoints as items, with "type": "folder" and no quantity or price. Nest one inside another by setting parent_id; leave it out for the top level. To list a folder's contents, pass its id as folder_id when listing items.

Operations

Custom Fields

The extra fields defined on your account. Fetch these to get the custom_attribute_id values you need when writing custom field values onto items.

Operations

Units of Measure

The units available for tracking quantity: weight, length, volume and count.

Operations

Alerts

Alerts tell your team when stock runs low, or when a date you're tracking is coming up. Two kinds: Quantity and DateReminder.

Operations

Purchase Orders

Purchase orders record what you have ordered from a vendor and on what terms. Each one carries vendor and ship-to details plus a list of line items drawn from your inventory.

How an order moves:

  • draft, ready_for_review and approved can each move to one another, or on to ordered
  • From ordered you can request voided or closed
  • Receiving stock moves an ordered order to partially_received and then received, through the receive flow rather than a status call
  • From partially_received or received, the only status you can request is closed
  • voided and closed are final

Use the status endpoint for these transitions rather than the update endpoint.

Operations

Jobs

Jobs are work orders. Create a job, assign items to it, move it through not_started, in_progress and completed, and return items when it's done.

Operations

Changelog

Aug 5, 2026. Added Purchase Orders: list, create, fetch, update and change status.

Jul 31, 2026. Added Jobs: list, create, fetch, update, change status and delete, plus adding items to a job and returning them.

Jun 17, 2021. Added yard and gallon units of measure.

Jun 5, 2021. Added support for item variants (Item Groups).

Jan 4, 2021. Renamed attribute_value to value on custom field values (attribute_value still works). Added tags to item reads and search.

Sep 1, 2020. Added the search endpoint.

Jun 15, 2020. Added alerts.

Mar 2, 2019. First release.

© Sortly Inc.