Subscription
Subscriptions allow you to charge a customer on a recurring basis.
The Subscription object
Attributes
Unique identifier for the object.
The subscription's description, meant to be displayable to the customer.
Start of the current period that the subscription has been invoiced for.
End of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
Three-letter ISO currency code, in lowercase. Must be a supported currency.
Status of this Subscription, one of pending, active, terminated, or canceled.
ID of the customer who owns the subscription.
ID of the default payment method for the subscription. It must belong to the customer associated with the subscription.
String representing the object's type. Objects of the same type share the same value.
A metadata object consists of key-value pairs that can be attached to Frame object. Use metadata to store structured, additional information about the object for your reference. Learn more about storing information in metadata.
Time at which the object was created. Measured in seconds since the Unix epoch.
Date when the subscription was first created. The date might differ from the created date due to backdating.
The calculated effective price in cents after applying subscription phases and discounts.
The effective billing interval from the subscription plan (e.g., "monthly", "every_6_months").
The effective interval count from the subscription plan.
ID of the most recent charge intent for this subscription.
The most recent charge object for this subscription, containing payment details such as status, amount, and payment method information.
The following phase-related attributes are currently in beta and only available when subscription phases are enabled for your account.
Array of subscription phase objects defining pricing changes over time. Each phase can have different pricing and duration.
Indicates whether this subscription uses phases for pricing changes.
The currently active subscription phase object, if phases are configured for this subscription.
The method by which to charge prorations when a subscription is updated. Possible values are always_invoice (default), create_prorations, or none.
{
"id": "398f4d2f-0679-4820-8b15-c7947c9b365f",
"description": "My subscription",
"current_period_start": 1720695392,
"current_period_end": 1736592992,
"livemode": false,
"plan": {
"id": "0914f5b2-d3d2-424a-a32c-a97db5144e9f",
"interval": "every_6_months",
"interval_count": 1,
"product": "b74bc1f3-a6a0-4588-a544-ae9d897e00d0",
"amount": 600,
"currency": "USD",
"object": "plan",
"active": true,
"created": 1720695392,
"livemode": false
},
"effective_amount": 600,
"effective_interval": "every_6_months",
"effective_interval_count": 1,
"latest_charge_intent": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"latest_charge": {...},
"phases": [{...}],
"has_phases": true,
"current_phase": {...},
"currency": "USD",
"status": "pending",
"quantity": 1,
"customer": "ca98780e-2d73-46ae-89cb-8aefe72d7a23",
"default_payment_method": "f4f05ac4-5b33-4281-a305-bf7106a6a664",
"metadata": {},
"object": "subscription",
"created": 1720695392,
"start_date": 1720695392
}
Create a subscription
Creates a new subscription on an existing customer.
Parameters
The identifier of the customer to subscribe.
The ID of the product. The purchase type must be recurring.
Three-letter ISO currency code, in lowercase. Must be a supported currency.
ID of the default payment method for the subscription.
The subscription's description, meant to be displayable to the customer.
An array of subscription phase objects to create with the subscription. Each phase can have different pricing, intervals, and durations.
A metadata object consists of key-value pairs that can be attached to Frame object. Use metadata to store structured, additional information about the object for your reference. Learn more about storing information in metadata.
When creating a subscription with phases, each phase object in the subscription_phases array should contain the following parameters. Note: If the product has predefined phases, providing subscription_phases will override the product's phases with your custom phases.
Phase 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.
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. If not specified, the phase continues indefinitely.
Returns
The newly created Subscription object, if the call succeeded. If the attempted charge fails, the subscription is created in an incomplete status.
curl --request POST \
--url https://api.framepayments.com/v1/subscriptions \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"customer": "ca98780e-2d73-46ae-89cb-8aefe72d7a23",
"product": "b74bc1f3-a6a0-4588-a544-ae9d897e00d0",
"currency": "USD",
"default_payment_method": "f4f05ac4-5b33-4281-a305-bf7106a6a664",
"description": "My subscription",
"subscription_phases": [
{
"ordinal": 1,
"name": "Custom Trial",
"pricing_type": "relative",
"discount_percentage": 100.0,
"period_count": 1
},
{
"ordinal": 2,
"name": "Custom Discount",
"pricing_type": "static",
"amount_cents": 5000,
"period_count": 3
}
]
}'
{
"id": "398f4d2f-0679-4820-8b15-c7947c9b365f",
"description": "My subscription",
"current_period_start": 1720695392,
"current_period_end": 1736592992,
"livemode": false,
"plan": {
"id": "0914f5b2-d3d2-424a-a32c-a97db5144e9f",
"interval": "every_6_months",
"interval_count": 1,
"product": "b74bc1f3-a6a0-4588-a544-ae9d897e00d0",
"amount": 600,
"currency": "USD",
"object": "plan",
"active": true,
"created": 1720695392,
"livemode": false
},
"effective_amount": 600,
"effective_interval": "every_6_months",
"effective_interval_count": 1,
"latest_charge_intent": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"latest_charge": {...},
"phases": [{...}],
"has_phases": true,
"current_phase": {...},
"currency": "USD",
"status": "pending",
"quantity": 1,
"customer": "ca98780e-2d73-46ae-89cb-8aefe72d7a23",
"default_payment_method": "f4f05ac4-5b33-4281-a305-bf7106a6a664",
"metadata": {},
"object": "subscription",
"created": 1720695392,
"start_date": 1720695392
}
Update a subscription
Updates an existing subscription to match the specified parameters.
Parameters
The ID of a new subscription product. The purchase type must be recurring.
ID of the default payment method for the subscription. It must belong to the customer associated with the subscription.
The subscription's description, meant to be displayable to the customer.
A metadata object consists of key-value pairs that can be attached to Frame object. Use metadata to store structured, additional information about the object for your reference. Learn more about storing information in metadata.
Returns
The newly updated Subscription object.
If set to true, the subscription's billing interval will be updated to match the new product's interval.
curl --request PATCH \
--url https://api.framepayments.com/v1/subscriptions/:id \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"description": "Smart"
}'
{
"id": "6f34a36b-052e-4846-8d6f-2c555e5bdd8b",
"description": "Smart",
"current_period_start": 1722226719,
"current_period_end": 1738124319,
"livemode": false,
"plan": {...},
"latest_charge": {...},
"currency": "USD",
"status": "active",
"quantity": 1,
"customer": "098ac82e-eccf-49de-94f2-6718caec1316",
"default_payment_method": "281f3243-7e59-4cc2-a528-102df5872674",
"metadata": {},
"object": "subscription",
"created": 1722226719,
"start_date": 1722226719
}
Retrieve a subscription
Retrieves the subscription with the given ID.
Parameters
No parameters.
Returns
Returns the subscription object.
curl --request GET \
--url https://api.framepayments.com/v1/subscriptions/:id \
--header 'Authorization: Bearer API_KEY'
{
"id": "398f4d2f-0679-4820-8b15-c7947c9b365f",
"description": "My subscription",
"current_period_start": 1720695392,
"current_period_end": 1736592992,
"livemode": false,
"plan": {
"id": "0914f5b2-d3d2-424a-a32c-a97db5144e9f",
"interval": "every_6_months",
"interval_count": 1,
"product": "b74bc1f3-a6a0-4588-a544-ae9d897e00d0",
"amount": 600,
"currency": "USD",
"object": "plan",
"active": true,
"created": 1720695392,
"livemode": false
},
"effective_amount": 600,
"effective_interval": "every_6_months",
"effective_interval_count": 1,
"latest_charge_intent": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"latest_charge": {...},
"phases": [{...}],
"has_phases": true,
"current_phase": {...},
"currency": "USD",
"status": "pending",
"quantity": 1,
"customer": "ca98780e-2d73-46ae-89cb-8aefe72d7a23",
"default_payment_method": "f4f05ac4-5b33-4281-a305-bf7106a6a664",
"metadata": {},
"object": "subscription",
"created": 1720695392,
"start_date": 1720695392
}
List subscriptions
Returns a list of Subscriptions.
Parameters
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
The page offset at which you'd like to resume fetching data.
Returns
A dictionary with a data property that contains an array of up to limit Subscriptions. Each entry in the array is a separate Subscription object. If no more Subscriptions are available, the resulting array will be empty.
curl --request GET \
--url https://api.framepayments.com/v1/subscriptions \
--header 'Authorization: Bearer API_KEY'
{
"meta": {
"page": 1,
"url": "/v1/subscriptions",
"has_more": false,
"prev": null,
"next": null
},
"subscriptions": [
{
"id": "398f4d2f-0679-4820-8b15-c7947c9b365f",
"description": "My subscription",
"current_period_start": 1720695392,
"current_period_end": 1736592992,
"livemode": false,
"plan": {
"id": "0914f5b2-d3d2-424a-a32c-a97db5144e9f",
"interval": "every_6_months",
"interval_count": 1,
"product": "b74bc1f3-a6a0-4588-a544-ae9d897e00d0",
"amount": 600,
"currency": "USD",
"object": "plan",
"active": true,
"created": 1720695392,
"livemode": false
},
"effective_amount": 600,
"effective_interval": "every_6_months",
"effective_interval_count": 1,
"latest_charge_intent": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"latest_charge": {...},
"phases": [{...}],
"has_phases": true,
"current_phase": {...},
"currency": "USD",
"status": "pending",
"quantity": 1,
"customer": "ca98780e-2d73-46ae-89cb-8aefe72d7a23",
"default_payment_method": "f4f05ac4-5b33-4281-a305-bf7106a6a664",
"metadata": {},
"object": "subscription",
"created": 1720695392,
"start_date": 1720695392
},
{...},
{...}
]
}
Search subscriptions
Search for customers you've previously created using Frame's Search Query Language. Don't use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages.
Parameters
The status of the subscription
Time at which the object was created. Measured in seconds since the Unix epoch.
Time at which the object was created. Measured in seconds since the Unix epoch.
Returns
A dictionary with a data property that contains an array of up to limit subscriptions. If no objects match the query, the resulting array will be empty.
curl --request GET \
--url 'https://api.framepayments.com/v1/subscriptions/search?status=pending' \
--header 'Authorization: Bearer API_KEY'
{
"meta": {
"page": 1,
"url": "/v1/subscriptions/search?status=pending",
"has_more": false,
"prev": null,
"next": null
},
"subscriptions": [
{
"id": "398f4d2f-0679-4820-8b15-c7947c9b365f",
"description": "My subscription",
"current_period_start": 1720695392,
"current_period_end": 1736592992,
"livemode": false,
"plan": {
"id": "0914f5b2-d3d2-424a-a32c-a97db5144e9f",
"interval": "every_6_months",
"interval_count": 1,
"product": "b74bc1f3-a6a0-4588-a544-ae9d897e00d0",
"amount": 600,
"currency": "USD",
"object": "plan",
"active": true,
"created": 1720695392,
"livemode": false
},
"effective_amount": 600,
"effective_interval": "every_6_months",
"effective_interval_count": 1,
"latest_charge_intent": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"latest_charge": {...},
"phases": [{...}],
"has_phases": true,
"current_phase": {...},
"currency": "USD",
"status": "pending",
"quantity": 1,
"customer": "ca98780e-2d73-46ae-89cb-8aefe72d7a23",
"default_payment_method": "f4f05ac4-5b33-4281-a305-bf7106a6a664",
"metadata": {},
"object": "subscription",
"created": 1720695392,
"start_date": 1720695392
}
]
}
Cancel a subscription
Cancels a customer's subscription immediately. The customer will not be charged again for the subscription.
Parameters
No parameters.
Returns
The canceled Subscription object. Its subscription status will be set to canceled.
curl --request POST \
--url https://api.framepayments.com/v1/subscriptions/:id/cancel \
--header 'Authorization: Bearer API_KEY'
{
"id": "398f4d2f-0679-4820-8b15-c7947c9b365f",
"description": "My subscription",
"current_period_start": 1720695392,
"current_period_end": 1736592992,
"livemode": false,
"plan": {
"id": "0914f5b2-d3d2-424a-a32c-a97db5144e9f",
"interval": "every_6_months",
"interval_count": 1,
"product": "b74bc1f3-a6a0-4588-a544-ae9d897e00d0",
"amount": 600,
"currency": "USD",
"object": "plan",
"active": true,
"created": 1720695392,
"livemode": false
},
"effective_amount": 600,
"effective_interval": "every_6_months",
"effective_interval_count": 1,
"latest_charge_intent": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"latest_charge": {...},
"phases": [{...}],
"has_phases": true,
"current_phase": {...},
"currency": "USD",
"status": "canceled",
"quantity": 1,
"customer": "ca98780e-2d73-46ae-89cb-8aefe72d7a23",
"default_payment_method": "f4f05ac4-5b33-4281-a305-bf7106a6a664",
"metadata": {},
"object": "subscription",
"created": 1720695392,
"start_date": 1720695392
}