Skip to main content

​
Overview

Creators are merchants or brands within an organization. They manage products, fulfill orders, receive payouts, and run campaigns. Public-facing creator pages are accessed by slug; authenticated operations use creator ID. A user creates a creator profile via POST /user/{id}/creator, and the creator is linked to the user through the CreatorUser join table. One user can own multiple creator profiles.

​
Public Endpoints (by Slug)

Public endpoints don’t require the user to own the creator.

​
Get Creator Profile

curl https://api.podium.build/api/v1/creator/clean-beauty-co \
  -H "Authorization: Bearer $PODIUM_API_KEY"

{
  "id": "clcreator_abc",
  "slug": "clean-beauty-co",
  "displayName": "Clean Beauty Co",
  "description": "Sustainable skincare for mindful beauty",
  "avatarUrl": "https://cdn.example.com/avatar.jpg",
  "heroUrl": "https://cdn.example.com/hero.jpg",
  "flatShippingRate": 500,
  "socialProfiles": [
    { "platform": "INSTAGRAM", "url": "https://instagram.com/cleanbeautyco" }
  ],
  "createdAt": "2026-01-15T10:00:00.000Z"
}

​
Public Stats

curl https://api.podium.build/api/v1/creator/clean-beauty-co/stats \
  -H "Authorization: Bearer $PODIUM_API_KEY"

​
Browse Products

curl https://api.podium.build/api/v1/creator/clean-beauty-co/products \
  -H "Authorization: Bearer $PODIUM_API_KEY"
Returns only published products. For all products including drafts, use the authenticated endpoint.

​
Public Collectibles & Rewards

EndpointReturns
/creator/{slug}/collectiblesOn-chain collectibles
/creator/{slug}/collectibles/metadataCollectible metadata
/creator/{slug}/rewardsAvailable reward programs

​
Update Creator Profile

curl -X PATCH https://api.podium.build/api/v1/creator/id/clcreator_abc \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Clean Beauty Co.",
    "description": "Sustainable skincare for mindful beauty lovers",
    "avatarUrl": "https://cdn.example.com/new-avatar.jpg",
    "heroUrl": "https://cdn.example.com/new-hero.jpg",
    "flatShippingRate": 799,
    "socialProfiles": [
      { "platform": "INSTAGRAM", "url": "https://instagram.com/cleanbeautyco" },
      { "platform": "TIKTOK", "url": "https://tiktok.com/@cleanbeautyco" }
    ]
  }'
FieldTypeDescription
displayNamestringBrand/creator name
descriptionstringBio/description
avatarUrlstringProfile image URL
heroUrlstringStorefront banner image URL
flatShippingRateintegerDefault shipping rate in cents (e.g., 799 = $7.99)
socialProfilesarray{ platform, url } pairs
All fields are optional — include only what you want to change.

​
Product Management

​
Create a Product

curl -X POST https://api.podium.build/api/v1/creator/id/clcreator_abc/product \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hydrating Face Serum",
    "slug": "hydrating-face-serum",
    "description": "Lightweight hyaluronic acid serum for all skin types",
    "price": 2900
  }'
See Products API for the full product create/update schema, variant management, and publish lifecycle.

​
List All Products (Including Drafts)

curl https://api.podium.build/api/v1/creator/id/clcreator_abc/products \
  -H "Authorization: Bearer $PODIUM_API_KEY"

​
Product Sales & Analytics

EndpointReturns
/creator/id/{creatorId}/products/salesSales data per product
/creator/id/{creatorId}/products/analyticsAggregate product analytics
/creator/id/{creatorId}/product/{productId}/analyticsSingle product analytics

​
Product Lifecycle

EndpointAction
POST /creator/id/{creatorId}/product/{productId}/publishPublish a draft product
POST /creator/id/{creatorId}/product/{productId}/restoreRestore an archived product
DELETE /creator/id/{creatorId}/product/{productId}Archive (soft delete)
DELETE /creator/id/{creatorId}/product/{productId}/purgePermanently delete

​
Order Management

​
List Orders

curl https://api.podium.build/api/v1/creator/id/clcreator_abc/orders \
  -H "Authorization: Bearer $PODIUM_API_KEY"

​
Update Order Shipping Status

curl -X PATCH https://api.podium.build/api/v1/creator/id/clcreator_abc/order/clord_xyz \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "shippingStatus": "SHIPPED" }'
Shipping StatusDescription
PENDINGOrder placed, not yet shipped
PROCESSINGBeing prepared for shipment
SHIPPEDIn transit
DELIVEREDDelivered to recipient
RETURNEDReturned by customer

​
Generate Shipping Label

curl https://api.podium.build/api/v1/creator/id/clcreator_abc/order/clord_xyz/shipping/label \
  -H "Authorization: Bearer $PODIUM_API_KEY"
Generates a Shippo shipping label for the order. Requires the creator to have a connected Shippo account.

​
Stripe Connect Onboarding

Creators receive payouts through Stripe Connect. The onboarding flow creates a Stripe Express account linked to the creator.

​
Initiate Stripe Connect

curl -X POST https://api.podium.build/api/v1/creator/id/clcreator_abc/stripe/account \
  -H "Authorization: Bearer $PODIUM_API_KEY"
Returns a Stripe Connect onboarding URL. Redirect the creator to this URL to complete identity verification and bank account setup. 
{
  "url": "https://connect.stripe.com/setup/s/...",
  "accountId": "acct_1234567890"
}

​
Onboarding Flow

​
Onboarding Reminders

If a creator hasn’t completed Stripe onboarding within 48 hours, the stripe-onboarding-reminder cron job sends an email reminder. The stripeOnboardingReminderSentAt and stripeOnboardingReminderClaimedUntil fields on the Creator model track this flow.

​
Payout Lifecycle

When an order is paid, a CreatorPayout record is created to track the creator’s share:
StatusDescription
PENDINGOrder paid, payout created. Funds held during review period
ELIGIBLEHold period complete, payout ready for transfer
TRANSFERREDFunds sent to creator’s Stripe Connect account

​
View Payouts

curl https://api.podium.build/api/v1/creator/id/clcreator_abc/payouts \
  -H "Authorization: Bearer $PODIUM_API_KEY"

[
  {
    "id": "clpayout_abc",
    "orderId": "clord_xyz",
    "amount": 2320,
    "currency": "usd",
    "status": "TRANSFERRED",
    "stripeTransferId": "tr_1234567890",
    "createdAt": "2026-03-01T10:00:00.000Z",
    "transferredAt": "2026-03-03T14:30:00.000Z"
  }
]
The amount is in cents and represents the creator’s share after the platform application fee (STRIPE_PLATFORM_APPLICATION_FEE_BPS).

​
Payout Sweep Cron

The payouts-sweep cron job runs periodically to:
  1. Query all ELIGIBLE payouts
  2. Execute Stripe Connect transfers to each creator’s account
  3. Update status to TRANSFERRED with the stripeTransferId

​
Dashboard Analytics

EndpointReturns
/creator/id/{creatorId}/dashboardOverview dashboard
/creator/id/{creatorId}/dashboard/rewardsReward program performance
/creator/id/{creatorId}/dashboard/fansFan/follower analytics
/creator/id/{creatorId}/dashboard/campaignsCampaign performance

​
Campaigns

EndpointReturns
/creator/id/{creatorId}/campaignsAll campaigns
/creator/id/{creatorId}/campaigns/titlesCampaign title list
/creator/id/{creatorId}/campaigns/latestMost recent campaign
/creator/id/{creatorId}/campaigns/analytics/participants/countTotal participants

​
Archive / Restore / Purge Campaigns

EndpointAction
DELETE /creator/id/{creatorId}/campaign/{id}Archive
POST /creator/id/{creatorId}/campaign/{id}/restoreRestore
DELETE /creator/id/{creatorId}/campaign/{id}/purgePermanent delete

​
Followers

EndpointReturns
/creator/id/{creatorId}/followersFollower list
/creator/id/{creatorId}/followers/countFollower count
/creator/followers/{id}Followers by creator (public)
/creator/followers/{id}/topTop followers
/creator/followers/{id}/growthFollower growth over time

​
Rewards & Airdrops

EndpointReturns
/creator/id/{creatorId}/nft-rewardsReward programs
/creator/id/{creatorId}/nft-rewards/redeemedRedeemed rewards
/creator/id/{creatorId}/latest-earned-rewardLatest earned reward
/creator/id/{creatorId}/latest-airdropLatest airdrop
/creator/id/{creatorId}/earned-rewardsAll earned rewards
/creator/id/{creatorId}/airdropsAirdrop history

​
Groups

Creators can organize followers into groups for targeted campaigns and communications: 
curl -X POST https://api.podium.build/api/v1/creator/id/clcreator_abc/group \
  -H "Authorization: Bearer $PODIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "groupName": "VIP Customers",
    "groupType": "MANUAL",
    "memberIds": ["cluser_1", "cluser_2", "cluser_3"]
  }'
EndpointAction
GET /creator/id/{creatorId}/groupsList groups
POST /creator/id/{creatorId}/groupCreate group

​
Token Presales

Creators can run token presale campaigns:
EndpointAction
GET /creator/id/{creatorId}/token-presalesList presales
POST /creator/id/{creatorId}/token-presalesCreate presale
GET /creator/id/{creatorId}/token-presales/{id}Get presale
PATCH /creator/id/{creatorId}/token-presales/{id}Update presale
DELETE /creator/id/{creatorId}/token-presales/{id}Delete presale

​
Creator Model

FieldTypeDescription
idstringCUID2 identifier
slugstringURL-friendly unique handle
displayNamestringBrand/creator name (unique)
descriptionstringCreator bio
avatarUrlstringProfile image URL
heroUrlstringStorefront banner image
flatShippingRateintegerDefault shipping rate in cents
pointsAcceptedenumSELF (own points only) or ALL
createdAtdatetimeCreation timestamp
organizationIdstringParent organization

​
CreatorPayout Model

FieldTypeDescription
idstringCUID2 identifier
creatorIdstringOwning creator
orderIdstringSource order (unique)
amountintegerPayout amount in cents
currencystringCurrency code (default: usd)
statusenumPENDING, ELIGIBLE, TRANSFERRED
stripeTransferIdstringStripe transfer ID (when transferred)
createdAtdatetimeCreation timestamp
transferredAtdatetimeTransfer timestamp

​
Endpoint Summary

MethodPathDescription
GET/creator/{slug}Public profile
GET/creator/{slug}/productsPublished products
GET/creator/{slug}/product/{productSlug}Product by slug
GET/creator/{slug}/collectiblesCollectibles
GET/creator/{slug}/collectibles/metadataCollectible metadata
GET/creator/{slug}/rewardsRewards
GET/creator/{slug}/statsPublic stats
GET/creator/id/{creatorId}Get by ID
PATCH/creator/id/{creatorId}Update profile
GET/creator/id/{creatorId}/productsAll products
GET/creator/id/{creatorId}/products/salesSales data
GET/creator/id/{creatorId}/products/analyticsProduct analytics
POST/creator/id/{creatorId}/productCreate product
GET/creator/id/{creatorId}/product/{productId}Get product
PATCH/creator/id/{creatorId}/product/{productId}Update product
DELETE/creator/id/{creatorId}/product/{productId}Archive product
POST/creator/id/{creatorId}/product/{productId}/publishPublish
POST/creator/id/{creatorId}/product/{productId}/restoreRestore
DELETE/creator/id/{creatorId}/product/{productId}/purgePurge
GET/creator/id/{creatorId}/ordersOrders
PATCH/creator/id/{creatorId}/order/{id}Update order
GET/creator/id/{creatorId}/order/{id}/shipping/labelShipping label
GET/creator/id/{creatorId}/payoutsPayouts
POST/creator/id/{creatorId}/stripe/accountStripe Connect
GET/creator/id/{creatorId}/dashboardDashboard
GET/creator/id/{creatorId}/dashboard/rewardsRewards dash
GET/creator/id/{creatorId}/dashboard/fansFan analytics
GET/creator/id/{creatorId}/dashboard/campaignsCampaign dash
GET/creator/id/{creatorId}/campaignsCampaigns
GET/creator/id/{creatorId}/campaigns/titlesCampaign titles
GET/creator/id/{creatorId}/campaigns/latestLatest campaign
GET/creator/id/{creatorId}/followersFollowers
GET/creator/id/{creatorId}/followers/countFollower count
GET/creator/id/{creatorId}/nft-rewardsRewards
GET/creator/id/{creatorId}/nft-rewards/redeemedRedeemed
GET/creator/id/{creatorId}/airdropsAirdrops
GET/creator/id/{creatorId}/groupsGroups
POST/creator/id/{creatorId}/groupCreate group
GET/creator/id/{creatorId}/notificationsNotifications
POST/creator/id/{creatorId}/chatInitialize chat