Create a subscription

Creates a subscription.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

Subscription payload

TypeScript Definitions

Use the request body type in TypeScript.

plan_id?|

Plan ID. When set, subscription is built from the plan's items.

product_id?|

Product ID (legacy). Use plan_id or items for new subscriptions.

collection_method*string

Payment collection method for invoices generated by the subscription.

Value in"manual" | "automatic"

proration_mode?string

Proration mode for the subscription.

Value in"none" | "invoice_immediately" | "invoice_later"

payment_method_id?|

Payment method ID associated with the subscription. Required if collection_method is automatic.

billing_cycle_type?string

Billing cycle type of the subscription.

Value in"anniversary" | "calendar"

items?array<>

Modify product quantities for the subscription plans.

account_id*string

Billingrails account ID associated with the subscription.

start_at?string

Start date of the subscription.

Formatdate-time

start_billing_at?string

First billing date of the subscription.

Formatdate-time

trial_period_days?|

Trial period of the subscription in days. Overrides the plan's trial period if set.

Response Body

`application/json`

curl -X POST "https://api.sandbox.billingrails.com/v1/subscriptions" \  -H "Content-Type: application/json" \  -d '{    "account_id": "acc_IhMUl3rrZ3",    "plan_id": "pln_IhMUl3rrZ3",    "currency": "USD",    "billing_cycle_type": "anniversary",    "collection_method": "automatic",    "payment_method_id": "pme_IhMUl3rrZ3"  }'

{
  "subscription": {
    "object": "subscription",
    "id": "sub_IhMUl3rrZ3",
    "status": "active",
    "account_id": "acc_IhMUl3rrZ3",
    "plan_id": "pln_IhMUl3rrZ3",
    "payment_method_id": "pme_IhMUl3rrZ3",
    "currency": "USD",
    "billing_cycle_type": "anniversary",
    "collection_method": "automatic",
    "current_period_start": "2025-02-14T17:33:40.843Z",
    "current_period_end": "2025-03-14T17:33:40.843Z",
    "first_billing_at": "2025-02-28T17:33:40.843Z",
    "previous_billing_at": "2025-02-14T17:33:40.843Z",
    "billed_through": "2025-03-14T17:33:40.843Z",
    "next_billing_at": "2025-03-14T17:33:40.843Z",
    "started_at": "2025-02-14T17:33:40.843Z",
    "trial_period_start": null,
    "trial_period_end": null,
    "created_at": "2025-02-14T17:33:40.843Z",
    "items": [
      {
        "product_id": "prd_IhMUl3rrZ3",
        "price_id": "prc_IhMUl3rrZ3",
        "quantity": 1
      }
    ]
  },
  "meta": {
    "request_id": "req_IhMUl3rrZ3"
  }
}

Authorization

Request Body

Response Body

201application/json

`application/json`