SubscriptionPlans

SubscriptionPlans define the recurring pricing you offer to your customers. Each plan specifies an amount, a currency, and a billing frequency. A plan is then attached to one or more Subscriptions to trigger automatic charges.

Typical use cases: monthly SaaS subscription, annual plan with a discount, quarterly offer with a free trial period.

Amount immutable after creation

A plan’s amount (amount) cannot be modified after creation. To change the price, create a new plan and migrate your subscribers via PATCH /subscriptions/{id}/. Only name and description can be modified via PATCH.

Endpoints

Méthode	Endpoint	Description
POST	`/subscription-plans/`	Create a plan
GET	`/subscription-plans/`	List plans
GET	`/subscription-plans/{id}/`	Retrieve a plan
PATCH	`/subscription-plans/{id}/`	Update (name and description only)
DELETE	`/subscription-plans/{id}/`	Deactivate (not possible with active subscribers)

Is this introduction clear?

Object schema

ResponseSubscriptionPlan object

Full structure returned by all endpoints of this resource.

json

{
  "id": "plan_xxxxxxxxxxxx",
  "object": "subscription_plan",
  "name": "Monthly Growth Plan",
  "description": "Full access to all Growth features",
  "amount": 15000,
  "currency": "XAF",
  "interval": "month",
  "interval_count": 1,
  "trial_period_days": 14,
  "active": true,
  "metadata": {
    "tier": "growth"
  },
  "livemode": true,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Create a SubscriptionPlan

Creates a new pricing plan. The plan is immediately available to be attached to a Subscription.

POSTRequest body

nameRequis

stringex :Monthly Growth Plan

Name of the plan. Visible to the customer on payment pages, invoices, and renewal emails.

Choose a clear name that reflects the value offered — it appears directly in communications sent to your subscribers.

amountRequis

integercentsex :15000

Amount charged at each billing period, in cents. This field is immutable after creation.

Always express in cents. 15,000 XAF = 15000. For decimal currencies (EUR, USD), 15 EUR = 1500. To change a price, create a new plan and migrate your subscribers.

currencyRequis

stringISO 4217ex :XAF

ISO 4217 currency code for the plan. Must match a currency enabled on your App. Immutable after creation.

intervalRequis

string

Unit of the billing period. Values: day, week, month, year.

Combined with interval_count, this field defines the exact billing frequency. Examples: interval: “month” + interval_count: 3 = quarterly billing; interval: “year” + interval_count: 1 = annual billing.

interval_countOptionnel

integerdéfaut :1

Multiplier for the interval. Determines the actual billing frequency in combination with interval.

Examples: interval: “month”, interval_count: 1 → monthly; interval: “month”, interval_count: 3 → quarterly; interval: “month”, interval_count: 6 → semi-annual.

trial_period_daysOptionnel

integerex :14

Length of the free trial period, in days. During this period, no charge is made. The Subscription moves to trialing status until the trial ends.

This field sets the plan’s default trial period. It can be overridden per subscriber by passing trial_period_days directly when creating the Subscription.

descriptionOptionnel

string

Description of the plan. Displayed on the plan selection page and in welcome emails.

metadataOptionnel

object

Free-form data — internal identifier, pricing tier, CRM reference, etc.

The plan’s metadata is included in the subscription.created and subscription.canceled webhooks. Useful for identifying the tier during automatic access provisioning.

Are the plan parameters clear?

Create a monthly plan with a trial

bash

curl -X POST https://api.sangho.ga/v1/subscription-plans/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Growth Plan",
    "amount": 15000,
    "currency": "XAF",
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": 14,
    "description": "Full access to all Growth features",
    "metadata": { "tier": "growth" }
  }'

Response201 Created

The plan is active immediately and can be attached to new Subscriptions.

json

{
  "id": "plan_xxxxxxxxxxxx",
  "object": "subscription_plan",
  "name": "Monthly Growth Plan",
  "description": "Full access to all Growth features",
  "amount": 15000,
  "currency": "XAF",
  "interval": "month",
  "interval_count": 1,
  "trial_period_days": 14,
  "active": true,
  "metadata": { "tier": "growth" },
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

List SubscriptionPlans

Returns all of your App’s plans, sorted by descending creation date.

GETQuery parameters

activeOptionnel

boolean

Filter by status. true returns only active plans, false returns deactivated plans.

currencyOptionnel

stringISO 4217

Filter by currency. Useful if you offer plans in multiple currencies.

intervalOptionnel

string

Filter by billing interval: day, week, month, or year.

pageOptionnel

integerdéfaut :1

Page number.

page_sizeOptionnel

integerdéfaut :20

Results per page. Maximum: 100.

Update a SubscriptionPlan

Only name and description can be modified after creation. amount, currency, interval and interval_count are immutable.

PATCHUpdate body (PATCH)

nameOptionnel

string

New name for the plan. Reflected in future renewal emails.

descriptionOptionnel

string

New description. Pass null to remove it.

metadataOptionnel

object

Merged with existing metadata.

Deactivate a SubscriptionPlan

Deactivates the plan by setting active to false. A deactivated plan can no longer be attached to new Subscriptions, but existing subscriptions continue to work normally.

Not possible with active subscribers

Deactivation fails with a 409 Conflict error if the plan still has Subscriptions in active or trialing status. Migrate your subscribers to a new plan first before deactivating the old one.

Are the operations on SubscriptionPlans well documented?

List active plans

bash

curl "https://api.sangho.ga/v1/subscription-plans/?active=true&interval=month" \
  -H "Authorization: Bearer sk_prod_xxxx"

Update a plan

bash

curl -X PATCH https://api.sangho.ga/v1/subscription-plans/plan_xxx/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Growth Plan — New",
    "metadata": { "tier": "growth", "legacy": null }
  }'

Response200 OK — Plan updated

json

{
  "id": "plan_xxxxxxxxxxxx",
  "object": "subscription_plan",
  "name": "Monthly Growth Plan — New",
  "amount": 15000,
  "currency": "XAF",
  "interval": "month",
  "interval_count": 1,
  "active": true,
  "metadata": { "tier": "growth" },
  "updated_at": "2026-04-01T09:00:00Z"
}

Deactivate a plan

bash

curl -X DELETE https://api.sangho.ga/v1/subscription-plans/plan_xxx/ \
  -H "Authorization: Bearer sk_prod_xxxx"

Response200 OK — Deactivated

The plan is deactivated. Existing Subscriptions continue to work until they are canceled.

Fails with 409 if active or trialing Subscriptions are still associated with this plan.

json

{
  "id": "plan_xxxxxxxxxxxx",
  "active": false,
  "updated_at": "2026-04-10T12:00:00Z"
}