Subscription

Subscriptions allow you to charge a customer on a recurring basis.

The Subscription object

Attributes
idstring

Unique identifier for the object.

descriptionstring

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

current_period_startstring

Start of the current period that the subscription has been invoiced for.

current_period_endstring

End of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.

livemodestring

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

currencystring

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

statusstring

Status of this Subscription, one of pending, active, terminated, or canceled.

customerstring

ID of the customer who owns the subscription.

default_payment_methodstring

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

objectstring

String representing the object's type. Objects of the same type share the same value.

createdstring

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

start_datestring

Date when the subscription was first created. The date might differ from the created date due to backdating.

THE SUBSCRIPTION OBJECT
{
  "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
  },
  "currency": "USD",
  "status": "pending",
  "quantity": 1,
  "customer": "ca98780e-2d73-46ae-89cb-8aefe72d7a23",
  "default_payment_method": "f4f05ac4-5b33-4281-a305-bf7106a6a664",
  "object": "subscription",
  "created": 1720695392,
  "start_date": 1720695392
}

Create a subscription

Creates a new subscription on an existing customer.

Parameters
customerREQUIREDstring

The identifier of the customer to subscribe.

productREQUIREDstring

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

currencyREQUIREDstring

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

default_payment_methodREQUIREDstring

ID of the default payment method for the subscription.

descriptionstring

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

Returns

The newly created Subscription object, if the call succeeded. If the attempted charge fails, the subscription is created in an incomplete status.

POST/v1/subscriptions
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"
}'
RESPONSE
{
  "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
  },
  "currency": "USD",
  "status": "pending",
  "quantity": 1,
  "customer": "ca98780e-2d73-46ae-89cb-8aefe72d7a23",
  "default_payment_method": "f4f05ac4-5b33-4281-a305-bf7106a6a664",
  "object": "subscription",
  "created": 1720695392,
  "start_date": 1720695392
}

Update a subscription

Updates an existing subscription to match the specified parameters.

Parameters
default_payment_methodstring

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

descriptionstring

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

Returns

The newly updated Subscription object.

PATCH/v1/subscriptions/:id
curl --request PATCH \
  --url https://api.framepayments.com/v1/subscriptions/6f34a36b-052e-4846-8d6f-2c555e5bdd8b \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "description": "Smart"
}'
RESPONSE
{
  "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",
  "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.

GET/v1/subscriptions:id
curl --request GET \
  --url https://api.framepayments.com/v1/subscriptions/398f4d2f-0679-4820-8b15-c7947c9b365f \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "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
  },
  "currency": "USD",
  "status": "pending",
  "quantity": 1,
  "customer": "ca98780e-2d73-46ae-89cb-8aefe72d7a23",
  "default_payment_method": "f4f05ac4-5b33-4281-a305-bf7106a6a664",
  "object": "subscription",
  "created": 1720695392,
  "start_date": 1720695392
}

List subscriptions

Returns a list of Subscriptions.

Parameters
per_pageinteger

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 50.

pageinteger

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.

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": "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
      },
      "currency": "USD",
      "status": "pending",
      "quantity": 1,
      "customer": "ca98780e-2d73-46ae-89cb-8aefe72d7a23",
      "default_payment_method": "f4f05ac4-5b33-4281-a305-bf7106a6a664",
      "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
statusstring

The status of the subscription

created_beforeinteger

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

created_afterinteger

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.

GET/v1/subscriptions/search
curl --request GET \
  --url 'https://api.framepayments.com/v1/subscriptions/search?status=pending' \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "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
      },
      "currency": "USD",
      "status": "pending",
      "quantity": 1,
      "customer": "ca98780e-2d73-46ae-89cb-8aefe72d7a23",
      "default_payment_method": "f4f05ac4-5b33-4281-a305-bf7106a6a664",
      "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.

GET/v1/subscriptions/:id/cancel
curl --request POST \
  --url https://api.framepayments.com/v1/subscriptions/398f4d2f-0679-4820-8b15-c7947c9b365f/cancel \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "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
  },
  "currency": "USD",
  "status": "canceled",
  "quantity": 1,
  "customer": "ca98780e-2d73-46ae-89cb-8aefe72d7a23",
  "default_payment_method": "f4f05ac4-5b33-4281-a305-bf7106a6a664",
  "object": "subscription",
  "created": 1720695392,
  "start_date": 1720695392
}