Subscriptions

Create and manage subscriptions. Subscriptions represent recurring billing relationships between your platform and a customer, tied to a product and billing interval.

export FRAME_API_KEY='sk_sandbox_...'

The Subscription object

Attributes
idstring

Unique identifier for the subscription

objectstring

Object type identifier. Always subscription.

accountnullable string

ID of the account this subscription belongs to. null on legacy customer-owned subscriptions.

customernullable string

ID of the customer this subscription belongs to, if it is owned by a legacy customer. Deprecated — create subscriptions with account instead.

statusstring

Current status. One of pending, active, paused, past_due, unpaid, incomplete, canceled, or terminated.

createdinteger

Unix timestamp of creation

updatedinteger

Unix timestamp of last update

livemodeboolean

true if live mode, false if test mode

current_period_startnullable integer

Unix timestamp of the start of the current billing period

current_period_endnullable integer

Unix timestamp of the end of the current billing period

paused_atnullable integer

Unix timestamp of when the subscription entered the current paused state, if paused.

resume_atnullable integer

Unix timestamp of the scheduled resume time for the current pause, if one is set.

metadataobject

Set of key-value pairs for your own reference

THE SUBSCRIPTION OBJECT
{
  "id": "e6f7g8h9-3456-7890-cdef-1a2b3c4d5e6f",
  "object": "subscription",
  "account": "235978d1-9081-45ce-a57d-e0a9659e8880",
  "customer": null,
  "status": "active",
  "created": 1721010605,
  "updated": 1721010605,
  "livemode": false,
  "current_period_start": 1721010605,
  "current_period_end": 1723689005,
  "paused_at": 1721010605,
  "resume_at": 1721270605,
  "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_idstringrequired

Subscription ID

Query parameters
pageintegeroptional

Page number

per_pageintegeroptional

Results per page

Returns

Change logs retrieved

GET/v1/subscriptions/{subscription_id}/change_logs
curl --request GET \
  --url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a/change_logs \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/subscriptions/00000000-0000-4000-8000-000000000001/change_logs",
    "has_more": false,
    "prev": null,
    "next": null,
    "subscription_id": "00000000-0000-4000-8000-000000000001"
  },
  "subscription_change_logs": [
    {
      "id": "00000000-0000-4000-8000-000000000002",
      "proration_behavior": "always_invoice",
      "previous_product": "00000000-0000-4000-8000-000000000003",
      "new_product": "00000000-0000-4000-8000-000000000004",
      "subscription": "00000000-0000-4000-8000-000000000001",
      "object": "subscription_change_log",
      "effective_date": 1745107200,
      "created": 1745107200,
      "previous_plan": "00000000-0000-4000-8000-000000000005",
      "current_plan": "00000000-0000-4000-8000-000000000006"
    }
  ]
}

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_idstringrequired

Subscription ID

Returns

A dictionary with a phases property containing an array of Subscription Phase objects in ordinal order

GET/v1/subscriptions/{subscription_id}/phases
curl --request GET \
  --url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phases \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "subscription_id": "00000000-0000-4000-8000-000000000001"
  },
  "phases": [
    {
      "id": "00000000-0000-4000-8000-000000000002",
      "ordinal": 1,
      "name": null,
      "pricing_type": "static",
      "discount_percentage": null,
      "period_count": 3,
      "phaseable_type": "Subscription",
      "phaseable_id": "00000000-0000-4000-8000-000000000001",
      "started_at": null,
      "amount": 5000,
      "currency": "USD",
      "object": "subscription_phase",
      "created": 1745107200,
      "updated": 1745107200,
      "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_idstringrequired

Subscription ID

Query 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.

amount_centsintegeroptional

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

discount_percentagenumberoptional

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.

namestringoptional

A descriptive name for this phase.

Returns

Returns the Subscription Phase object after successful creation

POST/v1/subscriptions/{subscription_id}/phases
curl --request POST \
  --url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phases \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "ordinal": 1,
  "name": null,
  "pricing_type": "relative",
  "discount_percentage": "50.0",
  "period_count": 3,
  "phaseable_type": "Subscription",
  "phaseable_id": "00000000-0000-4000-8000-000000000002",
  "started_at": null,
  "amount": null,
  "currency": "USD",
  "object": "subscription_phase",
  "created": 1745107200,
  "updated": 1745107200,
  "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_idstringrequired

Subscription ID

idstringrequired

Phase ID

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/a70cd72f-e74a-40f2-96a2-3f60714aac4a/phases/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "ordinal": 1,
  "name": null,
  "pricing_type": "static",
  "discount_percentage": null,
  "period_count": 3,
  "phaseable_type": "Subscription",
  "phaseable_id": "00000000-0000-4000-8000-000000000002",
  "started_at": null,
  "amount": 5000,
  "currency": "USD",
  "object": "subscription_phase",
  "created": 1745107200,
  "updated": 1745107200,
  "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_idstringrequired

Subscription ID

idstringrequired

Phase ID

Query parameters
namestringoptional

A descriptive name for this phase.

period_countintegeroptional

The number of billing periods this phase lasts.

discount_percentagenumberoptional

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

amount_centsintegeroptional

The amount for this phase in cents.

Returns

Returns the updated Subscription Phase object

PATCH/v1/subscriptions/{subscription_id}/phases/{id}
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'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "ordinal": 1,
  "name": null,
  "pricing_type": "static",
  "discount_percentage": null,
  "period_count": 6,
  "phaseable_type": "Subscription",
  "phaseable_id": "00000000-0000-4000-8000-000000000002",
  "started_at": null,
  "amount": 5000,
  "currency": "USD",
  "object": "subscription_phase",
  "created": 1745107200,
  "updated": 1745107200,
  "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_idstringrequired

Subscription ID

idstringrequired

Phase ID

DELETE/v1/subscriptions/{subscription_id}/phases/{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_idstringrequired

Subscription ID

Body 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

PATCH/v1/subscriptions/{subscription_id}/phases/bulk_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": [
    {}
  ]
}'
RESPONSE
{
  "meta": {
    "subscription_id": "00000000-0000-4000-8000-000000000001",
    "updated_count": 1
  },
  "phases": [
    {
      "id": "00000000-0000-4000-8000-000000000002",
      "ordinal": 1,
      "name": null,
      "pricing_type": "relative",
      "discount_percentage": "50.0",
      "period_count": 3,
      "phaseable_type": "Subscription",
      "phaseable_id": "00000000-0000-4000-8000-000000000001",
      "started_at": null,
      "amount": null,
      "currency": "USD",
      "object": "subscription_phase",
      "created": 1745107200,
      "updated": 1745107200,
      "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
pageintegeroptional

The page offset at which you'd like to resume fetching data.

per_pageintegeroptional

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

GET/v1/subscriptions
curl --request GET \
  --url https://api.framepayments.com/v1/subscriptions \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/subscriptions",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "subscriptions": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "description": null,
      "currency": "USD",
      "status": "active",
      "quantity": 1,
      "customer": null,
      "account": "00000000-0000-4000-8000-000000000002",
      "default_payment_method": null,
      "object": "subscription",
      "created": 1745107200,
      "start_date": 1745107200,
      "current_period_start": 1745107200,
      "current_period_end": 1747699200,
      "paused_at": null,
      "resume_at": null,
      "livemode": false,
      "plan": {
        "id": "00000000-0000-4000-8000-000000000003",
        "interval": "monthly",
        "interval_count": 1,
        "product": "00000000-0000-4000-8000-000000000004",
        "amount": 10000,
        "currency": "USD",
        "object": "plan",
        "active": true,
        "created": 1745107200,
        "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": "00000000-0000-4000-8000-000000000005",
      "description": null,
      "currency": "USD",
      "status": "active",
      "quantity": 1,
      "customer": null,
      "account": "00000000-0000-4000-8000-000000000002",
      "default_payment_method": null,
      "object": "subscription",
      "created": 1745107200,
      "start_date": 1745107200,
      "current_period_start": 1745107200,
      "current_period_end": 1747699200,
      "paused_at": null,
      "resume_at": null,
      "livemode": false,
      "plan": {
        "id": "00000000-0000-4000-8000-000000000006",
        "interval": "monthly",
        "interval_count": 1,
        "product": "00000000-0000-4000-8000-000000000007",
        "amount": 10000,
        "currency": "USD",
        "object": "plan",
        "active": true,
        "created": 1745107200,
        "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": "00000000-0000-4000-8000-000000000008",
      "description": null,
      "currency": "USD",
      "status": "active",
      "quantity": 1,
      "customer": null,
      "account": "00000000-0000-4000-8000-000000000002",
      "default_payment_method": null,
      "object": "subscription",
      "created": 1745107200,
      "start_date": 1745107200,
      "current_period_start": 1745107200,
      "current_period_end": 1747699200,
      "paused_at": null,
      "resume_at": null,
      "livemode": false,
      "plan": {
        "id": "00000000-0000-4000-8000-000000000009",
        "interval": "monthly",
        "interval_count": 1,
        "product": "00000000-0000-4000-8000-000000000010",
        "amount": 10000,
        "currency": "USD",
        "object": "plan",
        "active": true,
        "created": 1745107200,
        "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 for an existing account. 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
accountstringrequired

The identifier of the account to subscribe.

payment_methodstringrequired

Payment method ID

productstringrequired

The ID of the product. The purchase type must be recurring.

default_payment_methodstringrequired

ID of the default payment method for the subscription.

currencystringrequired

Three-letter ISO currency code, in lowercase. Must be a supported currency.

billing_intervalenumoptional

Billing interval One of month or year.

trial_period_daysintegeroptional

Trial period in days

metadatastringoptional

JSON string of additional custom metadata

Returns

The newly created Subscription object

POST/v1/subscriptions
curl --request POST \
  --url https://api.framepayments.com/v1/subscriptions \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "description": null,
  "currency": "USD",
  "status": "active",
  "quantity": 1,
  "customer": null,
  "account": "00000000-0000-4000-8000-000000000002",
  "default_payment_method": "00000000-0000-4000-8000-000000000003",
  "object": "subscription",
  "created": 1745107200,
  "start_date": 1745107200,
  "current_period_start": 1745107200,
  "current_period_end": 1747699200,
  "paused_at": null,
  "resume_at": null,
  "livemode": false,
  "plan": {
    "id": "00000000-0000-4000-8000-000000000004",
    "interval": "monthly",
    "interval_count": 1,
    "product": "00000000-0000-4000-8000-000000000005",
    "amount": 10000,
    "currency": "USD",
    "object": "plan",
    "active": true,
    "created": 1745107200,
    "livemode": false
  },
  "phases": [],
  "has_phases": false,
  "current_phase": null,
  "effective_amount": 10000,
  "effective_interval": "monthly",
  "effective_interval_count": 1,
  "latest_charge": {
    "id": "00000000-0000-4000-8000-000000000006",
    "currency": "usd",
    "failure_code": null,
    "failure_message": null,
    "failure_category": null,
    "description": "Subscription creation",
    "status": "succeeded",
    "acquirer_reference_number": null,
    "authorization_code": "SANDBOX000001",
    "object": "charge",
    "payment_method_details": {
      "id": "00000000-0000-4000-8000-000000000003",
      "customer_id": null,
      "account_id": "00000000-0000-4000-8000-000000000002",
      "billing": null,
      "type": "card",
      "object": "payment_method",
      "created": 1745107200,
      "updated": 1745107200,
      "livemode": false,
      "status": "active",
      "card": {
        "brand": "visa",
        "exp_month": "03",
        "exp_year": "30",
        "issuer": null,
        "currency": null,
        "segment": null,
        "type": null,
        "last_four": "4242",
        "instant_available": false,
        "instant_unavailable_reason": "card_not_debit",
        "instant_steer_to": "bank_account"
      }
    },
    "customer": null,
    "account": "00000000-0000-4000-8000-000000000002",
    "account_id": "00000000-0000-4000-8000-000000000002",
    "payment_method": "00000000-0000-4000-8000-000000000003",
    "amount": 10000,
    "amount_captured": 0,
    "amount_refunded": 0,
    "created": 1745107200,
    "updated": 1745107200,
    "livemode": false,
    "captured": true,
    "disputed": false,
    "charge_intent": "00000000-0000-4000-8000-000000000007",
    "refunded": false,
    "net_amount": 9611
  },
  "latest_charge_intent": "00000000-0000-4000-8000-000000000007",
  "metadata": {}
}

Get subscription

Retrieves the subscription with the given ID.

Returns the subscription object.

Path parameters
idstringrequired

Unique identifier of the subscription.

Returns

The requested Subscription object

GET/v1/subscriptions/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "description": null,
  "currency": "USD",
  "status": "pending",
  "quantity": 1,
  "customer": null,
  "account": "00000000-0000-4000-8000-000000000002",
  "default_payment_method": null,
  "object": "subscription",
  "created": 1745107200,
  "start_date": 1745107200,
  "current_period_start": 1745107200,
  "current_period_end": 1747699200,
  "paused_at": null,
  "resume_at": null,
  "livemode": false,
  "plan": {
    "id": "00000000-0000-4000-8000-000000000003",
    "interval": "monthly",
    "interval_count": 1,
    "product": "00000000-0000-4000-8000-000000000004",
    "amount": 10000,
    "currency": "USD",
    "object": "plan",
    "active": true,
    "created": 1745107200,
    "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
idstringrequired

Unique identifier of the subscription.

Query parameters
default_payment_methodstringoptional

ID of the default payment method for the subscription. It must belong to the account associated with the subscription.

descriptionstringoptional

The subscription's description, meant to be displayable to the customer.

Returns

The updated Subscription object

PATCH/v1/subscriptions/{id}
curl --request PATCH \
  --url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "description": "New description",
  "currency": "USD",
  "status": "pending",
  "quantity": 1,
  "customer": null,
  "account": "00000000-0000-4000-8000-000000000002",
  "default_payment_method": null,
  "object": "subscription",
  "created": 1745107200,
  "start_date": 1745107200,
  "current_period_start": 1745107200,
  "current_period_end": 1747699200,
  "paused_at": null,
  "resume_at": null,
  "livemode": false,
  "plan": {
    "id": "00000000-0000-4000-8000-000000000003",
    "interval": "monthly",
    "interval_count": 1,
    "product": "00000000-0000-4000-8000-000000000004",
    "amount": 10000,
    "currency": "USD",
    "object": "plan",
    "active": true,
    "created": 1745107200,
    "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 subscription immediately. The account will not be charged again for the subscription.

Returns the canceled Subscription object. Its subscription status will be set to canceled.

Path parameters
idstringrequired

Unique identifier of the subscription to cancel.

Query parameters
cancel_at_period_endbooleanoptional

Whether to cancel at the end of the current period

reasonstringoptional

Reason for cancellation

Returns

The canceled Subscription object with status set to canceled

POST/v1/subscriptions/{id}/cancel
curl --request POST \
  --url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a/cancel \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "description": null,
  "currency": "USD",
  "status": "canceled",
  "quantity": 1,
  "customer": null,
  "account": "00000000-0000-4000-8000-000000000002",
  "default_payment_method": null,
  "object": "subscription",
  "created": 1745107200,
  "start_date": 1745107200,
  "current_period_start": 1745107200,
  "current_period_end": 1747699200,
  "paused_at": null,
  "resume_at": null,
  "livemode": false,
  "plan": {
    "id": "00000000-0000-4000-8000-000000000003",
    "interval": "monthly",
    "interval_count": 1,
    "product": "00000000-0000-4000-8000-000000000004",
    "amount": 10000,
    "currency": "USD",
    "object": "plan",
    "active": true,
    "created": 1745107200,
    "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": {}
}

Pause subscription

Pauses an active subscription immediately. While paused, renewal is frozen and the subscription remains visible with status paused.

Returns the paused Subscription object.

Path parameters
idstringrequired

Unique identifier of the subscription to pause.

Query parameters
resume_atstringoptional

Optional scheduled resume time for the current pause.

Returns

The paused Subscription object with status set to paused

POST/v1/subscriptions/{id}/pause
curl --request POST \
  --url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a/pause \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "description": null,
  "currency": "USD",
  "status": "paused",
  "quantity": 1,
  "customer": null,
  "account": "00000000-0000-4000-8000-000000000002",
  "default_payment_method": "00000000-0000-4000-8000-000000000003",
  "object": "subscription",
  "created": 1745107200,
  "start_date": 1745107200,
  "current_period_start": 1745107200,
  "current_period_end": 1746316800,
  "paused_at": 1745107200,
  "resume_at": 1745539200,
  "livemode": false,
  "plan": {
    "id": "00000000-0000-4000-8000-000000000004",
    "interval": "monthly",
    "interval_count": 1,
    "product": "00000000-0000-4000-8000-000000000005",
    "amount": 10000,
    "currency": "USD",
    "object": "plan",
    "active": true,
    "created": 1745107200,
    "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": {}
}

Resume subscription

Resumes a paused subscription. Resuming is money-neutral and shifts the billing anchors by the paused duration.

Returns the resumed Subscription object.

Path parameters
idstringrequired

Unique identifier of the subscription to resume.

Returns

The resumed Subscription object with status set to active

POST/v1/subscriptions/{id}/resume
curl --request POST \
  --url https://api.framepayments.com/v1/subscriptions/a70cd72f-e74a-40f2-96a2-3f60714aac4a/resume \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "description": null,
  "currency": "USD",
  "status": "active",
  "quantity": 1,
  "customer": null,
  "account": "00000000-0000-4000-8000-000000000002",
  "default_payment_method": "00000000-0000-4000-8000-000000000003",
  "object": "subscription",
  "created": 1745107200,
  "start_date": 1745107200,
  "current_period_start": 1745193600,
  "current_period_end": 1747785600,
  "paused_at": null,
  "resume_at": null,
  "livemode": false,
  "plan": {
    "id": "00000000-0000-4000-8000-000000000004",
    "interval": "monthly",
    "interval_count": 1,
    "product": "00000000-0000-4000-8000-000000000005",
    "amount": 10000,
    "currency": "USD",
    "object": "plan",
    "active": true,
    "created": 1745107200,
    "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
statusenumoptional

The status of the subscription. One of pending, active, paused, terminated, canceled, incomplete, past_due, or unpaid.

created_beforeintegeroptional

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

created_afterintegeroptional

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

pageintegeroptional

The page offset at which you'd like to resume fetching data.

per_pageintegeroptional

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

GET/v1/subscriptions/search
curl --request GET \
  --url https://api.framepayments.com/v1/subscriptions/search \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/subscriptions/search?status=active",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "subscriptions": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "description": null,
      "currency": "USD",
      "status": "active",
      "quantity": 1,
      "customer": null,
      "account": "00000000-0000-4000-8000-000000000002",
      "default_payment_method": null,
      "object": "subscription",
      "created": 1745107200,
      "start_date": 1745107200,
      "current_period_start": 1745107200,
      "current_period_end": 1747699200,
      "paused_at": null,
      "resume_at": null,
      "livemode": false,
      "plan": {
        "id": "00000000-0000-4000-8000-000000000003",
        "interval": "monthly",
        "interval_count": 1,
        "product": "00000000-0000-4000-8000-000000000004",
        "amount": 10000,
        "currency": "USD",
        "object": "plan",
        "active": true,
        "created": 1745107200,
        "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": "00000000-0000-4000-8000-000000000005",
      "description": null,
      "currency": "USD",
      "status": "active",
      "quantity": 1,
      "customer": null,
      "account": "00000000-0000-4000-8000-000000000002",
      "default_payment_method": null,
      "object": "subscription",
      "created": 1745107200,
      "start_date": 1745107200,
      "current_period_start": 1745107200,
      "current_period_end": 1747699200,
      "paused_at": null,
      "resume_at": null,
      "livemode": false,
      "plan": {
        "id": "00000000-0000-4000-8000-000000000006",
        "interval": "monthly",
        "interval_count": 1,
        "product": "00000000-0000-4000-8000-000000000007",
        "amount": 10000,
        "currency": "USD",
        "object": "plan",
        "active": true,
        "created": 1745107200,
        "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": {}
    }
  ]
}