Products

Products are the core commerce entity. They support configurable attribute variants (size, color, etc.), media attachments, category organization, and per-creator assignment. All products belong to a creator’s storefront and go through a DRAFT → PUBLISHED → ARCHIVED lifecycle.

Base Path

Creator product endpoints use /api/v1/creator/id/{creatorId}/product. Public listing uses /api/v1/products.

Create a Product

curl -X POST https://api.podium.build/api/v1/creator/id/{creatorId}/product \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Organic Face Serum",
    "slug": "organic-face-serum",
    "description": "Lightweight hydrating serum with hyaluronic acid and vitamin C",
    "price": 2500,
    "maxDiscount": 500,
    "media": [
      {
        "url": "https://cdn.example.com/serum-front.jpg",
        "type": "IMAGE",
        "order": 0
      },
      {
        "url": "https://cdn.example.com/serum-texture.jpg",
        "type": "IMAGE",
        "order": 1
      }
    ]
  }'

import { createPodiumClient } from '@podium-sdk/node-sdk'

const client = createPodiumClient({ apiKey: process.env.PODIUM_API_KEY })

const product = await client.merchantProducts.create({
  creatorId,
  requestBody: {
    name: "Organic Face Serum",
    slug: "organic-face-serum",
    description: "Lightweight hydrating serum with hyaluronic acid and vitamin C",
    price: 2500,
    maxDiscount: 500,
    media: [
      { url: "https://cdn.example.com/serum-front.jpg", type: "IMAGE", order: 0 },
      { url: "https://cdn.example.com/serum-texture.jpg", type: "IMAGE", order: 1 },
    ],
  },
})

Response:

{
  "id": "clx9prod001",
  "name": "Organic Face Serum",
  "slug": "organic-face-serum",
  "description": "Lightweight hydrating serum with hyaluronic acid and vitamin C",
  "price": 2500,
  "currency": "USD",
  "supply": null,
  "maxDiscount": 500,
  "status": "DRAFT",
  "pointEligibility": "ELIGIBLE",
  "media": [
    { "id": 1, "url": "https://cdn.example.com/serum-front.jpg", "type": "IMAGE", "order": 0 },
    { "id": 2, "url": "https://cdn.example.com/serum-texture.jpg", "type": "IMAGE", "order": 1 }
  ],
  "attributes": [],
  "createdAt": "2026-03-07T10:00:00Z"
}

Create Product Schema

Field	Type	Required	Description
`name`	string	Yes	Product name
`slug`	string	Yes	URL-friendly identifier (unique per creator)
`description`	string	Yes	Product description
`price`	integer	Yes	Price in cents (e.g., `2500` = $25.00)
`maxDiscount`	integer	Yes	Maximum discount in cents (0–10000)
`allowedPointSources`	string[]?	No	Point source types allowed for discounts
`media`	array	Yes	1–5 media items (see Media below)

Update a Product

PATCH merges the provided fields into the existing product. This endpoint also handles attributes, media, supply, shipping config, and point eligibility.

curl -X PATCH https://api.podium.build/api/v1/creator/id/{creatorId}/product/{productId} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description with new ingredients list",
    "supply": 200,
    "pointEligibility": "ELIGIBLE",
    "shippingType": "STANDARD",
    "attributes": [
      {
        "name": "Size",
        "type": "VARIANT",
        "variants": [
          { "value": "30ml", "price": 2500, "supply": 100, "order": 0 },
          { "value": "50ml", "price": 3500, "supply": 50, "order": 1 },
          { "value": "100ml", "price": 5000, "supply": 50, "order": 2 }
        ]
      }
    ]
  }'

Update Schema (all fields optional)

Field	Type	Description
`name`	string	Product name
`description`	string	Product description
`price`	integer	Base price in cents
`supply`	integer	Total inventory (`null` for unlimited)
`logo`	string	Product logo/thumbnail URL
`pointEligibility`	enum	`ELIGIBLE` or `INELIGIBLE`
`shippingType`	enum	Shipping method
`subcategoryId`	integer	Category assignment
`attributes`	array	Attribute variants (replaces existing)
`media`	array	Media items (replaces existing)

Media

Each product requires 1–5 media items. The first item (order 0) is the hero image.

Field	Type	Required	Description
`url`	string	Yes	Media URL
`type`	enum	Yes	`IMAGE` or `VIDEO`
`order`	integer	Yes	Display order (0-indexed, must be unique)

Attribute Variants

Products support configurable attributes for variant selection. Each attribute has a name, type, and array of variants with independent pricing and inventory.

{
  "attributes": [
    {
      "name": "Size",
      "type": "VARIANT",
      "variants": [
        { "value": "30ml", "price": 2500, "supply": 100, "order": 0 },
        { "value": "50ml", "price": 3500, "supply": 50, "order": 1 },
        { "value": "100ml", "price": 5000, "supply": 50, "order": 2 }
      ]
    },
    {
      "name": "Color",
      "type": "VARIANT",
      "variants": [
        { "value": "Natural", "price": 2500, "supply": 50, "order": 0 },
        { "value": "Fair", "price": 2500, "supply": 30, "order": 1 }
      ]
    }
  ]
}

Each variant has its own price (in cents, replaces the base price when selected) and independent supply tracking. When a user selects variants at checkout, the selectedAttributes are stored on the order item.

Variant Schema

Field	Type	Required	Description
`value`	string	Yes	Display value (e.g., “30ml”, “Red”)
`price`	integer	Yes	Price in cents when this variant is selected
`supply`	integer	No	Inventory for this variant
`order`	integer	Yes	Display order

Product Lifecycle

Products move through three statuses:

Publish a Product

Transitions a DRAFT product to PUBLISHED, making it visible in public listings.

curl -X POST https://api.podium.build/api/v1/creator/id/{creatorId}/product/{productId}/publish \
  -H "Authorization: Bearer YOUR_API_KEY"

Restore an Archived Product

Returns an ARCHIVED product to DRAFT status.

curl -X POST https://api.podium.build/api/v1/creator/id/{creatorId}/product/{productId}/restore \
  -H "Authorization: Bearer YOUR_API_KEY"

Purge a Product

Permanently deletes an ARCHIVED product. This is irreversible.

curl -X POST https://api.podium.build/api/v1/creator/id/{creatorId}/product/{productId}/purge \
  -H "Authorization: Bearer YOUR_API_KEY"

Get and List Products

Get a Single Product

curl https://api.podium.build/api/v1/creator/id/{creatorId}/product/{productId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns the product with all attributes, media, and variant details. Works for products in any status (DRAFT, PUBLISHED, ARCHIVED).

Get Product by Slug

curl https://api.podium.build/api/v1/creator/id/{creatorId}/product/slug/{slug} \
  -H "Authorization: Bearer YOUR_API_KEY"

List Creator Products

curl https://api.podium.build/api/v1/creator/id/{creatorId}/products \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns all products for a creator with aggregated sales counts.

List Published Products (Public)

curl "https://api.podium.build/api/v1/products?categories=serum,moisturizer&limit=20&cursor=clx9prod050"

Public endpoint — no authentication required. Returns only PUBLISHED products. Supports cursor-based pagination and category filtering.

Delete (Archive) a Product

curl -X DELETE https://api.podium.build/api/v1/creator/id/{creatorId}/product/{productId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Moves the product to ARCHIVED status. Use /restore to bring it back, or /purge to permanently delete.

Buy Now

A shortcut endpoint that creates an order and optionally initiates Stripe checkout in a single request:

curl -X POST https://api.podium.build/api/v1/product/{productId}/buy-now \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 1,
    "variantIds": ["clx9var001"],
    "shouldUseStripe": true
  }'

Field	Type	Default	Description
`quantity`	integer	—	Number of items (min 1)
`variantIds`	string[]	`[]`	Selected variant IDs
`shouldUseStripe`	boolean	`true`	If true, creates Stripe PaymentIntent

Analytics

Product Analytics

curl https://api.podium.build/api/v1/creator/id/{creatorId}/product/{productId}/analytics \
  -H "Authorization: Bearer YOUR_API_KEY"

Aggregate Product Analytics

curl https://api.podium.build/api/v1/creator/id/{creatorId}/products/analytics \
  -H "Authorization: Bearer YOUR_API_KEY"

Sales Data

curl https://api.podium.build/api/v1/creator/id/{creatorId}/products/sales \
  -H "Authorization: Bearer YOUR_API_KEY"

Product Model

Field	Type	Description
`id`	string	CUID2 identifier
`name`	string	Product name
`description`	string	Product description
`price`	integer	Base price in cents
`supply`	integer?	Inventory count (`null` for unlimited)
`maxDiscount`	integer	Maximum applicable discount in cents
`status`	enum	`DRAFT`, `PUBLISHED`, `ARCHIVED`
`slug`	string	URL-friendly identifier
`pointEligibility`	enum	`ELIGIBLE` or `INELIGIBLE`
`shippingType`	enum?	Shipping method
`logo`	string?	Product thumbnail URL
`subcategoryId`	integer?	Category reference
`shopifyProductId`	string?	Linked Shopify product (if synced)
`media`	array	Attached media items
`attributes`	array	Configurable attribute variants
`createdAt`	datetime	Creation timestamp
`updatedAt`	datetime	Last update timestamp

Endpoint Summary

Method	Path	Description
`POST`	`/creator/id/{creatorId}/product`	Create a product
`GET`	`/creator/id/{creatorId}/product/{productId}`	Get product by ID
`PATCH`	`/creator/id/{creatorId}/product/{productId}`	Update product
`DELETE`	`/creator/id/{creatorId}/product/{productId}`	Archive product
`POST`	`/creator/id/{creatorId}/product/{productId}/publish`	Publish product
`POST`	`/creator/id/{creatorId}/product/{productId}/restore`	Restore archived
`POST`	`/creator/id/{creatorId}/product/{productId}/purge`	Permanently delete
`GET`	`/creator/id/{creatorId}/product/slug/{slug}`	Get by slug
`GET`	`/creator/id/{creatorId}/products`	List creator products
`GET`	`/creator/id/{creatorId}/product/{productId}/analytics`	Product analytics
`GET`	`/creator/id/{creatorId}/products/analytics`	Aggregate analytics
`GET`	`/creator/id/{creatorId}/products/sales`	Sales data
`GET`	`/products`	List published products (public)
`POST`	`/product/{productId}/buy-now`	Buy now shortcut
`GET`	`/categories`	List all categories

Overview

Intelligence & Agents

Commerce

Users & Engagement

Platform

Base Path

Create a Product

Create Product Schema

Update a Product

Update Schema (all fields optional)

Media

Attribute Variants

Variant Schema

Product Lifecycle

Publish a Product

Restore an Archived Product

Purge a Product

Get and List Products

Get a Single Product

Get Product by Slug

List Creator Products

List Published Products (Public)

Delete (Archive) a Product

Buy Now

Analytics

Product Analytics

Aggregate Product Analytics

Sales Data

Categories

Product Model

Endpoint Summary

​Base Path

​Create a Product

​Create Product Schema

​Update a Product

​Update Schema (all fields optional)

​Media

​Attribute Variants

​Variant Schema

​Product Lifecycle

​Publish a Product

​Restore an Archived Product

​Purge a Product

​Get and List Products

​Get a Single Product

​Get Product by Slug

​List Creator Products

​List Published Products (Public)

​Delete (Archive) a Product

​Buy Now

​Analytics

​Product Analytics

​Aggregate Product Analytics

​Sales Data

​Categories

​Product Model

​Endpoint Summary

Base Path

Create a Product

Create Product Schema

Update a Product

Update Schema (all fields optional)

Media

Attribute Variants

Variant Schema

Product Lifecycle

Publish a Product

Restore an Archived Product

Purge a Product

Get and List Products

Get a Single Product

Get Product by Slug

List Creator Products

List Published Products (Public)

Delete (Archive) a Product

Buy Now

Analytics

Product Analytics

Aggregate Product Analytics

Sales Data

Categories

Product Model

Endpoint Summary