Subscription Phases

Subscription phases allow you to create multi-phase billing for subscriptions with different pricing, intervals, and durations. Each phase can have static pricing (fixed amounts) or relative pricing (percentage discounts).

Subscription phases can be managed for both products and subscriptions:

  • Product phases: Define default phases that will be applied to all subscriptions created from that product
  • Subscription phases: Override product phases with custom phases for specific subscriptions

The Subscription Phase object

Attributes
idstringoptional

Unique identifier for the object.

ordinalintegeroptional

The order position of this phase in the subscription. Must be unique within the subscription.

namenullable stringoptional

A descriptive name for this phase.

pricing_typeenumoptional

The pricing model for this phase. Can be static for fixed amounts or relative for percentage-based discounts.

amountnullable integeroptional

The amount for this phase in cents. Required when pricing_type is static.

currencystringoptional

Three-letter ISO currency code for the phase amount.

discount_percentagenullable decimaloptional

The discount percentage (0-100) to apply to the base subscription amount. Required when pricing_type is relative.

period_countnullable integeroptional

The number of billing periods this phase lasts.

livemodebooleanoptional

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

createdtimestampoptional

Time at which the object was created. Measured in seconds since the Unix epoch.

updatedtimestampoptional

Time at which the object was last updated. Measured in seconds since the Unix epoch.

objectstringoptional

String representing the object's type. Objects of the same type share the same value.

THE SUBSCRIPTION PHASE OBJECT
{
  "id": "ph_1234567890abcdef",
  "ordinal": 1,
  "name": "Introductory Phase",
  "pricing_type": "relative",
  "amount": null,
  "currency": "USD",
  "discount_percentage": 50.0,
  "period_count": 3,
  "livemode": false,
  "created": 1699564800,
  "updated": 1699564800,
  "object": "subscription_phase"
}

List all subscription phases

Returns a list of subscription phases for a given subscription. The phases are returned in order by their ordinal value.

Returns

A dictionary with a phases property that contains an array of Subscription Phase objects. If no phases exist, the resulting array will be empty.

GET/v1/subscriptions/:subscription_id/phases
curl --request GET \
  --url https://api.framepayments.com/v1/subscriptions/:subscription_id/phases \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "phases": [
    {
      "id": "ph_1234567890abcdef",
      "ordinal": 1,
      "name": "Introductory Phase",
      "pricing_type": "relative",
      "amount": null,
      "currency": "USD",
      "discount_percentage": 50.0,
      "period_count": 3,
      "livemode": false,
      "created": 1699564800,
      "updated": 1699564800,
      "object": "subscription_phase"
    }
  ],
  "meta": {
    "subscription_id": "398f4d2f-0679-4820-8b15-c7947c9b365f"
  }
}

Retrieve a subscription phase

Retrieves the details of an existing subscription phase.

Returns

Returns a Subscription Phase object if a valid identifier was provided.

GET/v1/subscriptions/:subscription_id/phases/:id
curl --request GET \
  --url https://api.framepayments.com/v1/subscriptions/:subscription_id/phases/:id \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "ph_1234567890abcdef",
  "ordinal": 1,
  "name": "Introductory Phase",
  "pricing_type": "relative",
  "amount": null,
  "currency": "USD",
  "discount_percentage": 50.0,
  "period_count": 3,
  "livemode": false,
  "created": 1699564800,
  "updated": 1699564800,
  "object": "subscription_phase"
}

Create a subscription phase

Creates a new subscription phase. Note that you cannot add phases after an infinite phase has been created.

Parameters
ordinalintegerrequired

The order position of this phase in the subscription. Must be unique within the subscription.

pricing_typeenumrequired

The pricing model for this phase. Can be static for fixed amounts or relative for percentage-based discounts.

namestringoptional

A descriptive name for this phase.

amount_centsintegeroptional

The amount for this phase in cents. Required when pricing_type is static.

discount_percentagedecimaloptional

The discount percentage (0-100) to apply to the base subscription amount. Required when pricing_type is relative.

period_countintegeroptional

The number of billing periods this phase lasts.

Returns

Returns the Subscription Phase object after successful creation. Returns an error if create parameters are invalid.

POST/v1/subscriptions/:subscription_id/phases
curl --request POST \
  --url https://api.framepayments.com/v1/subscriptions/:subscription_id/phases \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "ordinal": 1,
  "name": "Introductory Phase",
  "pricing_type": "relative",
  "discount_percentage": 50.0,
  "period_count": 3
}'
RESPONSE
{
  "id": "ph_1234567890abcdef",
  "ordinal": 1,
  "name": "Introductory Phase",
  "pricing_type": "relative",
  "amount": null,
  "currency": "USD",
  "discount_percentage": 50.0,
  "period_count": 3,
  "livemode": false,
  "created": 1699564800,
  "updated": 1699564800,
  "object": "subscription_phase"
}

Update a subscription phase

Updates the specified subscription phase by setting the values of the parameters passed.

Parameters
ordinalintegeroptional

The order position of this phase in the subscription.

namestringoptional

A descriptive name for this phase.

pricing_typeenumoptional

The pricing model for this phase. Can be static or relative.

amount_centsintegeroptional

The amount for this phase in cents.

discount_percentagedecimaloptional

The discount percentage (0-100) to apply to the base subscription amount.

period_countintegeroptional

The number of billing periods this phase lasts.

Returns

Returns the updated Subscription Phase object if the update succeeded. Returns an error if update parameters are invalid.

PATCH/v1/subscriptions/:subscription_id/phases/:id
curl --request PATCH \
  --url https://api.framepayments.com/v1/subscriptions/:subscription_id/phases/:id \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Updated Introductory Phase",
  "discount_percentage": 40.0
}'
RESPONSE
{
  "id": "ph_1234567890abcdef",
  "ordinal": 1,
  "name": "Updated Introductory Phase",
  "pricing_type": "relative",
  "amount": null,
  "currency": "USD",
  "discount_percentage": 40.0,
  "period_count": 3,
  "livemode": false,
  "created": 1699564800,
  "updated": 1699565400,
  "object": "subscription_phase"
}

Delete a subscription phase

Permanently deletes a subscription phase. This action cannot be undone.

Returns

Returns an empty response with HTTP status 204 (No Content) on successful deletion.

DELETE/v1/subscriptions/:subscription_id/phases/:id
curl --request DELETE \
  --url https://api.framepayments.com/v1/subscriptions/:subscription_id/phases/:id \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
HTTP/1.1 204 No Content

Bulk update subscription phases

Updates multiple subscription phases in a single request. This is useful for reordering phases or making coordinated changes to multiple phases.

Parameters
phasesarrayrequired

An array of phase objects to update. Each object should include the phase ID and the fields to update.

Returns

Returns a dictionary with a phases property containing all phases for the subscription after the update, along with metadata about the operation.

PATCH/v1/subscriptions/:subscription_id/phases/bulk_update
curl --request PATCH \
  --url https://api.framepayments.com/v1/subscriptions/:subscription_id/phases/bulk_update \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "phases": [
    {
      "id": "ph_1234567890abcdef",
      "ordinal": 2,
      "name": "Updated Phase 1"
    },
    {
      "id": "ph_0987654321fedcba",
      "ordinal": 1,
      "name": "Updated Phase 2"
    }
  ]
}'
RESPONSE
{
  "phases": [
    {
      "id": "ph_0987654321fedcba",
      "ordinal": 1,
      "name": "Updated Phase 2",
      "pricing_type": "static",
      "amount": 500,
      "currency": "USD",
      "discount_percentage": null,
      "period_count": 2,
      "livemode": false,
      "created": 1699564800,
      "updated": 1699566000,
      "object": "subscription_phase"
    },
    {
      "id": "ph_1234567890abcdef",
      "ordinal": 2,
      "name": "Updated Phase 1",
      "pricing_type": "relative",
      "amount": null,
      "currency": "USD",
      "discount_percentage": 40.0,
      "period_count": 3,
      "livemode": false,
      "created": 1699564800,
      "updated": 1699566000,
      "object": "subscription_phase"
    }
  ],
  "meta": {
    "subscription_id": "398f4d2f-0679-4820-8b15-c7947c9b365f",
    "updated_count": 2
  }
}