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), and can be finite (specific duration) or infinite (continues until subscription ends).
The Subscription Phase object
Attributes
Unique identifier for the object.
The order position of this phase in the subscription. Must be unique within the subscription.
A descriptive name for this phase.
The pricing model for this phase. Can be static for fixed amounts or relative for percentage-based discounts.
The duration model for this phase. Can be finite for a specific duration or infinite for phases that continue until subscription ends.
The amount for this phase in cents. Required when pricing_type is static.
Three-letter ISO currency code for the phase amount.
The discount percentage (0-100) to apply to the base subscription amount. Required when pricing_type is relative.
The number of billing periods this phase lasts. Required when duration_type is finite.
Custom billing interval for this phase. If not provided, uses the subscription's default interval.
Number of intervals between billings. If not provided, uses the subscription's default interval count.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
Time at which the object was created. Measured in seconds since the Unix epoch.
Time at which the object was last updated. Measured in seconds since the Unix epoch.
String representing the object's type. Objects of the same type share the same value.
{
"id": "ph_1234567890abcdef",
"ordinal": 1,
"name": "Introductory Phase",
"pricing_type": "relative",
"duration_type": "finite",
"amount": null,
"currency": "USD",
"discount_percentage": 50.0,
"period_count": 3,
"interval": null,
"interval_count": null,
"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.
curl --request GET \
--url https://api.framepayments.com/v1/subscriptions/:subscription_id/phases \
--header 'Authorization: Bearer API_KEY'
{
"phases": [
{
"id": "ph_1234567890abcdef",
"ordinal": 1,
"name": "Introductory Phase",
"pricing_type": "relative",
"duration_type": "finite",
"amount": null,
"currency": "USD",
"discount_percentage": 50.0,
"period_count": 3,
"interval": null,
"interval_count": null,
"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.
curl --request GET \
--url https://api.framepayments.com/v1/subscriptions/:subscription_id/phases/:id \
--header 'Authorization: Bearer API_KEY'
{
"id": "ph_1234567890abcdef",
"ordinal": 1,
"name": "Introductory Phase",
"pricing_type": "relative",
"duration_type": "finite",
"amount": null,
"currency": "USD",
"discount_percentage": 50.0,
"period_count": 3,
"interval": null,
"interval_count": null,
"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
The order position of this phase in the subscription. Must be unique within the subscription.
The pricing model for this phase. Can be static for fixed amounts or relative for percentage-based discounts.
The duration model for this phase. Can be finite for a specific duration or infinite for phases that continue until subscription ends.
A descriptive name for this phase.
The amount for this phase in cents. Required when pricing_type is static.
The discount percentage (0-100) to apply to the base subscription amount. Required when pricing_type is relative.
The number of billing periods this phase lasts. Required when duration_type is finite.
Custom billing interval for this phase (e.g., "month", "year"). If not provided, uses the subscription's default interval.
Number of intervals between billings. If not provided, uses the subscription's default interval count.
Returns
Returns the Subscription Phase object after successful creation. Returns an error if create parameters are invalid.
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",
"duration_type": "finite",
"discount_percentage": 50.0,
"period_count": 3
}'
{
"id": "ph_1234567890abcdef",
"ordinal": 1,
"name": "Introductory Phase",
"pricing_type": "relative",
"duration_type": "finite",
"amount": null,
"currency": "USD",
"discount_percentage": 50.0,
"period_count": 3,
"interval": null,
"interval_count": null,
"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
The order position of this phase in the subscription.
A descriptive name for this phase.
The pricing model for this phase. Can be static or relative.
The duration model for this phase. Can be finite or infinite.
The amount for this phase in cents.
The discount percentage (0-100) to apply to the base subscription amount.
The number of billing periods this phase lasts.
Custom billing interval for this phase.
Number of intervals between billings.
Returns
Returns the updated Subscription Phase object if the update succeeded. Returns an error if update parameters are invalid.
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
}'
{
"id": "ph_1234567890abcdef",
"ordinal": 1,
"name": "Updated Introductory Phase",
"pricing_type": "relative",
"duration_type": "finite",
"amount": null,
"currency": "USD",
"discount_percentage": 40.0,
"period_count": 3,
"interval": null,
"interval_count": null,
"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.
curl --request DELETE \
--url https://api.framepayments.com/v1/subscriptions/:subscription_id/phases/:id \
--header 'Authorization: Bearer API_KEY'
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
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.
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"
}
]
}'
{
"phases": [
{
"id": "ph_0987654321fedcba",
"ordinal": 1,
"name": "Updated Phase 2",
"pricing_type": "static",
"duration_type": "finite",
"amount": 500,
"currency": "USD",
"discount_percentage": null,
"period_count": 2,
"interval": null,
"interval_count": null,
"livemode": false,
"created": 1699564800,
"updated": 1699566000,
"object": "subscription_phase"
},
{
"id": "ph_1234567890abcdef",
"ordinal": 2,
"name": "Updated Phase 1",
"pricing_type": "relative",
"duration_type": "finite",
"amount": null,
"currency": "USD",
"discount_percentage": 40.0,
"period_count": 3,
"interval": null,
"interval_count": null,
"livemode": false,
"created": 1699564800,
"updated": 1699566000,
"object": "subscription_phase"
}
],
"meta": {
"subscription_id": "398f4d2f-0679-4820-8b15-c7947c9b365f",
"updated_count": 2
}
}