API docs

Products, categories, vendors

Permission: products (read / write).

The product object

{
  "object": "product",
  "id": 617,
  "sku": "CDL-SSD-08",
  "upc": "850012345617",
  "name": "Sea Salt & Driftwood Soy Candle 8oz",
  "brand": "Wick & Ember",
  "manufacturer": "Wick & Ember Studio",
  "model": null,
  "description": "Hand-poured soy wax, cotton wick, 45-hour burn.",
  "product_type": "general",
  "category_id": 142,
  "vendor_id": 33,
  "vendor_sku": "WES-SSD-08",
  "is_active": true,
  "is_serialized": false,
  "tracks_lots": false,
  "track_inventory": true,
  "min_age": null,
  "tax_class": "standard",
  "price_cents": 2400,
  "cost_cents": 650,
  "map_price_cents": null,
  "compare_at_cents": null,
  "sale_price_cents": null,
  "sale_starts_at": null,
  "sale_ends_at": null,
  "sale_scope": "store",
  "effective_price_cents": 2400,
  "weight_grams": 310,
  "image_url": "https://cdn11.bigcommerce.com/…/ssd-8oz.jpg",
  "reorder_point": 12,
  "bigcommerce": { "product_id": 212, "variant_id": 305 },
  "flxpoint_product_id": null,
  "inventory": [ { "object": "inventory_level", "product_id": 617, "location_id": 18, "qty_on_hand": 22, "qty_reserved": 0, "qty_available": 22, "reorder_point": null, "bin_location": "Wall A", "updated_at": "2026-09-24T06:22:22Z" } ],
  "created_at": "2026-09-03T15:10:00Z",
  "updated_at": "2026-09-24T06:22:22Z"
}

Field	Notes
`product_type`	`general`, `service`, `fee`, `gift_card`
`is_serialized`	Stocked as individual units with serial numbers (see Inventory)
`tracks_lots`	Stocked in lots with lot numbers and expiry dates (see Inventory). A product is serialized or lot-tracked, never both.
`tax_class`	`standard`, `exempt`, `service`
`effective_price_cents`	`sale_price_cents` while a sale window is open, otherwise `price_cents`
`sale_scope`	`store` (counter only) or `store_online` (also pushed to BigCommerce)
`inventory`	Levels at the locations the key can see. Always on single-product responses; on lists with `include=inventory`

List products

GET /v1/products

Filter
`sku`, `upc`, `vendor_sku`	Exact match
`product_type`, `category_id`, `vendor_id`, `bigcommerce_product_id`	Exact match
`is_active`	`true` / `false`
`q`	Name, SKU prefix, model, or exact UPC
`include=inventory`	Embed levels
`updated_since`, `limit`, `cursor`	See Conventions

curl "https://app.blackbeachpos.com/api/v1/products?category_id=142&include=inventory&limit=100" \
  -H "Authorization: Bearer $KEY"

Get a product

GET /v1/products/{id}: the product with its inventory levels.

Create a product

POST /v1/products (write). Requires name and price_cents. Everything else is optional:

sku is generated if you leave it out.
Send the read shape; reorder_point is accepted (and the internal default_reorder_point).
is_serialized and tracks_lots can't both be true.

curl -X POST https://app.blackbeachpos.com/api/v1/products \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d3f0c1e-2b8a-4c55-9d1e-0f6a2c1b9e44" \
  -d '{
    "sku": "CDL-FIG-08",
    "name": "Fig & Black Currant Soy Candle 8oz",
    "brand": "Wick & Ember",
    "product_type": "general",
    "tax_class": "standard",
    "price_cents": 2400,
    "cost_cents": 650,
    "category_id": 142,
    "vendor_id": 33,
    "vendor_sku": "WES-FIG-08",
    "reorder_point": 12
  }'

Returns 201 with the product.

Possible errors:

409 SKU_TAKEN
400 VALIDATION_ERROR for an unknown category_id or vendor_id, or is_serialized and tracks_lots both set

Update a product

PATCH /v1/products/{id} (write). Send only the fields you're changing.

Prices, descriptions and the rest are ordinary edits.
How it's stocked. is_serialized and tracks_lots can change only while no location has stock on hand: otherwise 409 HAS_STOCK. Sending the current value is fine.
Sale prices online. Changing sale_price_cents, sale_starts_at or sale_ends_at on a product with sale_scope: "store_online" also queues the sale price to BigCommerce.

curl -X PATCH https://app.blackbeachpos.com/api/v1/products/617 \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "price_cents": 2600, "sale_price_cents": 2200, "sale_starts_at": "2026-10-01T04:00:00Z", "sale_ends_at": "2026-10-08T04:00:00Z" }'

Delete a product

DELETE /v1/products/{id} (write). Refused with 409 HAS_STOCK while any location has stock on hand. To take a product out of use, set is_active: false instead.

{ "status": "ok", "data": { "object": "product", "id": 617, "deleted": true } }

Vendors

GET /v1/vendors (products:read). Paginated, with updated_since.

{ "object": "vendor", "id": 34, "name": "Aromatique Supply Co.", "code": "ASC", "contact_name": "Rep Desk", "email": "orders@example.com", "phone": "800-555-0100", "website": "https://example.com", "is_distributor": true, "flxpoint_source_id": "src_8812", "status": "active", "updated_at": "2026-09-03T15:10:00Z" }