Skip to main content

Documentation Index

Fetch the complete documentation index at: https://podium.build/docs/llms.txt

Use this file to discover all available pages before exploring further.

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