Beginner · 15 min

Merchant Setup

Learn how users and merchants work in Podium, create your first merchant, and manage products, orders, and payouts.

Prerequisites

Podium SDK installed and configured
Basic understanding of REST APIs

In Podium, Users and Merchants are distinct but related concepts. A User represents any authenticated person on your platform—they can browse products, place orders, and manage their profile. A Merchant (also called a Creator) is a seller who can list products, fulfill orders, and receive payouts. Every Merchant must first be a User, but not every User is a Merchant. This guide walks you through creating both and setting up a merchant to start selling.

Create a user

First, create a user account. Users are identified by email and can optionally have a Privy ID for authentication:

merchant.ts

// Create a new user
const user = await client.user.create({
  requestBody: {
    email: 'seller@example.com',
    privyId: 'did:privy:xxx', // Optional: from Privy auth
  },
})

console.log(user)
// {
//   id: 'user_abc123',
//   email: 'seller@example.com',
//   username: null,
//   createdAt: '2025-01-15T...',
// }

Create a merchant from the user

Now create a merchant profile linked to that user. The merchant can then list products and receive orders:

merchant.ts

// Create a merchant profile for the user
const merchant = await client.userMerchant.create({
  id: user.id, // The user ID from step 1
  requestBody: {
    name: 'Awesome Store',
    bio: 'We sell awesome things',
  },
})

console.log(merchant)
// {
//   id: 'creator_xyz',
//   userId: 'user_abc123',
//   name: 'Awesome Store',
//   bio: 'We sell awesome things',
//   verified: false,
//   followerCount: 0,
//   productCount: 0,
// }

Get merchant profile

Retrieve an existing merchant profile by their creator ID:

merchant.ts

// Get merchant profile
const merchant = await client.merchant.get({
  creatorId: 'creator_xyz',
})

console.log(merchant)
// {
//   id: 'creator_xyz',
//   name: 'Awesome Store',
//   bio: 'We sell awesome things',
//   avatar: 'https://...',
//   verified: true,
//   followerCount: 1234,
//   productCount: 45,
// }

List merchant products

Get all products for a merchant:

merchant.ts

// List merchant products
const products = await client.merchantProducts.list({
  creatorId: 'creator_xyz',
})

console.log(products)
// {
//   data: [
//     { id: '...', title: 'Cool T-Shirt', price: 29.99, status: 'active' },
//     ...
//   ],
//   total: 45,
// }

Manage orders

View incoming orders for the merchant:

merchant.ts

// List merchant orders
const orders = await client.merchantOrders.list({
  creatorId: 'creator_xyz',
})

console.log(orders)
// {
//   data: [
//     {
//       id: 'order_...',
//       status: 'pending',
//       customer: { name: '...', email: '...' },
//       items: [...],
//       total: 59.98,
//     },
//     ...
//   ],
// }

View payouts

Check payout status and history:

merchant.ts

// List merchant payouts
const payouts = await client.merchantPayouts.list({
  creatorId: 'creator_xyz',
})

console.log(payouts)
// {
//   data: [
//     { id: 'payout_...', amount: 1250.00, status: 'paid' },
//   ],
//   pendingBalance: 450.00,
// }

Complete Example

Here's a complete working example combining all the steps:

complete-example.ts

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

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

// Complete merchant onboarding
async function onboardMerchant(email: string, storeName: string, bio: string) {
  // Step 1: Create the user account
  const user = await client.user.create({
    requestBody: { email },
  })
  console.log('Created user:', user.id)

  // Step 2: Create the merchant profile
  const merchant = await client.userMerchant.create({
    id: user.id,
    requestBody: { name: storeName, bio },
  })
  console.log('Created merchant:', merchant.id)

  return { user, merchant }
}

// Get merchant dashboard data
async function getMerchantDashboard(creatorId: string) {
  const [products, orders, payouts] = await Promise.all([
    client.merchantProducts.list({ creatorId }),
    client.merchantOrders.list({ creatorId }),
    client.merchantPayouts.list({ creatorId }),
  ])

  return {
    totalProducts: products.total,
    pendingOrders: orders.data.filter(o => o.status === 'pending').length,
    pendingBalance: payouts.pendingBalance,
  }
}

// Usage
const { user, merchant } = await onboardMerchant(
  'seller@example.com',
  'My Awesome Store',
  'Selling quality products since 2025'
)

const dashboard = await getMerchantDashboard(merchant.id)
console.log('Dashboard:', dashboard)

Campaigns

Explore the full API

See all available endpoints and parameters in the API reference.

API Docs