Product Phases
Product phases allow you to create multi-phase billing for products with different pricing, intervals, and durations. Each phase can have static pricing (fixed amounts) or relative pricing (percentage discounts).
The Product 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 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.
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",
"amount": null,
"currency": "USD",
"discount_percentage": 50.0,
"period_count": 3,
"livemode": false,
"created": 1699564800,
"updated": 1699564800,
"object": "subscription_phase"
}
List all product phases
Returns a list of subscription phases for a given product. 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/products/:product_id/phases \
--header 'Authorization: Bearer API_KEY'
{
"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": {
"product_id": "b74bc1f3-a6a0-4588-a544-ae9d897e00d0"
}
}
Retrieve a product phase
Retrieves the details of an existing product phase.
Returns
Returns a Subscription Phase object if a valid identifier was provided.
curl --request GET \
--url https://api.framepayments.com/v1/products/:product_id/phases/:id \
--header 'Authorization: Bearer API_KEY'
{
"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 product phase
Creates a new product phase. Note that you cannot add phases after an infinite phase has been created.
Parameters
The order position of this phase in the product. Must be unique within the product.
The pricing model for this phase. Can be static for fixed amounts or relative for percentage-based discounts.
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.
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/products/:product_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
}'
{
"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 product phase
Updates the specified product phase by setting the values of the parameters passed.
Parameters
The order position of this phase in the product.
A descriptive name for this phase.
The pricing model for this phase. Can be static or relative.
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.
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/products/:product_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",
"amount": null,
"currency": "USD",
"discount_percentage": 40.0,
"period_count": 3,
"livemode": false,
"created": 1699564800,
"updated": 1699565400,
"object": "subscription_phase"
}
Delete a product phase
Permanently deletes a product 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/products/:product_id/phases/:id \
--header 'Authorization: Bearer API_KEY'
HTTP/1.1 204 No Content
Bulk update product phases
Updates multiple product 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 product after the update, along with metadata about the operation.
curl --request PATCH \
--url https://api.framepayments.com/v1/products/:product_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",
"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": {
"product_id": "b74bc1f3-a6a0-4588-a544-ae9d897e00d0",
"updated_count": 2
}
}