Admin Products API — Create and Manage Products

The Admin Products API gives you full control over the product catalog. Use it to create new products, update existing ones, search and filter across all catalog entries — including soft-deleted items — and perform soft-deletes that preserve order history without exposing discontinued items to customers. All write operations require an active admin session and a CSRF token.

All endpoints under /admin/products require an authenticated session with the ADMIN or SUPER_ADMIN role. Always call GET /auth/csrf-token first and pass the returned token in the x-csrf-token header for every POST, PATCH, and DELETE request.

List Products

Retrieve a paginated list of products from the admin catalog view. Unlike the public catalog endpoint, this view lets you filter by deleted status, search across all products regardless of active variant availability, and sort by any supported field.

GET /admin/products

Query Parameters

integer

default:"1"

Page number (1-based).

integer

default:"20"

Number of results per page. Accepted range: 1–100.

string

Free-text search across product name, brand, and description.

string

Filter by exact brand name (trimmed). Maximum 255 characters.

string

default:"-created_at"

Sort field. Prefix with - for descending order. Accepted values: name, -name, created_at, -created_at, updated_at, -updated_at.

string

default:"false"

Pass "true" to include soft-deleted products in the response. Must be the string "true" or "false".

Pass include_deleted=true when auditing removed catalog items — for example, when reconciling order history against products that are no longer actively sold.

Response

Returns a paginated envelope with a data array of product summaries and a meta pagination object.

boolean

Always true on a 200 response.

array

Array of product summary objects.

Show Product summary fields

string

Unique product identifier, prefixed prd_.

string

Product display name.

string

URL-safe slug. Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$.

string | null

Brand name, or null if not set.

string | null

Product description, or null if not set.

string | null

ISO 8601 UTC timestamp of soft-deletion, or null if the product is active.

string

ISO 8601 UTC creation timestamp.

string

ISO 8601 UTC last-updated timestamp.

object

Pagination metadata.

Show Pagination fields

integer

Total matching records.

integer

Total number of pages.

boolean

Whether a next page exists.

boolean

Whether a previous page exists.

Create Product

Create a new product in the catalog. Only name is required; provide a slug to control the URL path or let the API auto-generate one from the name. A 409 is returned if the slug already exists.

POST /admin/products

Request Body

string

required

Product display name. Between 1 and 255 characters.

string

URL slug for the product. Must match ^[a-z0-9]+(?:-[a-z0-9]+)*$ and be unique. Auto-generated from name if omitted. Maximum 255 characters.

string

Long-form product description. Maximum 10,000 characters. Optional.

string

Brand name. Maximum 255 characters. Optional.

Example

# Step 1: obtain a CSRF token
TOKEN=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<your-session-cookie>" \
  | jq -r '.data.csrf_token')

# Step 2: create the product
curl -X POST https://api.example.com/api/v1/admin/products \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $TOKEN" \
  -d '{
    "name": "Runner Sneaker",
    "slug": "runner-sneaker",
    "description": "Lightweight daily trainer built for speed and comfort.",
    "brand": "Nike"
  }'

const response = await fetch('https://api.example.com/api/v1/admin/products', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'x-csrf-token': csrfToken,
  },
  body: JSON.stringify({
    name: 'Runner Sneaker',
    slug: 'runner-sneaker',
    description: 'Lightweight daily trainer built for speed and comfort.',
    brand: 'Nike',
  }),
});
const data = await response.json();

201 Response

{
  "success": true,
  "data": {
    "public_id": "prd_01H",
    "name": "Runner Sneaker",
    "slug": "runner-sneaker",
    "description": "Lightweight daily trainer built for speed and comfort.",
    "brand": "Nike",
    "images": [],
    "variants": [],
    "deleted_at": null,
    "created_at": "2024-06-01T09:00:00.000Z",
    "updated_at": "2024-06-01T09:00:00.000Z"
  }
}

Error Responses

Status	Meaning
`400`	Validation error — invalid slug format or missing required field.
`401`	No active session.
`403`	Session does not have ADMIN or SUPER_ADMIN role.
`409`	A product with the given slug already exists.

Get Product

Fetch the full admin projection of a product by its public ID. Pass include_deleted_variants=true to include any soft-deleted variants in the response.

GET /admin/products/{product_public_id}

Path Parameters

string

required

The product’s public ID, prefixed prd_.

Query Parameters

string

default:"false"

Pass "true" to include soft-deleted variants in the variants array. Must be the string "true" or "false".

Response

Returns the full ProductDetail object including images (ordered by display_order) and variants (all statuses when include_deleted_variants=true).

Update Product

Partially update a product’s fields. Only the fields you supply are modified. Pass null for description or brand to explicitly clear those values.

PATCH /admin/products/{product_public_id}

Path Parameters

string

required

The product’s public ID, prefixed prd_.

Request Body

At least one field is required.

string

Updated display name. Between 1 and 255 characters.

string

Updated URL slug. Must match ^[a-z0-9]+(?:-[a-z0-9]+)*$. Returns 409 on conflict.

string | null

Updated description. Pass null to clear the existing value.

string | null

Updated brand. Pass null to clear the existing value.

Example

curl -X PATCH https://api.example.com/api/v1/admin/products/prd_01H \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $TOKEN" \
  -d '{
    "name": "Runner Sneaker Pro",
    "brand": null
  }'

await fetch('https://api.example.com/api/v1/admin/products/prd_01H', {
  method: 'PATCH',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'x-csrf-token': csrfToken,
  },
  body: JSON.stringify({ name: 'Runner Sneaker Pro', brand: null }),
});

Delete Product

Soft-delete a product and all of its variants. The product is immediately hidden from all customer-facing endpoints but remains in the database with deleted_at set. Returns 204 No Content on success.

DELETE /admin/products/{product_public_id}

Path Parameters

string

required

The product’s public ID, prefixed prd_.

Example

curl -X DELETE https://api.example.com/api/v1/admin/products/prd_01H \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $TOKEN"

await fetch('https://api.example.com/api/v1/admin/products/prd_01H', {
  method: 'DELETE',
  credentials: 'include',
  headers: { 'x-csrf-token': csrfToken },
});

Soft-deleted products — and all their variants — are hidden from customers but are permanently retained in the database. This ensures that historical order line items continue to reference the correct product name, slug, and brand without data loss.

Error Responses

Status	Meaning
`401`	No active session.
`403`	Insufficient role.
`404`	Product not found.

Catalog Management

Operations

Users & Moderation

Analytics & Audit

Admin Products API — Create and Manage Products

List Products

Query Parameters

Response

Create Product

Request Body

Example

201 Response

Error Responses

Get Product

Path Parameters

Query Parameters

Response

Update Product

Path Parameters

Request Body

Example

Delete Product

Path Parameters

Example

Error Responses

​List Products

​Query Parameters

​Response

​Create Product

​Request Body

​Example

​201 Response

​Error Responses

​Get Product

​Path Parameters

​Query Parameters

​Response

​Update Product

​Path Parameters

​Request Body

​Example

​Delete Product

​Path Parameters

​Example

​Error Responses

List Products

Query Parameters

Response

Create Product

Request Body

Example

201 Response

Error Responses

Get Product

Path Parameters

Query Parameters

Response

Update Product

Path Parameters

Request Body

Example

Delete Product

Path Parameters

Example

Error Responses