BiasDocs

Subscriptions

A subscription bills a customer for one or more recurring prices on the same billing period. Each period produces an invoice that Bias charges to the saved card or bank account, or emails to the customer. The subscriptions guide covers renewals and failed payments, and plan changes covers proration.

The Subscription object

Name
object
Type
"subscription",
Description
The object's type.
Name
id
Type
string,
Description
Unique identifier for the object.
Name
live
Type
boolean,
Description
true if the object is live, or false if it's in a sandbox.
Name
created_at
Type
integer,
Description
When the object was created, in milliseconds since the Unix epoch.
Name
billing_cycle_anchor_at
Type
integer,
Description
When billing periods are counted from, as a Unix timestamp in milliseconds. Renewals fall on the anchor's day and time in UTC.
Name
cancel_at
Type
integer or null,
Description
When the subscription is scheduled to be canceled, as a Unix timestamp in milliseconds. Null once it's canceled.
Name
cancel_at_period_end
Type
boolean,
Description
Whether the subscription cancels at the end of its current period.
Name
canceled_at
Type
integer or null,
Description
When the subscription was canceled or scheduled to be canceled, as a Unix timestamp in milliseconds.
Name
cancellation_details
Type
object,
Description
Why the subscription was canceled or is scheduled to be canceled.
Properties
Name
collection_method
Type
enum,
Description
How the invoice is paid.
Properties
Name
customer
Type
string or Customer,
Description
Expandable. The customer who is subscribed.
Name
days_until_due
Type
integer or null,
Description
For send_invoice subscriptions, the number of days the customer has to pay each invoice.
Name
default_payment_method
Type
string or null,
Description
The saved payment method charged for renewals. When null, the customer's default_payment_method is charged.
Name
default_taxes
Type
array of objects,
Description
The taxes applied to each invoice.
Properties
Name
ended_at
Type
integer or null,
Description
When a canceled subscription ended, as a Unix timestamp in milliseconds.
Name
incomplete_expires_at
Type
integer or null,
Description
For an incomplete subscription, when it's canceled if its first invoice still isn't paid, as a Unix timestamp in milliseconds.
Name
items
Type
array of object,
Description
The prices the subscription bills each period.
Properties
Name
latest_invoice
Type
string or Invoice or null,
Description
Expandable. The most recent invoice for this subscription.
Name
metadata
Type
object,
Description
Your own key-value data on the object.
Name
next_renewal_at
Type
integer or null,
Description
When the subscription next renews, as a Unix timestamp in milliseconds. Null when it won't renew.
Name
payment_retries_end_at
Type
integer or null,
Description
For a past_due subscription, when payment retries stop, as a Unix timestamp in milliseconds.
Name
pending_change
Type
object or null,
Properties
Name
resumes_at
Type
integer or null,
Description
When a paused subscription resumes on its own, as a Unix timestamp in milliseconds. Null for a pause with no end.
Name
shipping_cost
Type
object or null,
Description
The shipping charged each period.
Properties
Name
shipping_details
Type
object or null,
Description
Where each period's order is shipped.
Properties
Name
status
Type
enum,
Description
The status of the subscription.
Properties
Name
trial_end_at
Type
integer or null,
Description
When the trial ends and the first paid period starts, as a Unix timestamp in milliseconds.
Name
trial_start_at
Type
integer or null,
Description
When the trial started, as a Unix timestamp in milliseconds.
Name
updated_at
Type
integer,
Description
When the object was last updated, in milliseconds since the Unix epoch.

The Subscription object

{
  "object": "subscription",
  "live": false,
  "id": "sub_nBAYX0s957u697jpsclt34",
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "status": "active",
  "items": [
    {
      "object": "subscription_item",
      "id": "si_sjms21TD0r7zmZJJA9rji7",
      "created_at": 1750000000000,
      "subscription": "sub_nBAYX0s957u697jpsclt34",
      "price": {
        "object": "price",
        "id": "price_dz1NVvl5CSogERkeA9Ng67",
        "live": false,
        "created_at": 1750000000000,
        "updated_at": 1750000000000,
        "deleted": false,
        "product": "prod_KDCnId9DMZSOA9MSaut4Q",
        "active": true,
        "name": "Monthly",
        "amount": 5000,
        "type": "recurring",
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "metadata": {}
      },
      "quantity": 1,
      "current_period": {
        "start": 1750000000000,
        "end": 1752592000000
      },
      "metadata": {}
    }
  ],
  "default_payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
  "collection_method": "charge_automatically",
  "days_until_due": null,
  "default_taxes": [],
  "billing_cycle_anchor_at": 1750000000000,
  "next_renewal_at": 1752592000000,
  "trial_start_at": null,
  "trial_end_at": null,
  "cancel_at": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "ended_at": null,
  "cancellation_details": {
    "reason": null,
    "feedback": null,
    "comment": null
  },
  "incomplete_expires_at": null,
  "payment_retries_end_at": null,
  "resumes_at": null,
  "latest_invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
  "shipping_details": null,
  "shipping_cost": null,
  "pending_change": null,
  "metadata": {}
}

The SubscriptionItem object

A subscription’s items are the prices it bills each period. They’re changed by updating the subscription.

Name
object
Type
"subscription_item",
Description
The object's type.
Name
id
Type
string,
Description
Unique identifier for the object.
Name
created_at
Type
integer,
Description
When the object was created, in milliseconds since the Unix epoch.
Name
current_period
Type
object,
Description
The item's current billing period.
Properties
Name
metadata
Type
object,
Description
Your own key-value data on the object.
Name
price
Type
Price,
Properties
Name
quantity
Type
integer, at least 1,
Description
The quantity billed.
Name
subscription
Type
string,
Description
The subscription this item belongs to.

The SubscriptionItem object

{
  "object": "subscription_item",
  "id": "si_sjms21TD0r7zmZJJA9rji7",
  "created_at": 1750000000000,
  "subscription": "sub_nBAYX0s957u697jpsclt34",
  "price": {
    "object": "price",
    "id": "price_dz1NVvl5CSogERkeA9Ng67",
    "live": false,
    "created_at": 1750000000000,
    "updated_at": 1750000000000,
    "deleted": false,
    "product": "prod_KDCnId9DMZSOA9MSaut4Q",
    "active": true,
    "name": "Monthly",
    "amount": 5000,
    "type": "recurring",
    "recurring": {
      "interval": "month",
      "interval_count": 1
    },
    "metadata": {}
  },
  "quantity": 1,
  "current_period": {
    "start": 1750000000000,
    "end": 1752592000000
  },
  "metadata": {}
}

Create a subscription

A new subscription bills the customer for its items every period. With a trial, it’s trialing and nothing is invoiced until the trial ends. Otherwise its first invoice is finalized in the request and charged with charge_automatically, or emailed with send_invoice.

If the first charge is declined, the subscription is incomplete until the invoice is paid, and is canceled at incomplete_expires_at. With payment_behavior: error_if_incomplete, the decline is returned as a payment_error instead.

Required parameters

Name
customer
Type
string,
Description
The customer to subscribe.
Name
items
Type
array of object,
Description
The prices to bill each period, all on the same interval.
Properties

Optional parameters

Name
expand
Type
object,
Properties
Name
default_payment_method
Type
string or null,
Description
The saved payment method charged for renewals. When null, the customer's default_payment_method is charged. An unattached payment method is attached to the customer.
Name
collection_method
Type
enum,
Description
How each invoice is paid. Defaults to charge_automatically.
Properties
Name
off_session
Type
boolean,
Description
Whether the customer is absent for the first charge. Defaults to false, which starts the recurring agreement renewals refer to. With true, the first invoice is charged like a renewal, which requires the customer's earlier agreement to be charged with this payment method.
Name
payment_behavior
Type
enum,
Description
What happens if the first invoice's charge is declined.
Properties
Name
days_until_due
Type
integer or null,
Description
For send_invoice subscriptions, the number of days the customer has to pay each invoice. Defaults to 30.
Name
default_taxes
Type
array of objects,
Description
The taxes applied to each invoice.
Properties
Name
trial_period_days
Type
integer, at least 1, at most 730,
Description
Starts the subscription with a free trial of this many days.
Name
trial_end_at
Type
integer,
Description
Starts the subscription with a free trial that ends at this Unix timestamp in milliseconds. Billing periods are counted from the trial end.
Name
cancel_at
Type
"period_end" or integer or null,
Description
Cancels the subscription at this Unix timestamp in milliseconds, or with period_end, at the end of the first period. Unused time isn't credited.
Name
shipping_details
Type
object or null,
Description
Where each period's order is shipped.
Properties
Name
shipping_rate
Type
string or null,
Description
The shipping rate to charge each period, at its amount when the subscription is created.
Name
metadata
Type
object or null,
Description
Your own key-value data on the object.

Returns

Returns the subscription object.

Create a subscription

const subscription = await bias.subscriptions.create({
  customer: "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  items: [
    {
      price: "price_dz1NVvl5CSogERkeA9Ng67",
      quantity: 1
    }
  ],
  default_payment_method: "pm_VQ9SaYquIZTG2l0uRsmUr4"
});

Response example

{
  "object": "subscription",
  "live": false,
  "id": "sub_nBAYX0s957u697jpsclt34",
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "status": "active",
  "items": [
    {
      "object": "subscription_item",
      "id": "si_sjms21TD0r7zmZJJA9rji7",
      "created_at": 1750000000000,
      "subscription": "sub_nBAYX0s957u697jpsclt34",
      "price": {
        "object": "price",
        "id": "price_dz1NVvl5CSogERkeA9Ng67",
        "live": false,
        "created_at": 1750000000000,
        "updated_at": 1750000000000,
        "deleted": false,
        "product": "prod_KDCnId9DMZSOA9MSaut4Q",
        "active": true,
        "name": "Monthly",
        "amount": 5000,
        "type": "recurring",
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "metadata": {}
      },
      "quantity": 1,
      "current_period": {
        "start": 1750000000000,
        "end": 1752592000000
      },
      "metadata": {}
    }
  ],
  "default_payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
  "collection_method": "charge_automatically",
  "days_until_due": null,
  "default_taxes": [],
  "billing_cycle_anchor_at": 1750000000000,
  "next_renewal_at": 1752592000000,
  "trial_start_at": null,
  "trial_end_at": null,
  "cancel_at": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "ended_at": null,
  "cancellation_details": {
    "reason": null,
    "feedback": null,
    "comment": null
  },
  "incomplete_expires_at": null,
  "payment_retries_end_at": null,
  "resumes_at": null,
  "latest_invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
  "shipping_details": null,
  "shipping_cost": null,
  "pending_change": null,
  "metadata": {}
}

Get a subscription

Retrieve a subscription by its ID.

Required parameters

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

Optional parameters

Name
expand
Type
object,
Properties

Returns

Returns the subscription object.

Retrieve a subscription

const subscription = await bias.subscriptions.get("id");

Response example

{
  "object": "subscription",
  "live": false,
  "id": "sub_nBAYX0s957u697jpsclt34",
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "status": "active",
  "items": [
    {
      "object": "subscription_item",
      "id": "si_sjms21TD0r7zmZJJA9rji7",
      "created_at": 1750000000000,
      "subscription": "sub_nBAYX0s957u697jpsclt34",
      "price": {
        "object": "price",
        "id": "price_dz1NVvl5CSogERkeA9Ng67",
        "live": false,
        "created_at": 1750000000000,
        "updated_at": 1750000000000,
        "deleted": false,
        "product": "prod_KDCnId9DMZSOA9MSaut4Q",
        "active": true,
        "name": "Monthly",
        "amount": 5000,
        "type": "recurring",
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "metadata": {}
      },
      "quantity": 1,
      "current_period": {
        "start": 1750000000000,
        "end": 1752592000000
      },
      "metadata": {}
    }
  ],
  "default_payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
  "collection_method": "charge_automatically",
  "days_until_due": null,
  "default_taxes": [],
  "billing_cycle_anchor_at": 1750000000000,
  "next_renewal_at": 1752592000000,
  "trial_start_at": null,
  "trial_end_at": null,
  "cancel_at": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "ended_at": null,
  "cancellation_details": {
    "reason": null,
    "feedback": null,
    "comment": null
  },
  "incomplete_expires_at": null,
  "payment_retries_end_at": null,
  "resumes_at": null,
  "latest_invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
  "shipping_details": null,
  "shipping_cost": null,
  "pending_change": null,
  "metadata": {}
}

Preview the upcoming invoice

The upcoming invoice shows what a customer will pay at their next renewal, or what a plan change would cost them before they confirm it.

These fields are specific to upcoming invoices and differ from the Invoice object:

  • period is the period the renewal bills for.
  • proration breaks down what a plan change would credit and charge immediately.
  • balance_applied is how much of the customer’s balance the renewal would use after any proration credit.
  • amount_billed is what the renewal would charge after balance_applied.

Required parameters

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

Optional parameters

Name
items
Type
array of object,
Description
Item changes to preview, in the same shape as an update.
Properties
Name
apply_at
Type
enum,
Description
When a change to items takes effect. Defaults to now.
Properties
Name
proration_behavior
Type
enum,
Description
How changing items mid-period is billed. Defaults to always_invoice.
Properties
Name
proration_at
Type
integer,
Description
When the change is prorated from, as a Unix timestamp in milliseconds. Defaults to now.

Returns

Returns the upcoming invoice, or a no_upcoming_invoice error if the subscription won’t renew, for example because it’s paused, canceled, or set to cancel before its next renewal.

Preview the upcoming invoice

const subscription = await bias.subscriptions.upcomingInvoice("id");

Response example

{
  "object": "upcoming_invoice",
  "live": false,
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "subscription": "sub_nBAYX0s957u697jpsclt34",
  "billing_reason": "subscription_cycle",
  "collection_method": "charge_automatically",
  "default_payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
  "days_until_due": null,
  "period": {
    "start": 1752592000000,
    "end": 1755270400000
  },
  "next_attempt_at": 1752595600000,
  "shipping_details": null,
  "default_taxes": [],
  "line_items": [
    {
      "type": "catalog",
      "quantity": 1,
      "name": null,
      "description": "Jul 15, 2025 – Aug 15, 2025",
      "unit_amount": 5000,
      "price": "price_dz1NVvl5CSogERkeA9Ng67",
      "product": "prod_KDCnId9DMZSOA9MSaut4Q",
      "taxes": [],
      "tax_amounts": [],
      "subtotal": 5000,
      "total": 5000,
      "period": {
        "start": 1752592000000,
        "end": 1755270400000
      },
      "subscription_item": "si_sjms21TD0r7zmZJJA9rji7"
    }
  ],
  "subtotal": 5000,
  "tax_total": 0,
  "total": 5000,
  "balance_applied": 0,
  "amount_billed": 5000,
  "proration": {
    "proration_at": 1751296000000,
    "credit_lines": [
      {
        "invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
        "line_item": "li_rbw8iroSXBkFMZ8bisSxK",
        "description": "Unused time on 1 × Starter after Jun 30, 2025",
        "period": {
          "start": 1751296000000,
          "end": 1752592000000
        },
        "subtotal": 1000,
        "tax_total": 0,
        "total": 1000
      }
    ],
    "charge_lines": [
      {
        "price": "price_dz1NVvl5CSogERkeA9Ng67",
        "quantity": 1,
        "description": "Remaining time on 1 × Pro from Jun 30, 2025",
        "period": {
          "start": 1751296000000,
          "end": 1752592000000
        },
        "subtotal": 2500,
        "tax_total": 0,
        "total": 2500
      }
    ],
    "credit_total": 1000,
    "charge_total": 2500,
    "balance_applied": 1000,
    "amount_billed": 1500
  }
}

Update a subscription

Updates change what a subscription bills and how: its items, payment method, collection method, taxes, shipping or scheduled cancellation. Item changes are prorated unless proration_behavior is none.

A change with a prorated charge applies once its invoice is paid, and is discarded if it isn’t paid within 15 minutes. With payment_behavior: error_if_incomplete, a decline is returned as a payment_error instead.

Setting a payment method on a subscription with an unpaid invoice charges that invoice right away.

Required parameters

Name
id
Type
string,

Optional parameters

Name
expand
Type
object,
Properties
Name
items
Type
array of object,
Description
Items to add, change or remove.
Properties
Name
apply_at
Type
enum,
Description
When a change to items takes effect. Defaults to now.
Properties
Name
proration_behavior
Type
enum,
Description
How changing items mid-period is billed. Defaults to always_invoice.
Properties
Name
proration_at
Type
integer,
Description
When the change is prorated from, as a Unix timestamp in milliseconds. Defaults to now. The proration_at from an upcoming invoice preview made in the last 30 minutes charges what the preview showed.
Name
payment_behavior
Type
enum,
Description
What happens if the charge for a change to items is declined.
Properties
Name
pending_change
Type
null,
Description
null cancels the scheduled change. Changing items also cancels or replaces it.
Name
default_payment_method
Type
string or null,
Description
The saved payment method charged for renewals. When null, the customer's default_payment_method is charged.
Name
collection_method
Type
enum,
Description
How future invoices are paid.
Properties
Name
days_until_due
Type
integer or null,
Description
For send_invoice subscriptions, the number of days the customer has to pay each invoice.
Name
default_taxes
Type
array of objects,
Description
The taxes applied to each invoice.
Properties
Name
trial_end_at
Type
"now" or integer,
Description
For a trialing subscription, when the trial ends, as a Unix timestamp in milliseconds. now ends the trial and starts the first paid period immediately.
Name
cancel_at
Type
"period_end" or integer or null,
Description
Cancels the subscription at this Unix timestamp in milliseconds, or with period_end, at the end of the current period. Unused time isn't credited. null removes a scheduled cancellation.
Name
cancellation_details
Type
object,
Description
The customer's reason for canceling.
Properties
Name
shipping_details
Type
object or null,
Description
Where each period's order is shipped.
Properties
Name
shipping_rate
Type
string or null,
Description
The shipping rate to charge from the next renewal, at its current amount. null stops charging shipping.
Name
metadata
Type
object or null,
Description
Your own key-value data on the object.

Returns

Returns the subscription object.

Update a subscription

const subscription = await bias.subscriptions.update("id");

Response example

{
  "object": "subscription",
  "live": false,
  "id": "sub_nBAYX0s957u697jpsclt34",
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "status": "active",
  "items": [
    {
      "object": "subscription_item",
      "id": "si_sjms21TD0r7zmZJJA9rji7",
      "created_at": 1750000000000,
      "subscription": "sub_nBAYX0s957u697jpsclt34",
      "price": {
        "object": "price",
        "id": "price_dz1NVvl5CSogERkeA9Ng67",
        "live": false,
        "created_at": 1750000000000,
        "updated_at": 1750000000000,
        "deleted": false,
        "product": "prod_KDCnId9DMZSOA9MSaut4Q",
        "active": true,
        "name": "Monthly",
        "amount": 5000,
        "type": "recurring",
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "metadata": {}
      },
      "quantity": 1,
      "current_period": {
        "start": 1750000000000,
        "end": 1752592000000
      },
      "metadata": {}
    }
  ],
  "default_payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
  "collection_method": "charge_automatically",
  "days_until_due": null,
  "default_taxes": [],
  "billing_cycle_anchor_at": 1750000000000,
  "next_renewal_at": 1752592000000,
  "trial_start_at": null,
  "trial_end_at": null,
  "cancel_at": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "ended_at": null,
  "cancellation_details": {
    "reason": null,
    "feedback": null,
    "comment": null
  },
  "incomplete_expires_at": null,
  "payment_retries_end_at": null,
  "resumes_at": null,
  "latest_invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
  "shipping_details": null,
  "shipping_cost": null,
  "pending_change": null,
  "metadata": {}
}

List all subscriptions

Retrieve a paginated list of subscriptions, most recently created first.

Optional parameters

Name
expand
Type
object,
Description
Related objects to expand in the response.
Properties
Name
ending_before
Type
string,
Description
The ID of the object to list before, for pagination.
Name
starting_after
Type
string,
Description
The ID of the object to list after, for pagination.
Name
limit
Type
integer, at least 1, at most 1000, default is 50
Description
The maximum number of objects to return, from 1 to 1000. Defaults to 50.
Name
filters
Type
object, object, or object,
Description
Filters for the list, combined with and and or.
Properties

Returns

Returns a list of subscription objects.

List all subscriptions

const subscription = await bias.subscriptions.list();

Response example

{
  "object": "list",
  "items": [
    {
      "object": "subscription",
      "live": false,
      "id": "sub_nBAYX0s957u697jpsclt34",
      "created_at": 1750000000000,
      "updated_at": 1750000000000,
      "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
      "status": "active",
      "items": [
        {
          "object": "subscription_item",
          "id": "si_sjms21TD0r7zmZJJA9rji7",
          "created_at": 1750000000000,
          "subscription": "sub_nBAYX0s957u697jpsclt34",
          "price": {
            "object": "price",
            "id": "price_dz1NVvl5CSogERkeA9Ng67",
            "live": false,
            "created_at": 1750000000000,
            "updated_at": 1750000000000,
            "deleted": false,
            "product": "prod_KDCnId9DMZSOA9MSaut4Q",
            "active": true,
            "name": "Monthly",
            "amount": 5000,
            "type": "recurring",
            "recurring": {
              "interval": "month",
              "interval_count": 1
            },
            "metadata": {}
          },
          "quantity": 1,
          "current_period": {
            "start": 1750000000000,
            "end": 1752592000000
          },
          "metadata": {}
        }
      ],
      "default_payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
      "collection_method": "charge_automatically",
      "days_until_due": null,
      "default_taxes": [],
      "billing_cycle_anchor_at": 1750000000000,
      "next_renewal_at": 1752592000000,
      "trial_start_at": null,
      "trial_end_at": null,
      "cancel_at": null,
      "cancel_at_period_end": false,
      "canceled_at": null,
      "ended_at": null,
      "cancellation_details": {
        "reason": null,
        "feedback": null,
        "comment": null
      },
      "incomplete_expires_at": null,
      "payment_retries_end_at": null,
      "resumes_at": null,
      "latest_invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
      "shipping_details": null,
      "shipping_cost": null,
      "pending_change": null,
      "metadata": {}
    }
  ],
  "has_more": true
}

Cancel a subscription

Canceling ends an active subscription immediately.

To schedule a cancelation, update with cancel_at instead.

With proration enabled, the unused value is credited to the customer’s balance or refunded.

Required parameters

Name
id
Type
string,

Optional parameters

Name
expand
Type
object,
Properties
Name
prorate
Type
boolean,
Description
Credits the unused time on the current period with a credit note. Defaults to false.
Name
unused_credit
Type
enum,
Description
What happens to the credit prorate issues for the unused time. keep (the default) adds it to the customer's balance, and refund refunds what's left of it to the period's payments.
Properties
Name
cancellation_details
Type
object,
Description
Why the customer canceled.
Properties

Returns

Returns the canceled subscription object.

Cancel a subscription

const subscription = await bias.subscriptions.cancel("id", {
  prorate: true,
  unused_credit: "refund"
});

Response example

{
  "object": "subscription",
  "live": false,
  "id": "sub_nBAYX0s957u697jpsclt34",
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "status": "active",
  "items": [
    {
      "object": "subscription_item",
      "id": "si_sjms21TD0r7zmZJJA9rji7",
      "created_at": 1750000000000,
      "subscription": "sub_nBAYX0s957u697jpsclt34",
      "price": {
        "object": "price",
        "id": "price_dz1NVvl5CSogERkeA9Ng67",
        "live": false,
        "created_at": 1750000000000,
        "updated_at": 1750000000000,
        "deleted": false,
        "product": "prod_KDCnId9DMZSOA9MSaut4Q",
        "active": true,
        "name": "Monthly",
        "amount": 5000,
        "type": "recurring",
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "metadata": {}
      },
      "quantity": 1,
      "current_period": {
        "start": 1750000000000,
        "end": 1752592000000
      },
      "metadata": {}
    }
  ],
  "default_payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
  "collection_method": "charge_automatically",
  "days_until_due": null,
  "default_taxes": [],
  "billing_cycle_anchor_at": 1750000000000,
  "next_renewal_at": 1752592000000,
  "trial_start_at": null,
  "trial_end_at": null,
  "cancel_at": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "ended_at": null,
  "cancellation_details": {
    "reason": null,
    "feedback": null,
    "comment": null
  },
  "incomplete_expires_at": null,
  "payment_retries_end_at": null,
  "resumes_at": null,
  "latest_invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
  "shipping_details": null,
  "shipping_cost": null,
  "pending_change": null,
  "metadata": {}
}

Pause a subscription

Pausing stops a subscription’s renewals until it’s resumed, or until resumes_at. A pause until the end of the next period skips one renewal.

Required parameters

Name
id
Type
string,

Optional parameters

Name
expand
Type
object,
Properties
Name
resumes_at
Type
integer or null,
Description
When the subscription resumes on its own, as a Unix timestamp in milliseconds. Without it, the subscription stays paused until it's resumed.

Returns

Returns the paused subscription object.

Pause a subscription

const subscription = await bias.subscriptions.pause("id", {
  resumes_at: 1752592000000
});

Response example

{
  "object": "subscription",
  "live": false,
  "id": "sub_nBAYX0s957u697jpsclt34",
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "status": "active",
  "items": [
    {
      "object": "subscription_item",
      "id": "si_sjms21TD0r7zmZJJA9rji7",
      "created_at": 1750000000000,
      "subscription": "sub_nBAYX0s957u697jpsclt34",
      "price": {
        "object": "price",
        "id": "price_dz1NVvl5CSogERkeA9Ng67",
        "live": false,
        "created_at": 1750000000000,
        "updated_at": 1750000000000,
        "deleted": false,
        "product": "prod_KDCnId9DMZSOA9MSaut4Q",
        "active": true,
        "name": "Monthly",
        "amount": 5000,
        "type": "recurring",
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "metadata": {}
      },
      "quantity": 1,
      "current_period": {
        "start": 1750000000000,
        "end": 1752592000000
      },
      "metadata": {}
    }
  ],
  "default_payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
  "collection_method": "charge_automatically",
  "days_until_due": null,
  "default_taxes": [],
  "billing_cycle_anchor_at": 1750000000000,
  "next_renewal_at": 1752592000000,
  "trial_start_at": null,
  "trial_end_at": null,
  "cancel_at": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "ended_at": null,
  "cancellation_details": {
    "reason": null,
    "feedback": null,
    "comment": null
  },
  "incomplete_expires_at": null,
  "payment_retries_end_at": null,
  "resumes_at": null,
  "latest_invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
  "shipping_details": null,
  "shipping_cost": null,
  "pending_change": null,
  "metadata": {}
}

Resume a subscription

Resuming restarts billing for a paused subscription. If the paid period hasn’t ended, billing continues on its schedule; otherwise a new period starts and is billed right away.

Required parameters

Name
id
Type
string,

Optional parameters

Name
expand
Type
object,
Properties

Returns

Returns the subscription object.

Resume a subscription

const subscription = await bias.subscriptions.resume("id");

Response example

{
  "object": "subscription",
  "live": false,
  "id": "sub_nBAYX0s957u697jpsclt34",
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "status": "active",
  "items": [
    {
      "object": "subscription_item",
      "id": "si_sjms21TD0r7zmZJJA9rji7",
      "created_at": 1750000000000,
      "subscription": "sub_nBAYX0s957u697jpsclt34",
      "price": {
        "object": "price",
        "id": "price_dz1NVvl5CSogERkeA9Ng67",
        "live": false,
        "created_at": 1750000000000,
        "updated_at": 1750000000000,
        "deleted": false,
        "product": "prod_KDCnId9DMZSOA9MSaut4Q",
        "active": true,
        "name": "Monthly",
        "amount": 5000,
        "type": "recurring",
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "metadata": {}
      },
      "quantity": 1,
      "current_period": {
        "start": 1750000000000,
        "end": 1752592000000
      },
      "metadata": {}
    }
  ],
  "default_payment_method": "pm_VQ9SaYquIZTG2l0uRsmUr4",
  "collection_method": "charge_automatically",
  "days_until_due": null,
  "default_taxes": [],
  "billing_cycle_anchor_at": 1750000000000,
  "next_renewal_at": 1752592000000,
  "trial_start_at": null,
  "trial_end_at": null,
  "cancel_at": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "ended_at": null,
  "cancellation_details": {
    "reason": null,
    "feedback": null,
    "comment": null
  },
  "incomplete_expires_at": null,
  "payment_retries_end_at": null,
  "resumes_at": null,
  "latest_invoice": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
  "shipping_details": null,
  "shipping_cost": null,
  "pending_change": null,
  "metadata": {}
}