Payment configuration

Payments are a core part of TinyShip. For a global product, start with Stripe, PayPal, Creem, or Dodo Payments. WeChat Pay and Alipay are optional and only for buyers in mainland China. Three billing modes are supported: one-time payment, subscription, and credit packs. WeChat Pay and Alipay support one-time payments and credit packs only.

Pricing mode: static vs dynamic

Choose a pricing mode before you add plans:

• Static pricing (default): Plans live in config/payment.ts and ship with the code. Use this when plans rarely change. The "Configure plans" section below is the static path.
• Dynamic pricing: Plans live in the database. Create and edit them at /admin/pricing without a redeploy. This also adds strikethrough prices, locale filtering, and custom ordering. See Dynamic pricing.

Switch modes with the PRICING_MODE environment variable. The two modes do not overwrite each other.

Related pages

Supported providers

Configuration overview

Set providers in config/payment.ts. Enable the ones you will use.

Global

• Stripe — cards, one-time payments, and subscriptions
• PayPal — one-time payments and subscriptions
• Creem — indie-friendly checkout, with a simpler review than Stripe
• Dodo Payments — Merchant of Record that handles tax and compliance

China (optional)

• WeChat Pay and Alipay — for customers in China. Both require a Chinese business entity and a merchant account.

Provider guides

China (optional)

Configure plans

Plans live on plans in config/payment.ts. They show up on /pricing.

Plan types

Plan shape

Each plan is a typed object. Provider-specific IDs sit on that object (stripePriceId, paypalPlanId, creemProductId, dodoProductId).

plans: {
  lifetime: {
    provider: 'stripe',           // 'stripe' | 'dodo' | 'creem' | 'paypal' | 'wechat' | 'alipay'
    id: 'lifetime',               // Unique plan id
    amount: 999,                  // Price. WeChat Pay and Alipay amounts are yuan.
    currency: 'USD',              // 'USD' | 'EUR' | 'CNY' | …
    recommended: true,            // Highlight on the pricing page
    duration: {
      months: 999999,             // 999999 means lifetime (months >= 9999)
      type: 'one_time'            // 'one_time' | 'recurring' | 'credits'
    },
    stripePriceId: 'price_xxx',   // Stripe Price ID
    paypalPlanId: 'P-xxx',        // PayPal Plan ID (subscriptions)
    creemProductId: 'prod_xxx',   // Creem product ID
    dodoProductId: 'pdt_xxx',     // Dodo product ID
    i18n: { /* locale copy */ }
  }
}

Set only the provider ID that matches provider. A Stripe plan needs stripePriceId. A PayPal subscription needs paypalPlanId. A Creem plan needs creemProductId. A Dodo plan needs dodoProductId. WeChat Pay and Alipay do not use a product ID on the plan.

Fields

Locale copy

i18n: {
  'en': {
    name: 'Monthly Plan',
    description: 'Perfect for short-term projects',
    duration: 'month',
    features: ['All premium features', 'Priority support']
  }
}

Full example (USD, Stripe)

lifetime: {
  provider: 'stripe',
  id: 'lifetime',
  amount: 999,
  currency: 'USD',
  recommended: true,
  duration: {
    months: 999999,
    type: 'one_time'
  },
  stripePriceId: 'price_1RL2IcDjHLfDWeHDMCmobkzb',
  i18n: {
    'en': {
      name: 'TinyShip Complete',
      description: 'Lifetime access to the complete SaaS starter kit',
      duration: 'lifetime',
      features: [
        'Complete SaaS template source code',
        'Free lifetime updates',
        'Priority customer support',
        'Access to a private GitHub repository'
      ]
    }
  }
}

Strikethrough prices use originalPrice on dynamic plans (pricing_plan), not a field in config/payment.ts.

Payment flow

1. Buyer selects a plan → 2. Order is created → 3. Redirect to the provider → 4. Webhook is handled → 5. Order status is updated

The factory in libs/payment/index.ts is createPaymentProvider('stripe' | 'wechat' | 'creem' | 'dodo').

API routes

// Start checkout
POST /api/payment/initiate
{
  "planId": "monthly",
  "provider": "stripe"
}

// Order status (query string, not a path segment)
GET /api/payment/query?orderId=<orderId>&provider=<provider>

// Webhooks
POST /api/payment/webhook/stripe
POST /api/payment/webhook/paypal
POST /api/payment/webhook/creem
POST /api/payment/webhook/dodo
POST /api/payment/webhook/wechat
POST /api/payment/webhook/alipay

// Cancel (query string). Implemented for WeChat Pay.
POST /api/payment/cancel?orderId=<orderId>&provider=<provider>

References

• Payment testing — local development and webhooks
• Credits — credit packs and consumption

Provider docs

• Stripe docs
• PayPal developer docs
• Creem API docs
• Dodo Payments docs
• WeChat Pay docs
• Alipay Open Platform