Subscriptions
Create and manage subscriptions. Subscriptions represent recurring billing relationships between your platform and a customer, tied to a product and billing interval.
The Subscription object
Attributes
Unique identifier for the subscription
Object type identifier. Always subscription.
ID of the customer this subscription belongs to
Current status. One of active, past_due, canceled, incomplete, or trialing.
Unix timestamp of creation
Unix timestamp of last update
true if live mode, false if test mode
Unix timestamp of the start of the current billing period
Unix timestamp of the end of the current billing period
Set of key-value pairs for your own reference
{
"id": "e6f7g8h9-3456-7890-cdef-1a2b3c4d5e6f",
"object": "subscription",
"customer": "235978d1-9081-45ce-a57d-e0a9659e8880",
"status": "active",
"created": 1721010605,
"updated": 1721010605,
"livemode": false,
"current_period_start": 1721010605,
"current_period_end": 1723689005,
"metadata": {}
}
List subscription change logs
Returns a paginated list of change log entries for a subscription, ordered by most recent first. Each entry captures the full before and after state of a product change, including the proration behavior used and when the adjustment was or will be collected.
Path parameters
Subscription ID
Query parameters
Page number
Results per page
Returns
Change logs retrieved
curl --request GET \
--url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a/change_logs \
--header 'Authorization: Bearer API_KEY'
{
"meta": {
"page": 1,
"url": "/v1/subscriptions/8fc6456b-31ad-49d1-8031-5438f051380f/change_logs",
"has_more": false,
"prev": null,
"next": null,
"subscription_id": "8fc6456b-31ad-49d1-8031-5438f051380f"
},
"subscription_change_logs": [
{
"id": "d2000031-3ff1-428a-849f-a63e78dc4cc9",
"proration_behavior": "always_invoice",
"previous_product": "218fb93b-d9e6-4abf-82de-bcf8a1047dea",
"new_product": "0f5c25c2-c408-40d7-9ce3-25e534f3bbe2",
"subscription": "8fc6456b-31ad-49d1-8031-5438f051380f",
"object": "subscription_change_log",
"effective_date": 1781115887,
"created": 1781115887,
"previous_plan": "bc1c5aee-255b-4308-a055-831186075326",
"current_plan": "ccd361a4-483c-4953-982b-ae1f541f895d"
}
]
}
List 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.
Path parameters
Subscription ID
Returns
A dictionary with a phases property containing an array of Subscription Phase objects in ordinal order
curl --request GET \
--url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phases \
--header 'Authorization: Bearer API_KEY'
{
"meta": {
"subscription_id": "86aedb47-97d6-44e2-b01b-8fbbb87dbde8"
},
"phases": [
{
"id": "f15f2ac6-4cba-49f4-8bd2-d2ff119c013a",
"ordinal": 5,
"name": null,
"pricing_type": "static",
"discount_percentage": null,
"period_count": 3,
"phaseable_type": "Subscription",
"phaseable_id": "86aedb47-97d6-44e2-b01b-8fbbb87dbde8",
"started_at": null,
"amount": 5000,
"currency": "USD",
"object": "subscription_phase",
"created": 1781115888,
"updated": 1781115888,
"livemode": false
}
]
}
Create a subscription phase
Creates a new subscription phase. Note that you cannot add phases after an infinite phase has been created.
Returns the Subscription Phase object after successful creation. Returns an error if create parameters are invalid.
Path parameters
Subscription ID
Query 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 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.
A descriptive name for this phase.
Returns
Returns the Subscription Phase object after successful creation
curl --request POST \
--url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phases \
--header 'Authorization: Bearer API_KEY'
{
"id": "35206591-1181-4eb2-8222-f8cc6c839b87",
"ordinal": 1,
"name": null,
"pricing_type": "relative",
"discount_percentage": "50.0",
"period_count": 3,
"phaseable_type": "Subscription",
"phaseable_id": "8119dc7e-4159-4494-8df5-00ab19f24326",
"started_at": null,
"amount": null,
"currency": "USD",
"object": "subscription_phase",
"created": 1781115888,
"updated": 1781115888,
"livemode": false
}
Retrieve a subscription phase
Retrieves the details of an existing subscription phase.
Returns a Subscription Phase object if a valid identifier was provided.
Path parameters
Subscription ID
Phase ID
Returns
Returns a Subscription Phase object if a valid identifier was provided
curl --request GET \
--url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phases/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "e49263e1-8ffc-425d-a624-9d86f940dd18",
"ordinal": 6,
"name": null,
"pricing_type": "static",
"discount_percentage": null,
"period_count": 3,
"phaseable_type": "Subscription",
"phaseable_id": "c42f7e6c-c55b-47c7-af9b-f1da52fa64c0",
"started_at": null,
"amount": 5000,
"currency": "USD",
"object": "subscription_phase",
"created": 1781115889,
"updated": 1781115889,
"livemode": false
}
Update a subscription phase
Updates the specified subscription phase by setting the values of the parameters passed.
Returns the updated Subscription Phase object if the update succeeded. Returns an error if update parameters are invalid.
Path parameters
Subscription ID
Phase ID
Query parameters
A descriptive name for this phase.
The number of billing periods this phase lasts.
The discount percentage (0-100) to apply to the base subscription amount.
The amount for this phase in cents.
Returns
Returns the updated Subscription Phase object
curl --request PATCH \
--url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phases/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "2d4da860-b547-445d-9dad-809be497c855",
"ordinal": 7,
"name": null,
"pricing_type": "static",
"discount_percentage": null,
"period_count": 6,
"phaseable_type": "Subscription",
"phaseable_id": "43e0f2d7-f576-4138-ae85-3fa463724fea",
"started_at": null,
"amount": 5000,
"currency": "USD",
"object": "subscription_phase",
"created": 1781115889,
"updated": 1781115889,
"livemode": false
}
Delete a subscription phase
Permanently deletes a subscription phase. This action cannot be undone.
Returns an empty response with HTTP status 204 (No Content) on successful deletion.
Path parameters
Subscription ID
Phase ID
curl --request DELETE \
--url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phases/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
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.
Returns a dictionary with a phases property containing all phases for the subscription after the update, along with metadata about the operation.
Path parameters
Subscription ID
Body 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
curl --request PATCH \
--url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phases/bulk_update \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"phases": [
{}
]
}'
{
"meta": {
"subscription_id": "8c1fedde-d052-4921-ae94-b72f4979b1d6",
"updated_count": 1
},
"phases": [
{
"id": "0f129128-66d3-45c6-892c-3efba5147dae",
"ordinal": 1,
"name": null,
"pricing_type": "relative",
"discount_percentage": "50.0",
"period_count": 3,
"phaseable_type": "Subscription",
"phaseable_id": "8c1fedde-d052-4921-ae94-b72f4979b1d6",
"started_at": null,
"amount": null,
"currency": "USD",
"object": "subscription_phase",
"created": 1781115889,
"updated": 1781115889,
"livemode": false
}
]
}
List subscriptions
Returns a list of Subscriptions. Results are paginated and returned in reverse chronological order.
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.
Query parameters
The page offset at which you'd like to resume fetching data.
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
Returns
A paginated list of Subscription objects
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": "e9dde5ed-f4fa-4eec-b539-0fbbc2032849",
"description": null,
"currency": "USD",
"status": "active",
"quantity": 1,
"customer": "c8513cad-3407-43bf-b2ce-3506bd707c47",
"account": null,
"default_payment_method": null,
"object": "subscription",
"created": 1781115889,
"start_date": 1781115889,
"current_period_start": 1781115889,
"current_period_end": 1783707889,
"livemode": false,
"plan": {
"id": "0d3d839c-7cf6-4b53-9475-1a8c5c66f944",
"interval": "monthly",
"interval_count": 1,
"product": "3783be50-3db9-42f6-910a-2383c84d6d8f",
"amount": 10000,
"currency": "USD",
"object": "plan",
"active": true,
"created": 1781115890,
"livemode": false
},
"phases": [],
"has_phases": false,
"current_phase": null,
"effective_amount": 10000,
"effective_interval": "monthly",
"effective_interval_count": 1,
"latest_charge": null,
"latest_charge_intent": null,
"metadata": {}
},
{
"id": "a9a5c746-122a-487a-a880-7e8d6145e4d6",
"description": null,
"currency": "USD",
"status": "active",
"quantity": 1,
"customer": "c8513cad-3407-43bf-b2ce-3506bd707c47",
"account": null,
"default_payment_method": null,
"object": "subscription",
"created": 1781115889,
"start_date": 1781115889,
"current_period_start": 1781115889,
"current_period_end": 1783707889,
"livemode": false,
"plan": {
"id": "aa5d5ec0-0064-4cb6-8bd4-cd13ee11e125",
"interval": "monthly",
"interval_count": 1,
"product": "40af2810-2ad0-4f71-a4ef-4a7c968f4049",
"amount": 10000,
"currency": "USD",
"object": "plan",
"active": true,
"created": 1781115889,
"livemode": false
},
"phases": [],
"has_phases": false,
"current_phase": null,
"effective_amount": 10000,
"effective_interval": "monthly",
"effective_interval_count": 1,
"latest_charge": null,
"latest_charge_intent": null,
"metadata": {}
},
{
"id": "2f1051d1-013c-4973-b9f2-7a493335e566",
"description": null,
"currency": "USD",
"status": "active",
"quantity": 1,
"customer": "c8513cad-3407-43bf-b2ce-3506bd707c47",
"account": null,
"default_payment_method": null,
"object": "subscription",
"created": 1781115889,
"start_date": 1781115889,
"current_period_start": 1781115889,
"current_period_end": 1783707889,
"livemode": false,
"plan": {
"id": "eceadcb7-8d32-450a-a7e1-c53fe52cb743",
"interval": "monthly",
"interval_count": 1,
"product": "25af3992-9be9-4be8-8f04-50c25b39ae73",
"amount": 10000,
"currency": "USD",
"object": "plan",
"active": true,
"created": 1781115889,
"livemode": false
},
"phases": [],
"has_phases": false,
"current_phase": null,
"effective_amount": 10000,
"effective_interval": "monthly",
"effective_interval_count": 1,
"latest_charge": null,
"latest_charge_intent": null,
"metadata": {}
}
]
}
Create subscription
Creates a new subscription on an existing customer. The product's purchase type must be recurring.
Returns the newly created Subscription object, if the call succeeded. If the attempted charge fails, the subscription is created in an incomplete status.
Query parameters
The identifier of the customer to subscribe.
Payment method ID
The ID of the product. The purchase type must be recurring.
ID of the default payment method for the subscription.
Three-letter ISO currency code, in lowercase. Must be a supported currency.
Billing interval One of month or year.
Trial period in days
JSON string of additional custom metadata
Returns
The newly created Subscription object
curl --request POST \
--url https://api.framepayments.com/v1/subscriptions \
--header 'Authorization: Bearer API_KEY'
{
"id": "143b7a47-ff5f-49d7-ae3f-e253117f2984",
"description": null,
"currency": "USD",
"status": "active",
"quantity": 1,
"customer": "08ef0963-aa9d-4f07-9ff5-6e4edd4b3810",
"account": null,
"default_payment_method": "d7473f64-c2c2-4a5f-a607-6e9b7e47157e",
"object": "subscription",
"created": 1781115890,
"start_date": 1781115890,
"current_period_start": 1781115890,
"current_period_end": 1783707890,
"livemode": false,
"plan": {
"id": "6d730882-f83f-4c76-b920-03d00bc173dc",
"interval": "monthly",
"interval_count": 1,
"product": "055abd66-8007-4b86-95ed-b7295d443f4a",
"amount": 10000,
"currency": "USD",
"object": "plan",
"active": true,
"created": 1781115890,
"livemode": false
},
"phases": [],
"has_phases": false,
"current_phase": null,
"effective_amount": 10000,
"effective_interval": "monthly",
"effective_interval_count": 1,
"latest_charge": {
"id": "cadffeb9-d917-4550-95c5-d1ca69502daa",
"currency": "usd",
"failure_code": null,
"failure_message": null,
"failure_category": null,
"description": "Subscription creation",
"status": "succeeded",
"acquirer_reference_number": null,
"authorization_code": "SANDBOXC988A2",
"object": "charge",
"payment_method_details": {
"id": "d7473f64-c2c2-4a5f-a607-6e9b7e47157e",
"customer_id": "08ef0963-aa9d-4f07-9ff5-6e4edd4b3810",
"account_id": null,
"billing": null,
"type": "card",
"object": "payment_method",
"created": 1781115890,
"updated": 1781115890,
"livemode": false,
"status": "active",
"card": {
"brand": "visa",
"exp_month": "07",
"exp_year": "31",
"issuer": null,
"currency": null,
"segment": null,
"type": null,
"last_four": "4242"
}
},
"customer": "08ef0963-aa9d-4f07-9ff5-6e4edd4b3810",
"account": null,
"account_id": null,
"payment_method": "d7473f64-c2c2-4a5f-a607-6e9b7e47157e",
"amount": 10000,
"amount_captured": 0,
"amount_refunded": 0,
"created": 1781115890,
"updated": 1781115890,
"livemode": false,
"captured": true,
"disputed": false,
"charge_intent": "7d14785b-54c9-4772-b959-45587c33a34d",
"refunded": false,
"net_amount": 9611
},
"latest_charge_intent": "7d14785b-54c9-4772-b959-45587c33a34d",
"metadata": {}
}
Get subscription
Retrieves the subscription with the given ID.
Returns the subscription object.
Path parameters
Unique identifier of the subscription.
Returns
The requested Subscription object
curl --request GET \
--url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "f5fe0ff1-a38c-433b-b2c8-65002aa835c3",
"description": null,
"currency": "USD",
"status": "pending",
"quantity": 1,
"customer": "38f645da-fb60-4753-95df-4b5f5af8e58d",
"account": null,
"default_payment_method": null,
"object": "subscription",
"created": 1781115890,
"start_date": 1781115890,
"current_period_start": 1781115890,
"current_period_end": 1783707890,
"livemode": false,
"plan": {
"id": "b072a370-a7c3-4c21-b714-ce6ce172fb8f",
"interval": "monthly",
"interval_count": 1,
"product": "20f4dea2-50d6-45c0-b5de-73ab8408e323",
"amount": 10000,
"currency": "USD",
"object": "plan",
"active": true,
"created": 1781115890,
"livemode": false
},
"phases": [],
"has_phases": false,
"current_phase": null,
"effective_amount": 10000,
"effective_interval": "monthly",
"effective_interval_count": 1,
"latest_charge": null,
"latest_charge_intent": null,
"metadata": {}
}
Update subscription
Updates an existing subscription to match the specified parameters. Any parameters not provided will be left unchanged.
Returns the newly updated Subscription object.
Path parameters
Unique identifier of the subscription.
Query parameters
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.
Returns
The updated Subscription object
curl --request PATCH \
--url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "7fc5421f-0d72-4ee8-bf5f-432d27225af7",
"description": "New description",
"currency": "USD",
"status": "pending",
"quantity": 1,
"customer": "7f6f25f3-43b8-4cbe-879b-c9fa084ac8e0",
"account": null,
"default_payment_method": null,
"object": "subscription",
"created": 1781115890,
"start_date": 1781115890,
"current_period_start": 1781115890,
"current_period_end": 1783707890,
"livemode": false,
"plan": {
"id": "9134ebfb-e6df-4fbc-affb-904346eaa455",
"interval": "monthly",
"interval_count": 1,
"product": "dce762b2-f2d1-4aa0-85a9-0dc2aed87fc7",
"amount": 10000,
"currency": "USD",
"object": "plan",
"active": true,
"created": 1781115890,
"livemode": false
},
"phases": [],
"has_phases": false,
"current_phase": null,
"effective_amount": 10000,
"effective_interval": "monthly",
"effective_interval_count": 1,
"latest_charge": null,
"latest_charge_intent": null,
"metadata": {}
}
Cancel subscription
Cancels a customer's subscription immediately. The customer will not be charged again for the subscription.
Returns the canceled Subscription object. Its subscription status will be set to canceled.
Path parameters
Unique identifier of the subscription to cancel.
Query parameters
Whether to cancel at the end of the current period
Reason for cancellation
Returns
The canceled Subscription object with status set to canceled
curl --request POST \
--url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a/cancel \
--header 'Authorization: Bearer API_KEY'
{
"id": "aee23f15-2509-49bd-8b17-0dca47f19b3a",
"description": null,
"currency": "USD",
"status": "canceled",
"quantity": 1,
"customer": "1f7a1d3c-c505-4ab9-90dc-8fd07a57e020",
"account": null,
"default_payment_method": null,
"object": "subscription",
"created": 1781115890,
"start_date": 1781115890,
"current_period_start": 1781115890,
"current_period_end": 1783707890,
"livemode": false,
"plan": {
"id": "0fc2654a-5ed3-4d6c-b34b-52654a0ed4ad",
"interval": "monthly",
"interval_count": 1,
"product": "aca262d6-57fb-42ea-b93d-63709505838d",
"amount": 10000,
"currency": "USD",
"object": "plan",
"active": true,
"created": 1781115890,
"livemode": false
},
"phases": [],
"has_phases": false,
"current_phase": null,
"effective_amount": 10000,
"effective_interval": "monthly",
"effective_interval_count": 1,
"latest_charge": null,
"latest_charge_intent": null,
"metadata": {}
}
Search subscriptions
Search for subscriptions 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.
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.
Query parameters
Filter by customer ID
The status of the subscription. One of pending, active, terminated, or canceled.
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.
The page offset at which you'd like to resume fetching data.
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
Returns
A paginated list of Subscription objects matching the search criteria
curl --request GET \
--url https://api.framepayments.com/v1/subscriptions/search \
--header 'Authorization: Bearer API_KEY'
{
"meta": {
"page": 1,
"url": "/v1/subscriptions/search?customer=%23%3CCustomer%3A0x0000000135562800%3E&status=active",
"has_more": false,
"prev": null,
"next": null
},
"subscriptions": [
{
"id": "e81939fd-aa63-4857-a334-8b5d4581d344",
"description": null,
"currency": "USD",
"status": "active",
"quantity": 1,
"customer": "a84cdc7f-fd1a-4a66-a1e9-9170e3a9e443",
"account": null,
"default_payment_method": null,
"object": "subscription",
"created": 1781115890,
"start_date": 1781115890,
"current_period_start": 1781115890,
"current_period_end": 1783707890,
"livemode": false,
"plan": {
"id": "a2b1bfa1-3158-4786-9bae-ee68848032ba",
"interval": "monthly",
"interval_count": 1,
"product": "b2893d01-2092-44ee-83b9-4c0cb2627c16",
"amount": 10000,
"currency": "USD",
"object": "plan",
"active": true,
"created": 1781115890,
"livemode": false
},
"phases": [],
"has_phases": false,
"current_phase": null,
"effective_amount": 10000,
"effective_interval": "monthly",
"effective_interval_count": 1,
"latest_charge": null,
"latest_charge_intent": null,
"metadata": {}
},
{
"id": "29ab2bf5-ec88-49b9-9c87-11ca982d95bc",
"description": null,
"currency": "USD",
"status": "active",
"quantity": 1,
"customer": "a84cdc7f-fd1a-4a66-a1e9-9170e3a9e443",
"account": null,
"default_payment_method": null,
"object": "subscription",
"created": 1781115890,
"start_date": 1781115890,
"current_period_start": 1781115890,
"current_period_end": 1783707890,
"livemode": false,
"plan": {
"id": "b2024679-e9f5-46e0-b9bb-15d377133c6d",
"interval": "monthly",
"interval_count": 1,
"product": "f4ff3d08-d290-4051-a787-30d1a208a018",
"amount": 10000,
"currency": "USD",
"object": "plan",
"active": true,
"created": 1781115890,
"livemode": false
},
"phases": [],
"has_phases": false,
"current_phase": null,
"effective_amount": 10000,
"effective_interval": "monthly",
"effective_interval_count": 1,
"latest_charge": null,
"latest_charge_intent": null,
"metadata": {}
}
]
}