Skip to main content
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
      }
    ]
  }'
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

FieldTypeRequiredDescription
namestringYesProduct name
slugstringYesURL-friendly identifier (unique per creator)
descriptionstringYesProduct description
priceintegerYesPrice in cents (e.g., 2500 = $25.00)
maxDiscountintegerYesMaximum discount in cents (0–10000)
allowedPointSourcesstring[]?NoPoint source types allowed for discounts
mediaarrayYes1–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)

FieldTypeDescription
namestringProduct name
descriptionstringProduct description
priceintegerBase price in cents
supplyintegerTotal inventory (null for unlimited)
logostringProduct logo/thumbnail URL
pointEligibilityenumELIGIBLE or INELIGIBLE
shippingTypeenumShipping method
subcategoryIdintegerCategory assignment
attributesarrayAttribute variants (replaces existing)
mediaarrayMedia items (replaces existing)

​
Media

Each product requires 1–5 media items. The first item (order 0) is the hero image.
FieldTypeRequiredDescription
urlstringYesMedia URL
typeenumYesIMAGE or VIDEO
orderintegerYesDisplay 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

FieldTypeRequiredDescription
valuestringYesDisplay value (e.g., “30ml”, “Red”)
priceintegerYesPrice in cents when this variant is selected
supplyintegerNoInventory for this variant
orderintegerYesDisplay 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
  }'
FieldTypeDefaultDescription
quantityinteger—Number of items (min 1)
variantIdsstring[][]Selected variant IDs
shouldUseStripebooleantrueIf 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"

​
Categories

curl https://api.podium.build/api/v1/categories
Returns all product categories. No authentication required.

​
Product Model

FieldTypeDescription
idstringCUID2 identifier
namestringProduct name
descriptionstringProduct description
priceintegerBase price in cents
supplyinteger?Inventory count (null for unlimited)
maxDiscountintegerMaximum applicable discount in cents
statusenumDRAFT, PUBLISHED, ARCHIVED
slugstringURL-friendly identifier
pointEligibilityenumELIGIBLE or INELIGIBLE
shippingTypeenum?Shipping method
logostring?Product thumbnail URL
subcategoryIdinteger?Category reference
shopifyProductIdstring?Linked Shopify product (if synced)
mediaarrayAttached media items
attributesarrayConfigurable attribute variants
createdAtdatetimeCreation timestamp
updatedAtdatetimeLast update timestamp

​
Endpoint Summary

MethodPathDescription
POST/creator/id/{creatorId}/productCreate 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}/publishPublish product
POST/creator/id/{creatorId}/product/{productId}/restoreRestore archived
POST/creator/id/{creatorId}/product/{productId}/purgePermanently delete
GET/creator/id/{creatorId}/product/slug/{slug}Get by slug
GET/creator/id/{creatorId}/productsList creator products
GET/creator/id/{creatorId}/product/{productId}/analyticsProduct analytics
GET/creator/id/{creatorId}/products/analyticsAggregate analytics
GET/creator/id/{creatorId}/products/salesSales data
GET/productsList published products (public)
POST/product/{productId}/buy-nowBuy now shortcut
GET/categoriesList all categories