v1

latestOpenAPI 3.0.32026-07-264469137.7 KB

Subscriptions

Retrieve a subscription

Retrieve a single subscription with its product, price, items, and billing dates.

get/v1/subscriptions/{subscription_id}

Path parameters

subscription_idstring required

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

Response

The subscription

idstring

Unique identifier for the subscription.

payment_method_idstring nullable

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

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.

collection_methodstring

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

currencystring

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

amountstring

Recurring amount as a decimal string

quantityinteger

Total billable quantity across the subscription's line items.

current_period_startstring date-time

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

current_period_endstring 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.

previously_billed_atstring date-time nullable

Start of the period that was last billed

next_billed_atstring date-time nullable

Next scheduled charge date

trial_endstring date-time nullable

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

cancel_at_period_endboolean

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

canceled_atstring date-time nullable

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

created_atstring date-time

When the subscription was created, in UTC.

metadataobject

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

Example response

{
  "id": "sub_1a2b3c4d5e6f",
  "customer": {
    "customer_id": "cust_xyz789",
    "email": "jane@example.com",
    "name": "Jane Doe",
    "phone_number": "+2348012345678",
    "metadata": {
      "plan": "pro"
    },
    "created_at": "2026-01-24T12:00:00.000Z",
    "updated_at": "2026-01-24T12:00:00.000Z"
  },
  "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-04-01T00:00:00Z",
  "current_period_end": "2026-05-01T00:00:00Z",
  "previously_billed_at": "2026-04-01T00:00:00Z",
  "next_billed_at": "2026-05-01T00:00:00Z",
  "trial_end": "2026-04-15T00:00:00Z",
  "created_at": "2026-03-01T12:00:00Z",
  "product": {
    "id": "prod_abc123",
    "name": "Pro plan",
    "description": "Everything in Basic, plus priority support.",
    "status": "active",
    "billing_cycle": {
      "interval": "month",
      "frequency": 1
    },
    "trial_period": {
      "interval": "day",
      "frequency": 14
    },
    "created_at": "2026-03-01T12:00:00Z",
    "updated_at": "2026-03-01T12: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-04-01T00:00:00Z",
      "next_billed_at": "2026-05-01T00: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": {
          "interval": "day",
          "frequency": 14
        },
        "created_at": "2026-03-01T12:00:00Z",
        "updated_at": "2026-03-01T12:00:00Z"
      },
      "product": {
        "id": "prod_abc123",
        "name": "Pro plan",
        "description": "Everything in Basic, plus priority support.",
        "status": "active",
        "billing_cycle": {
          "interval": "month",
          "frequency": 1
        },
        "trial_period": {
          "interval": "day",
          "frequency": 14
        },
        "created_at": "2026-03-01T12:00:00Z",
        "updated_at": "2026-03-01T12:00:00Z"
      },
      "created_at": "2026-03-01T12:00:00Z",
      "updated_at": "2026-04-01T00:00:00Z"
    }
  ],
  "metadata": {
    "plan": "pro",
    "seat_count": "5"
  }
}