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 { Creem } from "creem";

const creem = new Creem({
  apiKey: process.env.CREEM_API_KEY!,
  server: process.env.NODE_ENV === "production" ? "prod" : "test",
});

// Create customer portal link
const portal = await creem.customers.generateBillingLinks({
  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 { Creem } from "creem";

const creem = new Creem({
  apiKey: process.env.CREEM_API_KEY!,
  server: process.env.NODE_ENV === "production" ? "prod" : "test",
});

// Upgrade subscription to a different product
const upgraded = await creem.subscriptions.upgrade("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 { Creem } from "creem";

const creem = new Creem({
  apiKey: process.env.CREEM_API_KEY!,
  server: process.env.NODE_ENV === "production" ? "prod" : "test",
});

// First, get the subscription to retrieve the item ID
const subscription = await creem.subscriptions.get("sub_YOUR_SUBSCRIPTION_ID");

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

// Update the seat count
const updated = await creem.subscriptions.update("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.

Changing a Product’s Price

When you edit a recurring product’s price, the new price applies to new checkouts only. Existing subscriptions keep billing at the price they signed up with.

Raising Prices for Existing Subscribers

Creem has no built-in flow for moving existing subscribers to a new price. Instead, create a product with the new price, using the same currency and billing interval as the current product. Then move each subscription to the new product with the upgrade subscription endpoint.

Creem doesn’t notify subscribers when you move them to a new price. Let them know before the change takes effect.

With the Creem CLI and jq, list the active subscriptions on the current product, review the list, then move them:

OLD_PRODUCT_ID=prod_OLD_PRICE
NEW_PRODUCT_ID=prod_NEW_PRICE

# 1. Save the IDs of active subscriptions on the current product
creem subscriptions list --status active --json \
  | jq -r --arg product "$OLD_PRODUCT_ID" '.items[] | select(.product.id == $product) | .id' \
  > subscriptions-to-migrate.txt

# 2. Move each subscription to the new product
for SUBSCRIPTION_ID in $(cat subscriptions-to-migrate.txt); do
  creem subscriptions upgrade "$SUBSCRIPTION_ID" \
    --product "$NEW_PRODUCT_ID" \
    --update-behavior proration-none \
    --yes --json
done

The search subscriptions endpoint has no product or status filter, so --status fetches every page and filters on your machine. To do this with the API or SDK instead, page through that endpoint, keep subscriptions whose product.id and status match, and call the upgrade endpoint for each. With proration-none, customers aren’t charged in the middle of their current billing period and pay the new price from their next billing date. See Update Behavior Options for the other values.

The upgrade endpoint only supports subscriptions with a single item, and it can reject subscriptions that have a discount applied. Check the command output for failed upgrades.

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

Get Started

AI

Features

Code

Integrations

Community

Merchant of Record

For Customers

Managing Subscriptions

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

Changing a Product’s Price

Raising Prices for Existing Subscribers

Dashboard Management

Next Steps

Cancellations & Refunds

Webhooks

Customer Portal

API Reference

​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

​Changing a Product’s Price

​Raising Prices for Existing Subscribers

​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

Changing a Product’s Price

Raising Prices for Existing Subscribers

Dashboard Management

Next Steps