API Reference

Subscriptions

Subscriptions are the cornerstone of recurring billing in PaymentKit. The Subscriptions API allows you to manage the entire lifecycle of a customer's subscription, from creation and updates to pausing, resuming, and cancellation. This reference provides detailed information on all available subscription-related methods.
For a more hands-on guide to implementing subscription workflows, see the Subscriptions guide.
The Subscription Object#A Subscription object contains all the information about a customer's recurring payment plan.
Attribute
Type
Description
id
string
Unique identifier for the subscription.
status
string
The status of the subscription. Can be active, past_due, paused, canceled, incomplete, incomplete_expired, or trialing.
customer_id
string
The ID of the customer this subscription belongs to.
currency_id
string
The ID of the currency for the subscription.
current_period_start
number
The start of the current billing period, as a Unix timestamp.
current_period_end
number
The end of the current billing period, as a Unix timestamp.
cancel_at_period_end
boolean
If true, the subscription will be canceled at the end of the current period.
canceled_at
number
The time the subscription was canceled, as a Unix timestamp.
start_date
number
The start date of the subscription, as a Unix timestamp.
ended_at
number
The end date of the subscription, as a Unix timestamp.
trial_start
number
The start of the trial period, as a Unix timestamp.
trial_end
number
The end of the trial period, as a Unix timestamp.
collection_method
string
Either charge_automatically, or send_invoice.
default_payment_method_id
string
The ID of the default payment method for the subscription.
latest_invoice_id
string
The ID of the latest invoice generated for this subscription.
metadata
object
A set of key-value pairs that you can attach to an object.
cancelation_details
object
Provides details about the cancellation if the subscription was canceled. Contains comment, feedback, and reason.
pause_collection
object
Provides details about the pause state if the subscription is paused. Contains behavior and resumes_at.
Retrieve a Subscription#Retrieves the details of an existing subscription by its unique ID.
Parameters
Name
Type
Description
id
string
The unique identifier of the subscription to retrieve.
Returns
The Subscription object, if found. When retrieved, the object is expanded with additional details (TSubscriptionExpanded).
async function retrieveSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.retrieve(subscriptionId);
    console.log('Retrieved subscription:', subscription);
  } catch (error) {
    console.error('Error retrieving subscription:', error.message);
  }
}

retrieveSubscription('sub_xxxxxxxxxxxxxx');Example Response
{
  "id": "sub_xxxxxxxxxxxxxx",
  "livemode": false,
  "currency_id": "usd",
  "customer_id": "cus_xxxxxxxxxxxxxx",
  "current_period_end": 1672531199,
  "current_period_start": 1669852800,
  "status": "active",
  "cancel_at_period_end": false,
  "billing_cycle_anchor": 1669852800,
  "collection_method": "charge_automatically",
  "start_date": 1669852800,
  "metadata": {}
}Update a Subscription#Updates an existing subscription by setting or unsetting properties.
Parameters
Name
Type
Description
id
string
The unique identifier of the subscription to update.
data
object
An object containing the fields to update.
Data Fields
Name
Type
Description
description
string
An arbitrary string attached to the subscription.
default_payment_method_id
string
ID of the default payment method for the subscription.
metadata
object
A set of key-value pairs to store with the subscription.
proration_behavior
string
Determines how to handle prorations when the billing cycle changes. Can be always_invoice, create_prorations, or none.
async function updateSubscription(subscriptionId) {
  try {
    const updatedSubscription = await payment.subscriptions.update(subscriptionId, {
      metadata: { order_id: '6735' }
    });
    console.log('Updated subscription:', updatedSubscription);
  } catch (error) {
    console.error('Error updating subscription:', error.message);
  }
}

updateSubscription('sub_xxxxxxxxxxxxxx');Example Response
{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "active",
  "metadata": {
    "order_id": "6735"
  }
}List Subscriptions#Returns a list of your subscriptions. The subscriptions are returned sorted by creation date, with the most recent ones appearing first.
Parameters
Name
Type
Description
status
string
Filter subscriptions by status (e.g., active, trialing, canceled).
customer_id
string
Filter by a specific customer ID.
customer_did
string
Filter by a specific customer DID.
activeFirst
boolean
If true, active subscriptions are listed first.
order
string or array
Sort order (e.g., 'created_at:DESC').
page
number
The page number for pagination.
pageSize
number
The number of items per page. Defaults to 20.
async function listSubscriptions() {
  try {
    const subscriptions = await payment.subscriptions.list({ 
      status: 'active',
      limit: 5
    });
    console.log('Active subscriptions:', subscriptions.list);
  } catch (error) {
    console.error('Error listing subscriptions:', error.message);
  }
}

listSubscriptions();Example Response
{
  "count": 50,
  "list": [
    {
      "id": "sub_xxxxxxxxxxxxxx",
      "customer_id": "cus_xxxxxxxxxxxxxx",
      "status": "active",
      "current_period_end": 1672531199
    }
  ]
}Cancel a Subscription#Cancels a customer’s subscription. The subscription status will be set to canceled.
Parameters
Name
Type
Description
id
string
The unique identifier of the subscription to cancel.
body
object
An object containing cancellation parameters.
Body Fields
Name
Type
Description
at
string
When to cancel. Can be now, current_period_end, or custom.
time
number or string
Required if at is custom. The Unix timestamp when the cancellation should take effect.
refund
string
Specifies refund behavior. Can be none, proration, or last.
reason
string
Reason for cancellation (e.g., cancellation_requested, payment_failed).
feedback
string
Customer feedback for the cancellation.
comment
string
An internal comment about the cancellation.
async function cancelSubscription(subscriptionId) {
  try {
    const canceledSubscription = await payment.subscriptions.cancel(subscriptionId, {
      at: 'current_period_end',
      reason: 'cancellation_requested',
      feedback: 'switched_service'
    });
    console.log('Subscription scheduled for cancellation:', canceledSubscription);
  } catch (error) {
    console.error('Error canceling subscription:', error.message);
  }
}

cancelSubscription('sub_xxxxxxxxxxxxxx');Example Response
{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "active",
  "cancel_at_period_end": true,
  "canceled_at": null,
  "cancelation_details": {
    "reason": "cancellation_requested",
    "feedback": "switched_service"
  }
}Pause a Subscription#Pauses the collection of payments for a subscription. The subscription status will be set to paused.
Parameters
Name
Type
Description
id
string
The unique identifier of the subscription to pause.
async function pauseSubscription(subscriptionId) {
  try {
    const pausedSubscription = await payment.subscriptions.pause(subscriptionId);
    console.log('Paused subscription:', pausedSubscription);
  } catch (error) {
    console.error('Error pausing subscription:', error.message);
  }
}

pauseSubscription('sub_xxxxxxxxxxxxxx');Example Response
{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "paused",
  "pause_collection": {
    "behavior": "keep_as_draft",
    "resumes_at": 1672531199
  }
}Resume a Subscription#Resumes a paused subscription. The subscription status will be set back to active.
Parameters
Name
Type
Description
id
string
The unique identifier of the subscription to resume.
async function resumeSubscription(subscriptionId) {
  try {
    const resumedSubscription = await payment.subscriptions.resume(subscriptionId);
    console.log('Resumed subscription:', resumedSubscription);
  } catch (error) {
    console.error('Error resuming subscription:', error.message);
  }
}

resumeSubscription('sub_xxxxxxxxxxxxxx');Example Response
{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "active",
  "pause_collection": null
}Recover a Subscription#Recovers a canceled subscription. This is useful if a customer changes their mind after cancellation.
Parameters
Name
Type
Description
id
string
The unique identifier of the subscription to recover.
async function recoverSubscription(subscriptionId) {
  try {
    const recoveredSubscription = await payment.subscriptions.recover(subscriptionId);
    console.log('Recovered subscription:', recoveredSubscription);
  } catch (error) {
    console.error('Error recovering subscription:', error.message);
  }
}

recoverSubscription('sub_xxxxxxxxxxxxxx');Example Response
{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "active",
  "recovered_from": "sub_originalxxxxxx"
}
You now have a detailed understanding of how to manage subscriptions. To manage the individual products or services within a subscription, proceed to the Subscription Items API reference.

Attribute	Type	Description
`id`	`string`	Unique identifier for the subscription.
`status`	`string`	The status of the subscription. Can be `active`, `past_due`, `paused`, `canceled`, `incomplete`, `incomplete_expired`, or `trialing`.
`customer_id`	`string`	The ID of the customer this subscription belongs to.
`currency_id`	`string`	The ID of the currency for the subscription.
`current_period_start`	`number`	The start of the current billing period, as a Unix timestamp.
`current_period_end`	`number`	The end of the current billing period, as a Unix timestamp.
`cancel_at_period_end`	`boolean`	If true, the subscription will be canceled at the end of the current period.
`canceled_at`	`number`	The time the subscription was canceled, as a Unix timestamp.
`start_date`	`number`	The start date of the subscription, as a Unix timestamp.
`ended_at`	`number`	The end date of the subscription, as a Unix timestamp.
`trial_start`	`number`	The start of the trial period, as a Unix timestamp.
`trial_end`	`number`	The end of the trial period, as a Unix timestamp.
`collection_method`	`string`	Either `charge_automatically`, or `send_invoice`.
`default_payment_method_id`	`string`	The ID of the default payment method for the subscription.
`latest_invoice_id`	`string`	The ID of the latest invoice generated for this subscription.
`metadata`	`object`	A set of key-value pairs that you can attach to an object.
`cancelation_details`	`object`	Provides details about the cancellation if the subscription was canceled. Contains `comment`, `feedback`, and `reason`.
`pause_collection`	`object`	Provides details about the pause state if the subscription is paused. Contains `behavior` and `resumes_at`.

Name	Type	Description
`description`	`string`	An arbitrary string attached to the subscription.
`default_payment_method_id`	`string`	ID of the default payment method for the subscription.
`metadata`	`object`	A set of key-value pairs to store with the subscription.
`proration_behavior`	`string`	Determines how to handle prorations when the billing cycle changes. Can be `always_invoice`, `create_prorations`, or `none`.

Name	Type	Description
`status`	`string`	Filter subscriptions by status (e.g., `active`, `trialing`, `canceled`).
`customer_id`	`string`	Filter by a specific customer ID.
`customer_did`	`string`	Filter by a specific customer DID.
`activeFirst`	`boolean`	If `true`, active subscriptions are listed first.
`order`	`string` or `array`	Sort order (e.g., `'created_at:DESC'`).
`page`	`number`	The page number for pagination.
`pageSize`	`number`	The number of items per page. Defaults to `20`.

Name	Type	Description
`at`	`string`	When to cancel. Can be `now`, `current_period_end`, or `custom`.
`time`	`number` or `string`	Required if `at` is `custom`. The Unix timestamp when the cancellation should take effect.
`refund`	`string`	Specifies refund behavior. Can be `none`, `proration`, or `last`.
`reason`	`string`	Reason for cancellation (e.g., `cancellation_requested`, `payment_failed`).
`feedback`	`string`	Customer feedback for the cancellation.
`comment`	`string`	An internal comment about the cancellation.

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

Subscriptions

The Subscription Object#

Retrieve a Subscription#

Update a Subscription#

List Subscriptions#

Cancel a Subscription#

Pause a Subscription#

Resume a Subscription#

Recover a Subscription#

Checkout Sessions

Subscription Items

Name	Type	Description
`id`	`string`	The unique identifier of the subscription to update.
`data`	`object`	An object containing the fields to update.