Update a subscription

curl --request PATCH \
  --url https://api.bachs.io/v1/subscriptions/{subscription_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "product_id": "prod_premium",
  "proration_behavior": "invoice_now"
}
'

{
  "id": "sub_1a2b3c4d5e6f",
  "payment_method_id": "pm_7h8i9j0k",
  "status": "active",
  "collection_method": "charge_automatically",
  "currency": "USD",
  "amount": "10.00",
  "billing_cycle": {
    "interval": "month",
    "frequency": 1
  },
  "quantity": 1,
  "current_period_start": "2026-07-13T12:00:00Z",
  "current_period_end": "2026-08-13T12:00:00Z",
  "previously_billed_at": "2026-07-13T12:00:00Z",
  "next_billed_at": "2026-08-13T12:00:00Z",
  "trial_end": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "created_at": "2026-07-13T12:00:00Z",
  "product": {
    "id": "prod_abc123",
    "name": "Pro plan",
    "description": "Everything in Pro.",
    "status": "active",
    "billing_cycle": {
      "interval": "month",
      "frequency": 1
    },
    "trial_period": null,
    "created_at": "2026-07-01T09:00:00Z",
    "updated_at": "2026-07-01T09:00:00Z"
  },
  "items": [
    {
      "id": "si_11aa22bb",
      "status": "active",
      "quantity": 1,
      "recurring": true,
      "price_type": "fixed",
      "unit_amount": "10.00",
      "currency": "USD",
      "previously_billed_at": "2026-07-13T12:00:00Z",
      "next_billed_at": "2026-08-13T12:00:00Z",
      "price": {
        "id": "price_pro_usd",
        "product_id": "prod_abc123",
        "price_type": "fixed",
        "currency": "USD",
        "unit_amount": "10.00",
        "billing_cycle": {
          "interval": "month",
          "frequency": 1
        },
        "trial_period": null,
        "seat_tiers": null,
        "is_archived": false,
        "created_at": "2026-07-01T09:00:00Z",
        "updated_at": "2026-07-01T09:00:00Z"
      },
      "product": {
        "id": "prod_abc123",
        "name": "Pro plan",
        "status": "active",
        "billing_cycle": {
          "interval": "month",
          "frequency": 1
        },
        "trial_period": null,
        "created_at": "2026-07-01T09:00:00Z",
        "updated_at": "2026-07-01T09:00:00Z"
      },
      "created_at": "2026-07-13T12:00:00Z",
      "updated_at": "2026-07-13T12:00:00Z"
    }
  ],
  "customer": {
    "customer_id": "cust_xyz789",
    "email": "customer@example.com",
    "name": "Jane Doe",
    "phone_number": "+2348012345678",
    "metadata": {},
    "created_at": "2026-07-01T09:00:00Z",
    "updated_at": "2026-07-01T09:00:00Z"
  }
}

{
  "detail": "Invalid request parameters",
  "error_code": "VALIDATION_ERROR",
  "errors": [
    {
      "field": "amount",
      "message": "Amount must be a positive decimal string",
      "type": "value_error"
    }
  ]
}

{
  "detail": "Invalid API key",
  "error_code": "UNAUTHORIZED"
}

{
  "detail": "API key does not have permission for this operation",
  "error_code": "FORBIDDEN"
}

{
  "detail": "Resource not found",
  "error_code": "NOT_FOUND"
}

{
  "detail": "Rate limit exceeded. Please retry after a few seconds.",
  "error_code": "TOO_MANY_REQUESTS"
}

{
  "detail": "An unexpected error occurred. Please try again later.",
  "error_code": "INTERNAL_SERVER_ERROR"
}

PATCH

subscriptions

{subscription_id}

curl --request PATCH \
  --url https://api.bachs.io/v1/subscriptions/{subscription_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "product_id": "prod_premium",
  "proration_behavior": "invoice_now"
}
'

{
  "id": "sub_1a2b3c4d5e6f",
  "payment_method_id": "pm_7h8i9j0k",
  "status": "active",
  "collection_method": "charge_automatically",
  "currency": "USD",
  "amount": "10.00",
  "billing_cycle": {
    "interval": "month",
    "frequency": 1
  },
  "quantity": 1,
  "current_period_start": "2026-07-13T12:00:00Z",
  "current_period_end": "2026-08-13T12:00:00Z",
  "previously_billed_at": "2026-07-13T12:00:00Z",
  "next_billed_at": "2026-08-13T12:00:00Z",
  "trial_end": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "created_at": "2026-07-13T12:00:00Z",
  "product": {
    "id": "prod_abc123",
    "name": "Pro plan",
    "description": "Everything in Pro.",
    "status": "active",
    "billing_cycle": {
      "interval": "month",
      "frequency": 1
    },
    "trial_period": null,
    "created_at": "2026-07-01T09:00:00Z",
    "updated_at": "2026-07-01T09:00:00Z"
  },
  "items": [
    {
      "id": "si_11aa22bb",
      "status": "active",
      "quantity": 1,
      "recurring": true,
      "price_type": "fixed",
      "unit_amount": "10.00",
      "currency": "USD",
      "previously_billed_at": "2026-07-13T12:00:00Z",
      "next_billed_at": "2026-08-13T12:00:00Z",
      "price": {
        "id": "price_pro_usd",
        "product_id": "prod_abc123",
        "price_type": "fixed",
        "currency": "USD",
        "unit_amount": "10.00",
        "billing_cycle": {
          "interval": "month",
          "frequency": 1
        },
        "trial_period": null,
        "seat_tiers": null,
        "is_archived": false,
        "created_at": "2026-07-01T09:00:00Z",
        "updated_at": "2026-07-01T09:00:00Z"
      },
      "product": {
        "id": "prod_abc123",
        "name": "Pro plan",
        "status": "active",
        "billing_cycle": {
          "interval": "month",
          "frequency": 1
        },
        "trial_period": null,
        "created_at": "2026-07-01T09:00:00Z",
        "updated_at": "2026-07-01T09:00:00Z"
      },
      "created_at": "2026-07-13T12:00:00Z",
      "updated_at": "2026-07-13T12:00:00Z"
    }
  ],
  "customer": {
    "customer_id": "cust_xyz789",
    "email": "customer@example.com",
    "name": "Jane Doe",
    "phone_number": "+2348012345678",
    "metadata": {},
    "created_at": "2026-07-01T09:00:00Z",
    "updated_at": "2026-07-01T09:00:00Z"
  }
}

{
  "detail": "Invalid request parameters",
  "error_code": "VALIDATION_ERROR",
  "errors": [
    {
      "field": "amount",
      "message": "Amount must be a positive decimal string",
      "type": "value_error"
    }
  ]
}

{
  "detail": "Invalid API key",
  "error_code": "UNAUTHORIZED"
}

{
  "detail": "API key does not have permission for this operation",
  "error_code": "FORBIDDEN"
}

{
  "detail": "Resource not found",
  "error_code": "NOT_FOUND"
}

{
  "detail": "Rate limit exceeded. Please retry after a few seconds.",
  "error_code": "TOO_MANY_REQUESTS"
}

{
  "detail": "An unexpected error occurred. Please try again later.",
  "error_code": "INTERNAL_SERVER_ERROR"
}

Authorizations

Authorization

string

header

required

Bearer token authentication. Pass your API key as Authorization: Bearer sk_.... See Authentication for keys, scopes, and sandbox vs production.

Path Parameters

subscription_id

string

required

The subscription's public ID (sub_...).

Body

application/json

A single change to a subscription. Send exactly one intent per request: change the plan (product_id), move a trial (trial_end), change the payment method (payment_method_id), or update metadata (metadata). Combining intents returns 400.

product_id

string

Move the subscription to this product (plan). The price is resolved from the product for the subscription's currency.

Maximum string length: 64

Example:

"prod_xyz456"

trial_end

string<date-time>

Future = add/extend the trial; past-or-now = end it and bill now.

Example:

"2026-05-01T00:00:00Z"

payment_method_id

string

Point the subscription at a different saved card. If past_due/unpaid, retries immediately. Stands alone.

Maximum string length: 64

Example:

"pm_9f8e7d6c5b"

metadata

Merge key-value metadata into the subscription (up to 20 keys total). Sent keys are added or overwritten; a key sent with an empty-string value is removed; send an empty string ("") to clear all metadata. Stands alone: it cannot be combined with a plan, trial, or payment-method change.

Example:

{ "plan": "pro", "seat_count": "5" }

proration_behavior

enum<string>

How a plan change is settled, and only meaningful alongside product_id. invoice_now: the change is settled straight away on a new invoice, and this is the default when you omit the field. next_cycle: the proration is accrued and drains into the next cycle's invoice. none: the plan changes with no proration charged or credited.

Available options:

invoice_now,

next_cycle,

none

Example:

"invoice_now"

Response

The updated subscription

string

Unique identifier for the subscription.

Example:

"sub_1a2b3c4d5e6f"

customer

object

The customer billed on each renewal, expanded inline so you can show who is being charged without a second call.

Show child attributes

payment_method_id

string | null

The saved payment method billed on each renewal. null until a payment method is attached.

Example:

"pm_7h8i9j0k"

status

enum<string>

Status of the subscription. Set automatically by Bachs as payments succeed or fail. trialing: In a free trial. No payment has been collected yet. trial_end marks when billing begins. active: Active and paid. Bachs is billing this subscription automatically each cycle. past_due: A cycle payment failed. Bachs is retrying the payment while access continues. unpaid: Payment retries have been exhausted. Access should be restricted. canceled: Canceled and will not renew. This is a terminal state. paused: Temporarily suspended. Billing is halted until the subscription resumes.

Available options:

trialing,

active,

past_due,

unpaid,

canceled,

paused

Example:

"active"

collection_method

string

How renewals are collected. charge_automatically bills the saved card each cycle.

Example:

"charge_automatically"

currency

string

The currency the subscription is billed in, as an ISO 4217 code. Subscriptions are USD only today.

Example:

"USD"

amount

string

Recurring amount as a decimal string

Example:

"10.00"

billing_cycle

object

How often the subscription renews, as an interval unit and a frequency, for example month with a frequency of 1 for monthly billing.

Show child attributes

quantity

integer

Total billable quantity across the subscription's line items.

Example:

1

current_period_start

string<date-time>

Start of the period currently being billed for, in UTC.

Example:

"2026-04-01T00:00:00Z"

current_period_end

string<date-time>

End of the period currently being billed for, in UTC. The next charge lands at this time unless the subscription is canceled first.

Example:

"2026-05-01T00:00:00Z"

previously_billed_at

string<date-time> | null

Start of the period that was last billed

Example:

"2026-04-01T00:00:00Z"

next_billed_at

string<date-time> | null

Next scheduled charge date

Example:

"2026-05-01T00:00:00Z"

trial_end

string<date-time> | null

When the free trial ends and billing begins, in UTC. null if the subscription is not trialing.

Example:

"2026-04-15T00:00:00Z"

cancel_at_period_end

boolean

When true, the subscription stays active until current_period_end and is not renewed. When false, it renews normally.

Example:

false

canceled_at

string<date-time> | null

When the subscription was canceled, in UTC. null if it has not been canceled.

Example:

null

created_at

string<date-time>

When the subscription was created, in UTC.

Example:

"2026-03-01T12:00:00Z"

product

object | null

The catalog product this subscription bills for, or null when the subscription is not tied to a single product.

Show child attributes

items

object[]

The line items that make up the subscription. Each item ties a product and its price to a billed quantity.

Show child attributes

metadata

object

Your own key-value data attached to the subscription at creation, returned unchanged.

Example:

{ "plan": "pro", "seat_count": "5" }

General

Checkout Sessions

Connected Accounts

Products

Subscriptions

Customers

Customer sessions

Payments

Refunds

Disputes

Payouts

Payout Destinations

Balance

Virtual accounts

Your account

Media

Misc

Transfers

Persons

Platform Fees

Reference

Update a subscription

Authorizations

Path Parameters

Body

Response