Skip to content
/Item Groups

Sortly API (1.0.0)

Sortly API can be used to manage items and folders in your Sortly account. Our API is organized around REST. It returns JSON-encoded responses and uses standard HTTP response codes. This API is only available on Sortly Enterprise Plan subscription.

NOTE:

  • This feature is currently under beta. Please expect minor updates in the near future.

  • Contact dev-support@sortly.com for developer support.

Authentication

Authentication to the API is performed via OAuth 2.0. Under this, you must provide your secret key as the Bearer token in the Authorization header. All requests must be made over HTTPS.

Getting Started

  • Visit: https://app.sortly.com/public-api to obtain an API access key pair for your account.

  • Use the secret key as the Bearer token.

Rate Limiting

Sortly API calls are rate limited. You can make 1000 requests per API in a 15-minute window. Rate limit information in available in the HTTP headers of the API response.

HeaderDescription
Sortly-Rate-Limit-MaxMaximum number of requests allowed within the 15-minute window
Sortly-Rate-Limit-RemainingNumber of requests remaining in the current 15-minute window
Sortly-Rate-Limit-ResetThe time at which the current rate limit window resets.(in seconds)

Once you go over the rate limit you will receive a HTTP 429 Too Many Requests error response.

Download OpenAPI description
index.json
index.yaml
Languages
Servers
Mock server
https://developer.sortly.com/_mock
https://api.sortly.co

Items

Operations

Item Groups

Operations

Create Item Group

Request

Headers
Acceptstring

e.g. application/json

Example: application/json
Authorizationstring

e.g. Bearer

Example: Bearer <Enter Secret Key Here>
Bodyapplication/json
idnumber

ID of the instance

namestringrequired

Name of item variant group

sidstring

Sortly system ID of the item variant group

photo_idsArray of objects

List of photo ids

photosArray of objects

Could be one of:

label_urlstring

QR url OR barcode value

label_url_typestring

QR OR barcode type.

Allowed values: [ 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, org.ansi.Interleaved2of5, org.iso.DataMatrix, com.sortly.textEntry ]

label_url_extrastring

QR url OR barcode value

label_url_extra_typestring

QR OR barcode type.

Allowed values: [ 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, org.ansi.Interleaved2of5, org.iso.DataMatrix, com.sortly.textEntry ]

group_attributesArray of objectsrequired
curl -i -X POST \
  https://developer.sortly.com/_mock/api/v1/item_groups \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Enter Secret Key Here>' \
  -H 'Content-Type: application/json' \
  -d '{
    "item_group": {
      "name": "T-shirt",
      "photo_ids": [
        154,
        648
      ],
      "attributes": [
        {
          "name": "Color",
          "order": 0,
          "options": [
            {
              "name": "Yellow",
              "order": 0
            },
            {
              "name": "Black",
              "order": 1
            },
            {
              "name": "Red",
              "order": 2
            }
          ]
        },
        {
          "name": "Size",
          "order": 1,
          "options": [
            {
              "name": "XL",
              "order": 0
            },
            {
              "name": "L",
              "order": 1
            },
            {
              "name": "M",
              "order": 2
            },
            {
              "name": "S",
              "order": 3
            }
          ]
        }
      ]
    }
  }'

Responses

OK

Headers
Sortly-Rate-Limit-Maxstring
Sortly-Rate-Limit-Remainingstring
Sortly-Rate-Limit-Resetstring
Bodyapplication/json
idstring
namestring
sidstring
label_urlstring
label_url_typestring
label_url_extraany or null
label_url_extra_typeany or null
photosArray of objects
attributesArray of objects
Response
application/json
{
  "id": "82b8c7c9-d7a0-49a8-830e-8f01ed58a5dc",
  "name": "T-shirt",
  "sid": "S01UOG0005",
  "label_url": "sy://BARCODE/m_barcode_us/S01UOG0005",
  "label_url_type": "com.sortly.sortlyLabel",
  "label_url_extra": null,
  "label_url_extra_type": null,
  "photos": [
    { … },
    { … }
  ],
  "attributes": [
    { … },
    { … }
  ]
}

List of Item Groups

Request

Query
per_pagenumber

Page size | Defaults to 10

Example: per_page=2
pagenumber

Page number | Defaults to 1

Example: page=1
includestring

Includes item variants of each group

Example: include=variants,photos
updated_sincenumber

Filter by updated at | If updated since is not provided, the end point functions similar to list endpoint | Number of seconds since the Epoch.

Example: updated_since=1559120004
Headers
Acceptstring

e.g. application/json

Example: application/json
Authorizationstring

e.g. Bearer

Example: Bearer <Enter Secret Key Here>
curl -i -X GET \
  'https://developer.sortly.com/_mock/api/v1/item_groups?per_page=2&page=1&include=variants%2Cphotos&updated_since=1559120004' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Enter Secret Key Here>'

Responses

OK

Headers
Sortly-Rate-Limit-Maxstring
Sortly-Rate-Limit-Remainingstring
Sortly-Rate-Limit-Resetstring
Bodyapplication/json
item_groupsArray of objects
Response
application/json
{
  "item_groups": [
    { … }
  ]
}

Fetch Item Group

Request

Path
item_group_idstringrequired

ID of Item Group

Example: 82b8c7c9-d7a0-49a8-830e-8f01ed58a5dc
Query
includestring

Includes item variants of each group

Example: include=variants,photos
Headers
Acceptstring

e.g. application/json

Example: application/json
Authorizationstring

e.g. Bearer

Example: Bearer <Enter Secret Key Here>
curl -i -X GET \
  'https://developer.sortly.com/_mock/api/v1/item_groups/82b8c7c9-d7a0-49a8-830e-8f01ed58a5dc?include=variants%2Cphotos' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Enter Secret Key Here>'

Responses

OK

Headers
Sortly-Rate-Limit-Maxstring
Sortly-Rate-Limit-Remainingstring
Sortly-Rate-Limit-Resetstring
Bodyapplication/json
idstring
namestring
sidstring
label_urlstring
label_url_typestring
label_url_extraany or null
label_url_extra_typeany or null
photosArray of objects
attributesArray of objects
variantsArray of objects
Response
application/json
{
  "id": "82b8c7c9-d7a0-49a8-830e-8f01ed58a5dc",
  "name": "T-shirt",
  "sid": "S01UOG0005",
  "label_url": "sy://BARCODE/m_barcode_us/S01UOG0005",
  "label_url_type": "com.sortly.sortlyLabel",
  "label_url_extra": null,
  "label_url_extra_type": null,
  "photos": [
    { … },
    { … }
  ],
  "attributes": [
    { … },
    { … }
  ],
  "variants": [
    { … }
  ]
}

Update an Item Group

Request

Headers
Acceptstring

e.g. application/json

Example: application/json
Authorizationstring

e.g. Bearer

Example: Bearer <Enter Secret Key Here>
Bodyapplication/json
idnumber

ID of the instance

namestringrequired

Name of item variant group

sidstring

Sortly system ID of the item variant group

photo_idsArray of objects

List of photo ids

photosArray of objects

Could be one of:

label_urlstring

QR url OR barcode value

label_url_typestring

QR OR barcode type.

Allowed values: [ 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, org.ansi.Interleaved2of5, org.iso.DataMatrix, com.sortly.textEntry ]

label_url_extrastring

QR url OR barcode value

label_url_extra_typestring

QR OR barcode type.

Allowed values: [ 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, org.ansi.Interleaved2of5, org.iso.DataMatrix, com.sortly.textEntry ]

group_attributesArray of objectsrequired
curl -i -X PUT \
  'https://developer.sortly.com/_mock/api/v1/item_groups/{item_group_id}' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Enter Secret Key Here>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Shirt",
    "attributes": [
      {
        "id": "13360e26-5d0a-4450-b6c5-5ff209123ea3",
        "name": "Color",
        "order": 0,
        "options": [
          {
            "id": "4e3a75d6-31b5-49f6-ad9b-58d97c08ee19",
            "name": "Yellow",
            "order": 0
          },
          {
            "id": "d0c650ed-c180-4d4c-9884-f483c59bb97d",
            "name": "Dark",
            "order": 1
          },
          {
            "id": "64d76318-1721-4c67-bb97-fc4f93d0bff1",
            "name": "Red",
            "order": 2
          },
          {
            "name": "White",
            "order": 3
          }
        ]
      },
      {
        "id": "0bb90eca-869a-4be0-90c7-eebb8b1d25b3",
        "name": "Size",
        "order": 1,
        "options": [
          {
            "id": "45c6672c-c3a7-4db3-9d04-f255876b46b3",
            "name": "XL",
            "order": 0
          },
          {
            "id": "eda8b7f0-0384-4144-b6e4-6b116577c03b",
            "name": "L",
            "order": 1
          },
          {
            "id": "c9edd56f-cc18-4bf4-a46b-80081fc181ab",
            "name": "M",
            "order": 2
          },
          {
            "id": "8d12e556-ad25-4b67-900e-5e66451c2c36",
            "name": "S",
            "order": 3
          }
        ]
      }
    ]
  }'

Responses

OK

Headers
Sortly-Rate-Limit-Maxstring
Sortly-Rate-Limit-Remainingstring
Sortly-Rate-Limit-Resetstring
Bodyapplication/json
idstring
namestring
sidstring
label_urlstring
label_url_typestring
label_url_extraany or null
label_url_extra_typeany or null
photosArray of objects
attributesArray of objects
Response
application/json
{
  "id": "82b8c7c9-d7a0-49a8-830e-8f01ed58a5dc",
  "name": "T-shirt",
  "sid": "S01UOG0005",
  "label_url": "sy://BARCODE/m_barcode_us/S01UOG0005",
  "label_url_type": "com.sortly.sortlyLabel",
  "label_url_extra": null,
  "label_url_extra_type": null,
  "photos": [
    { … },
    { … }
  ],
  "attributes": [
    { … },
    { … }
  ]
}

Delete Item Group

Request

Path
item_group_idstringrequired

ID of Item Group

Example: 82b8c7c9-d7a0-49a8-830e-8f01ed58a5dc
Headers
Acceptstring

e.g. application/json

Example: application/json
Authorizationstring

e.g. Bearer

Example: Bearer <Enter Secret Key Here>
curl -i -X DELETE \
  https://developer.sortly.com/_mock/api/v1/item_groups/82b8c7c9-d7a0-49a8-830e-8f01ed58a5dc \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Enter Secret Key Here>'

Responses

No Content

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

Units of Measure

Operations

Custom Fields

Operations

Alerts

Operations
© Sortly Inc.