Subscriptions

Subscriptions are used to manage recurring payment plans for customers. The Subscriptions API allows you to create, retrieve, update, cancel, and manage the lifecycle of these recurring billing arrangements.

For managing the individual items within a subscription, see the Subscription Items API.

Retrieve a Subscription#

Fetches the details of an existing subscription by its unique identifier.

Parameters

Name	Type	Description
id	string	The ID of the subscription to retrieve.

Returns

Returns a subscription object if a valid ID was provided. The TSubscriptionExpanded object includes the following properties:

Name	Type	Description
id	string	Unique identifier for the subscription.
status	string	The status of the subscription (e.g., active, trialing, past_due, canceled).
customer_id	string	The ID of the customer associated with this subscription.
currency_id	string	The ID of the currency used for this 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.
items	TSubscriptionItem[]	An array of subscription items associated with this subscription.
customer	TCustomer	The expanded customer object.
paymentCurrency	TPaymentCurrency	The expanded payment currency object.
paymentMethod	TPaymentMethod	The expanded payment method object.
metadata	object	A set of key-value pairs that you can attach to an object.

Example

async function getSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.retrieve(subscriptionId);
    console.log('Subscription retrieved:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error retrieving subscription:', error.message);
  }
}

// Example usage:
getProductDetails('sub_xxxxxxxxxxxxxx');

Example Response

{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "active",
  "customer_id": "cus_xxxxxxxxxxxxxx",
  "currency_id": "curr_xxxxxxxxxxxxxx",
  "current_period_start": 1672531200,
  "current_period_end": 1675209600,
  "items": [
    {
      "id": "si_xxxxxxxxxxxxxx",
      "price_id": "price_xxxxxxxxxxxxxx",
      "quantity": 1
    }
  ],
  "customer": { /* ... customer details ... */ },
  "paymentCurrency": { /* ... currency details ... */ },
  "paymentMethod": { /* ... method details ... */ },
  "metadata": {}
}

Update a Subscription#

Updates an existing subscription by setting the values of the parameters passed.

Parameters

Name	Type	Description
id	string	The ID of the subscription to update.
data	object	An object containing the fields to update. See details below.

Data Object Properties

Name	Type	Description
description	string	An optional description for the subscription.
metadata	object	A set of key-value pairs to store with the subscription.
payment_behavior	string	Determines how to handle payments. Can be allow_incomplete, error_if_incomplete, or pending_if_incomplete.
proration_behavior	string	Determines how to handle prorations. Can be always_invoice, create_prorations, or none.
trial_end	number | string	Unix timestamp indicating the end of the trial period. Can also be 'now'.
items	SubscriptionUpdateItem[]	An array of items to update on the subscription. See details below.

SubscriptionUpdateItem Object Properties

Name	Type	Description
id	string	The ID of an existing subscription item to update or delete.
price_id	string	The ID of the price for a new subscription item.
quantity	number	The quantity for the subscription item.
deleted	boolean	Set to true to delete this subscription item.
clear_usage	boolean	For metered billing, indicates whether to clear usage on deletion.

Returns

Returns the updated subscription object.

Example

async function updateSubscriptionMetadata(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.update(subscriptionId, {
      metadata: {
        order_id: 'order_12345'
      }
    });
    console.log('Subscription updated:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error updating subscription:', error.message);
  }
}

// Example usage:
updateSubscriptionMetadata('sub_xxxxxxxxxxxxxx');

Example Response

{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "active",
  "metadata": {
    "order_id": "order_12345"
  }
  // ... other subscription properties
}

List Subscriptions#

Returns a paginated list of subscriptions. You can filter the list based on various criteria.

Parameters

Name	Type	Description
status	string	Filter subscriptions by status (e.g., 'active', 'trialing'). Comma-separated for multiple values.
customer_id	string	Filter subscriptions by a specific customer ID.
customer_did	string	Filter subscriptions by a specific customer DID.
metadata.{key}	string	Filter by custom metadata fields.
order	string | string[]	Sort order (e.g., 'created_at:DESC').
activeFirst	boolean	If true, active and trialing subscriptions are listed first.
page	number	The page number for pagination (default: 1).
pageSize	number	The number of items per page (default: 20).

Returns

Returns a paginated list of subscription objects.

Name	Type	Description
list	TSubscriptionExpanded[]	An array of subscription objects for the current page.
count	number	The total number of subscriptions matching the query.
paging	object	An object containing pagination details (page, pageSize).

Example

async function listActiveSubscriptions() {
  try {
    const response = await payment.subscriptions.list({
      status: 'active',
      pageSize: 10
    });
    console.log(`Found ${response.count} active subscriptions.`);
    console.log('First page:', response.list);
    return response;
  } catch (error) {
    console.error('Error listing subscriptions:', error.message);
  }
}

// Example usage:
listActiveSubscriptions();

Example Response

{
  "count": 50,
  "list": [
    {
      "id": "sub_xxxxxxxxxxxxxx",
      "status": "active"
      // ... other subscription properties
    }
    // ... more subscriptions
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}

Search Subscriptions#

Performs a search for subscriptions based on a query string.

Parameters

Name	Type	Description
query	string	The search string to match against subscription fields.
page	number	The page number for pagination (default: 1).
pageSize	number	The number of items per page (default: 20).

Returns

Returns a paginated list of subscription objects matching the search query.

Example

async function searchForSubscription(query) {
  try {
    const response = await payment.subscriptions.search({ query });
    console.log(`Search results for "${query}":`, response.list);
    return response;
  } catch (error) {
    console.error('Error searching subscriptions:', error.message);
  }
}

// Example usage:
searchForSubscription('some_customer_did');

Cancel a Subscription#

Cancels a customer's subscription. The subscription can be canceled immediately or at the end of the current billing period.

Parameters

Name	Type	Description
id	string	The ID of the subscription to cancel.
body	object	An object containing cancellation details.

Body Object Properties

Name	Type	Description
at	string	When to cancel. Can be 'now', 'current_period_end', or 'custom'. Default is 'current_period_end'.
time	number | string	Required if at is 'custom'. A future Unix timestamp for cancellation.
refund	string	Specifies if a refund should be issued. Can be 'none', 'proration', or 'last'.
feedback	string	Customer feedback for the cancellation.
comment	string	Internal comment about the cancellation.
reason	string	The reason for cancellation (e.g., 'cancellation_requested').

Returns

Returns the updated subscription object with cancellation details.

Example

async function cancelSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.cancel(subscriptionId, {
      at: 'current_period_end',
      reason: 'cancellation_requested'
    });
    console.log('Subscription scheduled for cancellation:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error canceling subscription:', error.message);
  }
}

// Example usage:
cancelSubscription('sub_xxxxxxxxxxxxxx');

Recover a Subscription#

Reactivates a subscription that has been scheduled for cancellation but has not yet been canceled.

Parameters

Name	Type	Description
id	string	The ID of the subscription to recover.

Returns

Returns the updated, active subscription object.

Example

async function recoverSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.recover(subscriptionId);
    console.log('Subscription recovered:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error recovering subscription:', error.message);
  }
}

// Example usage:
recoverSubscription('sub_xxxxxxxxxxxxxx');

Pause a Subscription#

Pauses payment collection for a subscription.

Parameters

Name	Type	Description
id	string	The ID of the subscription to pause.
body	object	An object containing pause details.

Body Object Properties

Name	Type	Description
behavior	string	The behavior of invoices created while paused. Can be 'keep_as_draft', 'mark_uncollectible', or 'void'.
resumes_at	number	A Unix timestamp for when the subscription should automatically resume.

Returns

Returns the updated subscription object with a paused status.

Example

async function pauseSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.pause(subscriptionId, {
      behavior: 'keep_as_draft'
    });
    console.log('Subscription paused:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error pausing subscription:', error.message);
  }
}

// Example usage:
pauseSubscription('sub_xxxxxxxxxxxxxx');

Resume a Subscription#

Resumes payment collection for a paused subscription.

Parameters

Name	Type	Description
id	string	The ID of the subscription to resume.

Returns

Returns the updated, active subscription object.

Example

async function resumeSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.resume(subscriptionId);
    console.log('Subscription resumed:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error resuming subscription:', error.message);
  }
}

// Example usage:
resumeSubscription('sub_xxxxxxxxxxxxxx');

Delete a Subscription#

Permanently deletes a subscription and all its related data. This action is irreversible and should only be used in non-production environments.

Parameters

Name	Type	Description
id	string	The ID of the subscription to delete.

Returns

Returns the deleted subscription object.

Example

async function deleteSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.del(subscriptionId);
    console.log('Subscription deleted:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error deleting subscription:', error.message);
  }
}

// Example usage:
deleteSubscription('sub_xxxxxxxxxxxxxx');

List Overdue Invoices#

Retrieves a list of overdue (uncollectible) invoices for a specific subscription, along with a summary of the amounts due.

Parameters

Name	Type	Description
id	string	The ID of the subscription.

Returns

Returns an object containing the subscription, a list of overdue invoices, and a summary of the total amounts owed per currency.

Name	Type	Description
subscription	TSubscription	The subscription object.
invoices	TInvoice[]	An array of overdue invoice objects.
summary	object	An object summarizing the total overdue amount for each currency.

Example

async function getOverdueInvoices(subscriptionId) {
  try {
    const result = await payment.subscriptions.overdueInvoices(subscriptionId);
    console.log('Overdue Invoices Summary:', result.summary);
    console.log('Invoices:', result.invoices);
    return result;
  } catch (error) {
    console.error('Error fetching overdue invoices:', error.message);
  }
}

// Example usage:
getOverdueInvoices('sub_xxxxxxxxxxxxxx');

Return Stake#

Initiates the process of returning staked funds associated with a canceled subscription that used an ArcBlock payment method.

Parameters

Name	Type	Description
id	string	The ID of the canceled subscription.

Returns

Returns an object indicating the success of scheduling the stake return job.

Name	Type	Description
success	boolean	true if the stake return job was successfully scheduled.
subscriptionId	string	The ID of the subscription for which the stake is being returned.

Example

async function returnSubscriptionStake(subscriptionId) {
  try {
    const result = await payment.subscriptions.returnStake(subscriptionId);
    console.log('Stake return initiated:', result);
    return result;
  } catch (error) {
    console.error('Error returning stake:', error.message);
  }
}

// Example usage:
returnSubscriptionStake('sub_xxxxxxxxxxxxxx');