Managing Subscriptions

Creem provides comprehensive tools for managing active subscriptions, including updating seat counts, changing billing information, upgrading/downgrading plans, and enabling self-service management for your customers.

Managing Subscription Changes

Update Billing Information

Customers can update their payment method through the Customer Portal:

Next.js
TypeScript SDK
Better Auth
REST API

import { CreemPortal } from '@creem_io/nextjs';

export function ManageBillingButton({ customerId }: { customerId: string }) {
  return (
    <CreemPortal customerId={customerId}>
      <button>Manage Billing</button>
    </CreemPortal>
  );
}

import { createCreem } from 'creem_io';

const creem = createCreem({
  apiKey: process.env.CREEM_API_KEY!,
  testMode: process.env.NODE_ENV !== 'production',
});

// Create customer portal link
const portal = await creem.customers.createPortal({
  customerId: 'cust_YOUR_CUSTOMER_ID',
});

// Redirect to portal
console.log(portal.customerPortalLink);

"use client";

import { authClient } from "@/lib/auth-client";

export function ManageBillingButton() {
  const handlePortal = async () => {
    const { data } = await authClient.creem.createPortal();

    if (data?.url) {
      window.location.href = data.url;
    }
  };

  return (
    <button onClick={handlePortal}>
      Manage Billing
    </button>
  );
}

curl -X POST https://api.creem.io/v1/customer-portal \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_YOUR_CUSTOMER_ID"
  }'

Customer Portal

Learn more about the Customer Portal and its features.

Subscription Upgrades & Downgrades

Programmatic Upgrades

Upgrade or downgrade a subscription to a different product using the subscription upgrade endpoint:

TypeScript SDK
REST API

import { createCreem } from 'creem_io';

const creem = createCreem({
  apiKey: process.env.CREEM_API_KEY!,
  testMode: process.env.NODE_ENV !== 'production',
});

// Upgrade subscription to a different product
const upgraded = await creem.subscriptions.upgrade({
  subscriptionId: 'sub_YOUR_SUBSCRIPTION_ID',
  productId: 'prod_PREMIUM_PLAN', // New product ID
  updateBehavior: 'proration-charge-immediately',
});

console.log('Subscription upgraded:', upgraded);

curl -X POST https://api.creem.io/v1/subscriptions/sub_YOUR_SUBSCRIPTION_ID/upgrade \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_PREMIUM_PLAN",
    "update_behavior": "proration-charge-immediately"
  }'

Update Behavior Options

When upgrading or downgrading subscriptions, the plan change takes effect immediately. update_behavior controls how the unused or additional time in the current billing period is handled:

Behavior	Upgrade	Downgrade
`proration-charge-immediately`	Access changes now; prorated difference is charged immediately.	Plan changes now; unused time and tax are refunded to the original payment method.
~~`proration-charge`~~ (deprecated)	Behaves identically to `proration-charge-immediately`.	Behaves identically to `proration-charge-immediately`.
`proration-none`	Access changes now; no prorated difference is charged this period.	Plan changes now; unused time creates no credit or refund.

Deprecation Notice: proration-charge is deprecated and now behaves identically to proration-charge-immediately (charges are applied immediately rather than deferred to the next invoice). Existing integrations passing proration-charge will continue to work but should migrate to proration-charge-immediately for clarity.

Proration Example:If a customer upgrades from a $10/month plan to a $30/month plan halfway through their billing cycle:

proration-charge-immediately: Customer is charged ~$10 now (the difference for the remaining half of the month) and $30 on the next billing date.
proration-none: Customer gets the upgrade for the rest of the current period without paying the prorated difference.

Fees apply only to the amount actually charged to the payment method after credits. For example, if a $100 invoice uses $50 in subscription credits, fees apply to the remaining $50 charge.

API Reference - Upgrade Subscription

View the complete upgrade subscription endpoint documentation.

Updating Seat Count

For seat-based subscriptions, you can update the number of seats:

TypeScript SDK
REST API

import { createCreem } from 'creem_io';

const creem = createCreem({
  apiKey: process.env.CREEM_API_KEY!,
  testMode: process.env.NODE_ENV !== 'production',
});

// First, get the subscription to retrieve the item ID
const subscription = await creem.subscriptions.get({
  subscriptionId: 'sub_YOUR_SUBSCRIPTION_ID',
});

const itemId = subscription.items[0].id;

// Update the seat count
const updated = await creem.subscriptions.update({
  subscriptionId: 'sub_YOUR_SUBSCRIPTION_ID',
  items: [
    {
      id: itemId,
      units: 10, // New seat count
    },
  ],
  updateBehavior: 'proration-charge-immediately',
});

# First, get the subscription
curl -X GET https://api.creem.io/v1/subscriptions/sub_YOUR_SUBSCRIPTION_ID \
  -H "x-api-key: YOUR_API_KEY"

# Then update with the item ID
curl -X POST https://api.creem.io/v1/subscriptions/sub_YOUR_SUBSCRIPTION_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "sitem_ITEM_ID",
        "units": 10
      }
    ]
  }'

Seat-Based Billing

Learn more about implementing seat-based pricing models.

Dashboard Management

You can also manage subscriptions directly through the Creem Dashboard:

View subscription details - See customer info, billing history, and status
Modify subscriptions - Change seat counts, update pricing
Pause subscriptions - Temporarily pause without canceling
Cancel subscriptions - End recurring billing

Simply navigate to a subscription and click “Modify Subscription” to make changes.

Next Steps

Cancellations & Refunds

Handle subscription cancellations and process refunds

Webhooks

Handle subscription events like renewals and cancellations

Customer Portal

Enable self-service subscription management

API Reference

View the complete API documentation

Documentation Index

​Managing Subscription Changes

​Update Billing Information

Customer Portal

​Subscription Upgrades & Downgrades

​Programmatic Upgrades

​Update Behavior Options

API Reference - Upgrade Subscription

​Updating Seat Count

Seat-Based Billing

​Dashboard Management

​Next Steps

Cancellations & Refunds

Webhooks

Customer Portal

API Reference

Managing Subscription Changes

Update Billing Information

Subscription Upgrades & Downgrades

Programmatic Upgrades

Update Behavior Options

Updating Seat Count

Dashboard Management

Next Steps