english/.opencode/skills/payment-integration/references/creem/subscriptions.md

Creem.io Subscriptions

Subscription Lifecycle

create → active → [pause] → [resume] → [upgrade] → cancel

Create Subscription

Via checkout session with recurring product:

const session = await creem.checkout.sessions.create({
  product_id: 'prod_recurring_xxx',
  success_url: 'https://example.com/success',
  customer_email: 'user@example.com'
});

Retrieve Subscription

// GET /v1/subscriptions/:id
const subscription = await creem.subscriptions.retrieve('sub_xxx');
// Returns: { id, status, product_id, current_period_end, ... }

Modify Subscription

Update Seats/Units

// PATCH /v1/subscriptions/:id
const updated = await creem.subscriptions.update('sub_xxx', {
  quantity: 10,           // Seat count
  prorate: true,          // Prorate charges
  billing_immediately: false
});

Upgrade/Downgrade

const updated = await creem.subscriptions.update('sub_xxx', {
  product_id: 'prod_higher_tier',
  prorate: true
});

Pause Subscription

// POST /v1/subscriptions/:id/pause
const paused = await creem.subscriptions.pause('sub_xxx', {
  resume_at: '2024-02-01T00:00:00Z'  // Optional auto-resume date
});

Resume Subscription

// POST /v1/subscriptions/:id/resume
const resumed = await creem.subscriptions.resume('sub_xxx');

Cancel Subscription

// POST /v1/subscriptions/:id/cancel
const cancelled = await creem.subscriptions.cancel('sub_xxx', {
  at_period_end: true    // false = immediate cancellation
});

Free Trials

Configure on product level:

const product = await creem.products.create({
  name: 'Pro Plan',
  price: 2900,
  currency: 'usd',
  recurring: { interval: 'month' },
  trial_period_days: 14
});

Seat-Based Billing

const product = await creem.products.create({
  name: 'Team Plan',
  price: 1000,           // Per seat price
  currency: 'usd',
  recurring: { interval: 'month' },
  billing_scheme: 'per_unit'
});

// Checkout with quantity
const session = await creem.checkout.sessions.create({
  product_id: 'prod_xxx',
  quantity: 5,           // 5 seats
  success_url: '...'
});

Product Bundles

Group related tiers for upsells:

const bundle = await creem.bundles.create({
  name: 'Growth Plans',
  products: ['prod_starter', 'prod_pro', 'prod_enterprise']
});

Subscription Events (Webhooks)

• subscription.created - New subscription started
• subscription.updated - Quantity, product, or status changed
• subscription.paused - Subscription paused
• subscription.resumed - Subscription resumed
• subscription.cancelled - Cancellation scheduled or completed
• subscription.renewed - Successful renewal charge

See references/creem/webhooks.md for webhook handling.