Skip to main content
Version: v2alpha1

Update subscriptions details using the API

Steps​

1. Get subscription details​

With the subscription id, you can get the check the subscription details to modify by calling GET /subscriptions/{subscription_id}.

Response​

200 OK
{
  "id": "sub_4ehg1mkv3mvt3256vcn8dspb4h",
  "name": "Monthly SAAS subscription",
  "version": "20240702153523123",
  "invoice_details": {
    [...]
  },
  [...]
}

2. Update subscription details​

You can use a partial update of the subscription defining only one or several of the top-level fields:

  • name: to rename the subscription.
  • ends_at: to cancel a subscription at a defined timestamp. See an easier way of cancelling a subscription.
  • invoice_details]: the details of the invoice must be updated as a block.

The effective_at field is used to perform the change in advance so the previous version of the subscription is used until that date.

The invoice_issued webhook and the subscription block in the invoice details endpoint of the invoices issued as part of a subscription contain a reference to the version of the subscription applied.

Once the details of the subscription are modified, you can update the subscription by calling the PATCH /subscriptions/{subscription_id} endpoint.

In this scenario, the subscription will be renamed.

Request​

PATCH /subscriptions/{subscription_id}
{
  "type": "custom",
  "name": "Supply delivery monthly fee"
}

Response​

200 OK
{
  "id": "sub_4ehg1mkv3mvt3256vcn8dspb4h",
  "effective_at": "2025-05-01T00:00:00.000+02:00"
}