Products API

Create, read, update, and delete products. Manage variants, attributes, inventory, and SEO metadata.

Endpoints

Method	Endpoint	Description
GET	/products	List all products
POST	/products	Create a product
GET	/products/:id	Get a product
PUT	/products/:id	Update a product
DELETE	/products/:id	Delete a product (soft delete)
GET	/products/attributes	Get all attribute keys/values
GET	/products/by-attributes	Filter products by attributes
GET	/products/by-variant-group	Get all variants in a group

All endpoints are prefixed with /stores/{storeId}.

The Product Object

{
  "id": "prod_abc123",
  "storeId": "store_xyz789",
  "title": "Wireless Headphones",
  "slug": "wireless-headphones",
  "status": "published",
  "publishedAt": "2024-01-15T10:30:00.000Z",
  "description": "Premium wireless headphones with noise cancellation.",
  "price": "199.99",
  "compareAtPrice": "249.99",
  "sku": "WH-001",
  "barcode": "1234567890123",
  "variantGroupId": "headphones-color-variants",
  "attributes": {
    "color": "Black",
    "connectivity": "Bluetooth 5.0"
  },
  "trackStock": true,
  "stock": 50,
  "allowBackorder": false,
  "categoryIds": ["cat_electronics", "cat_audio"],
  "primaryMediaId": "media_img001",
  "mediaIds": ["media_img001", "media_img002", "media_img003"],
  "seoTitle": "Wireless Headphones - Premium Audio",
  "seoDescription": "Shop premium wireless headphones with active noise cancellation.",
  "seoKeywords": "headphones, wireless, bluetooth, noise cancelling",
  "seoImageId": "media_img001",
  "createdAt": "2024-01-10T08:00:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Field Reference

Field	Type	Description
id	string	Unique identifier (UUID)
title	string	Product title (1-255 chars, required)
slug	string	URL-friendly identifier (unique per store)
status	enum	draft, published, archived, deleted
price	string	Price as decimal string (e.g., "99.99")
compareAtPrice	string?	Original price for sale display
sku	string?	Stock Keeping Unit (unique per store)
barcode	string?	UPC, EAN, or ISBN
variantGroupId	string?	Groups related variants together
attributes	object	Key-value pairs (e.g., color, size)
trackStock	boolean	Enable inventory tracking
stock	integer	Available quantity
allowBackorder	boolean	Allow orders when out of stock
categoryIds	string[]	Array of category IDs
primaryMediaId	string?	Main product image
mediaIds	string[]	All product images (ordered)

List Products

GET /stores/{storeId}/products

Query Parameters

Parameter	Type	Description
limit	integer	Results per page (1-200, default: 50)
offset	integer	Number of items to skip (default: 0)
status	string	Filter by status (draft, published, archived)
slug	string	Find by exact slug
sku	string	Find by exact SKU
variantGroupId	string	Filter by variant group
search	string	Search in title, description, SKU

Example

curl "https://api.barecommercecore.com/stores/{storeId}/products?status=published&limit=20" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Response

{
  "items": [
    {
      "id": "prod_abc123",
      "title": "Wireless Headphones",
      "slug": "wireless-headphones",
      "status": "published",
      "price": "199.99"
    }
  ],
  "total": 42
}

Create Product

POST /stores/{storeId}/products

Requires products:write scope.

Required Fields

title — Product name (1-255 characters)
slug — URL-friendly identifier (unique per store)
price — Price as decimal string (e.g., "99.99")

Example

curl -X POST "https://api.barecommercecore.com/stores/{storeId}/products" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Wireless Headphones",
    "slug": "wireless-headphones",
    "price": "199.99",
    "compareAtPrice": "249.99",
    "description": "Premium wireless headphones with noise cancellation.",
    "status": "draft",
    "sku": "WH-001",
    "trackStock": true,
    "stock": 100,
    "attributes": {
      "color": "Black",
      "connectivity": "Bluetooth 5.0"
    },
    "categoryIds": ["cat_electronics", "cat_audio"]
  }'

Get Product

GET /stores/{storeId}/products/{productId}

Update Product

PUT /stores/{storeId}/products/{productId}

Only include fields you want to change.

Example: Publish a Product

curl -X PUT "https://api.barecommercecore.com/stores/{storeId}/products/prod_abc123" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "published" }'

When you set status to "published" for the first time, publishedAt is automatically set.

Delete Product

DELETE /stores/{storeId}/products/{productId}

Soft-delete (sets status to "deleted"). Returns 204 No Content.

Specialized Endpoints

Get Attributes

GET /stores/{storeId}/products/attributes

Returns all attribute keys and their unique values across your product catalog.

{
  "keys": ["color", "size", "material"],
  "values": {
    "color": ["Black", "White", "Navy"],
    "size": ["S", "M", "L", "XL"],
    "material": ["Cotton", "Polyester"]
  }
}

Filter by Attributes

GET /stores/{storeId}/products/by-attributes?color=Black&size=L

Get Variants

GET /stores/{storeId}/products/by-variant-group?variantGroupId=tshirt-basic

Working with Variants

BareCommerce models variants as separate products linked by variantGroupId.

// Create the base product
await createProduct({
  title: "Basic T-Shirt - Black",
  slug: "basic-tshirt-black",
  variantGroupId: "basic-tshirt",
  price: "29.99",
  sku: "TSHIRT-BLK-M",
  attributes: { color: "Black", size: "M" },
});
 
// Create additional variant
await createProduct({
  title: "Basic T-Shirt - White",
  slug: "basic-tshirt-white",
  variantGroupId: "basic-tshirt",
  price: "29.99",
  sku: "TSHIRT-WHT-M",
  attributes: { color: "White", size: "M" },
});

Inventory Management

Field	Description
trackStock	Enable to validate stock during orders
stock	Current available quantity
allowBackorder	Allow orders even when stock is 0

Stock is automatically decremented when orders are created. See Inventory for more details.

Error Responses

400 Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [{ "field": "price", "message": "Invalid price format" }]
  }
}

409 Conflict (Duplicate)

{
  "error": {
    "code": "CONFLICT",
    "message": "slug already exists"
  }
}

Webhooks

product.created — When a product is created
product.updated — When a product is modified
product.deleted — When a product is deleted

Related Guides

Inventory — Stock tracking and management
Categories — Organize products

Overview Orders