Private API reference

Inventory

Private Inventory API endpoints

Endpoints

GET/inventory_items
POST/inventory_items
GET/inventory_items/{inventory_item_id}
PUT/inventory_items/{inventory_item_id}
POST/inventory_items/{inventory_item_id}/archive
GET/inventory_groups
POST/inventory_groups
GET/inventory_groups/{inventory_group_id}
PUT/inventory_groups/{inventory_group_id}

Get list of inventory items

GET /inventory_items

Query parameters

pageoptionalinteger

Page number

Defaults to 1.

per_pageoptionalinteger

Items per page

Defaults to 15.

group_idoptionalinteger

Filter by inventory group ID

statusoptionalboolean

Filter by active status

queryoptionalstring

Search by name or SKU

Returnsobject

Inventory items list response

Error responses

422object

A query parameter fails validation: page is not an integer of at least 1, per_page is not an integer between 1 and 100, group_id is not an integer, status is not 0 or 1, or query is longer than 255 characters.

curl https://api.subbly.co/private/v1/inventory_items \
  -H 'X-API-KEY: <api-key>'

Response

{
  "pagination": {
    "current_page": 1,
    "last_page": 2,
    "from": 1,
    "to": 1,
    "total": 20
  },
  "data": [
    {
      "id": 1,
      "sku": "sku",
      "name": "name",
      "description": "description",
      "photo_url": "photo_url",
      "buy_price": 1,
      "msrp_price": 1,
      "stock_count": 1,
      "status": true,
      "inventory_group_id": 1,
      "inventory_group": {
        "id": 1,
        "name": "name"
      },
      "weight": 1.5,
      "width": 1.5,
      "height": 1.5,
      "depth": 1.5,
      "hs_code": "hs_code",
      "country_origin_id": 1,
      "priority": 1,
      "tags": [
        "tags"
      ],
      "tags_meta": [
        {
          "id": 12,
          "value": "VIP"
        }
      ],
      "low_stock": true,
      "out_of_stock": true,
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T10:30:00Z"
    }
  ]
}

Create a new inventory item

POST /inventory_items

Request body

nameRequiredstring

skuRequiredstring

Unique SKU within the shop

stock_countRequiredinteger

statusRequiredinteger

Possible values: 0, 1.

priorityoptionalinteger | null

inventory_group_idoptionalinteger | null

buy_priceoptionalinteger | null

Buy price in cents

msrp_priceoptionalinteger | null

MSRP price in cents

descriptionoptionalstring | null

photo_urloptionalstring | null

Format: url.

weightoptionalnumber | null

widthoptionalnumber | null

heightoptionalnumber | null

depthoptionalnumber | null

hs_codeoptionalstring | null

Harmonized System code

country_origin_idoptionalinteger | null

Country of origin ID

tagsoptionalobject

ReturnsInventoryItem

Inventory item created successfully

Error responses

422object

The body fails validation. name, sku, stock_count and status are required. sku must be at most 100 characters and unique among the non-archived items of the shop ("The sku has already been taken."). status must be 0 or 1. inventory_group_id must be a group of this shop that is not deleted, and country_origin_id must be an existing shipping country. priority must be at least 1, buy_price and msrp_price at least 0, and weight, width, height and depth at least 0.01. name, description and hs_code allow up to 255 characters, photo_url must be a valid URL, and each tags.create.*.value must be a distinct string of up to 255 characters.

curl -X POST https://api.subbly.co/private/v1/inventory_items \
  -H 'X-API-KEY: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "name",
  "sku": "sku",
  "stock_count": 1,
  "status": 0,
  "priority": 1,
  "inventory_group_id": 1,
  "buy_price": 0,
  "msrp_price": 0,
  "description": "description",
  "photo_url": "https://example.com",
  "weight": 0.01,
  "width": 0.01,
  "height": 0.01,
  "depth": 0.01,
  "hs_code": "hs_code",
  "country_origin_id": 1,
  "tags": {
    "create": [
      {
        "value": "value"
      }
    ]
  }
}'

Response

{
  "id": 1,
  "sku": "sku",
  "name": "name",
  "description": "description",
  "photo_url": "photo_url",
  "buy_price": 1,
  "msrp_price": 1,
  "stock_count": 1,
  "status": true,
  "inventory_group_id": 1,
  "inventory_group": {
    "id": 1,
    "name": "name"
  },
  "weight": 1.5,
  "width": 1.5,
  "height": 1.5,
  "depth": 1.5,
  "hs_code": "hs_code",
  "country_origin_id": 1,
  "priority": 1,
  "tags": [
    "tags"
  ],
  "tags_meta": [
    {
      "id": 12,
      "value": "VIP"
    }
  ],
  "low_stock": true,
  "out_of_stock": true,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

Get inventory item by ID

GET /inventory_items/{inventory_item_id}

Path parameters

inventory_item_idRequiredinteger

Inventory item ID

ReturnsInventoryItem

Inventory item object response

Error responses

400object

The inventory item exists but belongs to another shop.

404object

No inventory item exists with this ID.

curl https://api.subbly.co/private/v1/inventory_items/{inventory_item_id} \
  -H 'X-API-KEY: <api-key>'

Response

{
  "id": 1,
  "sku": "sku",
  "name": "name",
  "description": "description",
  "photo_url": "photo_url",
  "buy_price": 1,
  "msrp_price": 1,
  "stock_count": 1,
  "status": true,
  "inventory_group_id": 1,
  "inventory_group": {
    "id": 1,
    "name": "name"
  },
  "weight": 1.5,
  "width": 1.5,
  "height": 1.5,
  "depth": 1.5,
  "hs_code": "hs_code",
  "country_origin_id": 1,
  "priority": 1,
  "tags": [
    "tags"
  ],
  "tags_meta": [
    {
      "id": 12,
      "value": "VIP"
    }
  ],
  "low_stock": true,
  "out_of_stock": true,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

Update an inventory item

PUT /inventory_items/{inventory_item_id}

Path parameters

inventory_item_idRequiredinteger

Inventory item ID

Request body

nameoptionalstring

skuoptionalstring

stock_countoptionalinteger

statusoptionalinteger

Possible values: 0, 1.

priorityoptionalinteger | null

inventory_group_idoptionalinteger

buy_priceoptionalinteger | null

Buy price in cents

msrp_priceoptionalinteger | null

MSRP price in cents

descriptionoptionalstring | null

photo_urloptionalstring | null

Format: url.

weightoptionalnumber | null

widthoptionalnumber | null

heightoptionalnumber | null

depthoptionalnumber | null

hs_codeoptionalstring | null

country_origin_idoptionalinteger | null

tagsoptionalobject

ReturnsInventoryItem

Inventory item updated successfully

Error responses

400object

The inventory item is archived (entity_archived), or it belongs to another shop (bad_request).

404object

No inventory item exists with this ID.

422object

A field you send fails validation. Every field is optional, but each one follows the create rules. sku must be unique among the other non-archived items of the shop ("The sku has already been taken."). inventory_group_id cannot be null and must be a group of this shop that is not deleted. country_origin_id must be an existing shipping country. Each tags.delete.*.id must be an integer.

curl -X PUT https://api.subbly.co/private/v1/inventory_items/{inventory_item_id} \
  -H 'X-API-KEY: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "name",
  "sku": "sku",
  "stock_count": 1,
  "status": 0,
  "priority": 1,
  "inventory_group_id": 1,
  "buy_price": 0,
  "msrp_price": 0,
  "description": "description",
  "photo_url": "https://example.com",
  "weight": 0.01,
  "width": 0.01,
  "height": 0.01,
  "depth": 0.01,
  "hs_code": "hs_code",
  "country_origin_id": 1,
  "tags": {
    "create": [
      {
        "value": "value"
      }
    ],
    "delete": [
      {
        "id": 1
      }
    ]
  }
}'

Response

{
  "id": 1,
  "sku": "sku",
  "name": "name",
  "description": "description",
  "photo_url": "photo_url",
  "buy_price": 1,
  "msrp_price": 1,
  "stock_count": 1,
  "status": true,
  "inventory_group_id": 1,
  "inventory_group": {
    "id": 1,
    "name": "name"
  },
  "weight": 1.5,
  "width": 1.5,
  "height": 1.5,
  "depth": 1.5,
  "hs_code": "hs_code",
  "country_origin_id": 1,
  "priority": 1,
  "tags": [
    "tags"
  ],
  "tags_meta": [
    {
      "id": 12,
      "value": "VIP"
    }
  ],
  "low_stock": true,
  "out_of_stock": true,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

Archive an inventory item

POST /inventory_items/{inventory_item_id}/archive

Path parameters

inventory_item_idRequiredinteger

Inventory item ID

ReturnsInventoryItem

Inventory item archived

Error responses

400object

The inventory item is already archived (entity_archived), or it belongs to another shop (bad_request).

404object

No inventory item exists with this ID.

curl -X POST https://api.subbly.co/private/v1/inventory_items/{inventory_item_id}/archive \
  -H 'X-API-KEY: <api-key>'

Response

{
  "id": 1,
  "sku": "sku",
  "name": "name",
  "description": "description",
  "photo_url": "photo_url",
  "buy_price": 1,
  "msrp_price": 1,
  "stock_count": 1,
  "status": true,
  "inventory_group_id": 1,
  "inventory_group": {
    "id": 1,
    "name": "name"
  },
  "weight": 1.5,
  "width": 1.5,
  "height": 1.5,
  "depth": 1.5,
  "hs_code": "hs_code",
  "country_origin_id": 1,
  "priority": 1,
  "tags": [
    "tags"
  ],
  "tags_meta": [
    {
      "id": 12,
      "value": "VIP"
    }
  ],
  "low_stock": true,
  "out_of_stock": true,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

Get list of inventory groups

GET /inventory_groups

Query parameters

pageoptionalinteger

Page number

Defaults to 1.

per_pageoptionalinteger

Items per page

Defaults to 15.

queryoptionalstring

Search by name or brand name

Returnsobject

Inventory groups list response

Error responses

422object

A query parameter fails validation: page is not an integer of at least 1, per_page is not an integer between 1 and 100, or query is longer than 255 characters.

curl https://api.subbly.co/private/v1/inventory_groups \
  -H 'X-API-KEY: <api-key>'

Response

{
  "pagination": {
    "current_page": 1,
    "last_page": 2,
    "from": 1,
    "to": 1,
    "total": 20
  },
  "data": [
    {
      "id": 1,
      "name": "name",
      "brand_name": "brand_name",
      "description": "description",
      "status": true,
      "items_count": 1,
      "total_stock": 1,
      "low_stock_count": 1,
      "out_of_stock_count": 1,
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T10:30:00Z"
    }
  ]
}

Create a new inventory group

POST /inventory_groups

Request body

nameRequiredstring

brand_nameoptionalstring | null

ReturnsInventoryGroup

Inventory group created successfully

Error responses

422object

name is missing, is not a string, or is longer than 255 characters, or brand_name is not a string or is longer than 255 characters.

curl -X POST https://api.subbly.co/private/v1/inventory_groups \
  -H 'X-API-KEY: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "name",
  "brand_name": "brand_name"
}'

Response

{
  "id": 1,
  "name": "name",
  "brand_name": "brand_name",
  "description": "description",
  "status": true,
  "items_count": 1,
  "total_stock": 1,
  "low_stock_count": 1,
  "out_of_stock_count": 1,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

Get inventory group by ID

GET /inventory_groups/{inventory_group_id}

Path parameters

inventory_group_idRequiredinteger

Inventory group ID

ReturnsInventoryGroup

Inventory group object response

Error responses

400object

The inventory group exists but belongs to another shop.

404object

No inventory group exists with this ID, or the group is deleted.

curl https://api.subbly.co/private/v1/inventory_groups/{inventory_group_id} \
  -H 'X-API-KEY: <api-key>'

Response

{
  "id": 1,
  "name": "name",
  "brand_name": "brand_name",
  "description": "description",
  "status": true,
  "items_count": 1,
  "total_stock": 1,
  "low_stock_count": 1,
  "out_of_stock_count": 1,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

Update an inventory group

PUT /inventory_groups/{inventory_group_id}

Path parameters

inventory_group_idRequiredinteger

Inventory group ID

Request body

nameoptionalstring

brand_nameoptionalstring | null

descriptionoptionalstring | null

ReturnsInventoryGroup

Inventory group updated successfully

Error responses

400object

The inventory group exists but belongs to another shop.

404object

No inventory group exists with this ID, or the group is deleted.

422object

name is not a string or is longer than 255 characters, brand_name is not a string or is longer than 255 characters, or description is not a string.

curl -X PUT https://api.subbly.co/private/v1/inventory_groups/{inventory_group_id} \
  -H 'X-API-KEY: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "name",
  "brand_name": "brand_name",
  "description": "description"
}'

Response

{
  "id": 1,
  "name": "name",
  "brand_name": "brand_name",
  "description": "description",
  "status": true,
  "items_count": 1,
  "total_stock": 1,
  "low_stock_count": 1,
  "out_of_stock_count": 1,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}