Create a Subscription

​

Creates a new subscription for a customer. The customer must exist and have at least one payment method configured.

Pricing Options:

  1. Catalog Price: Reference an existing price from your catalog, using price param.
  2. Inline Pricing: Specify custom pricing directly using price_data — the product must exist.

Trial Periods: Provide exactly one of trial_end (ISO 8601 datetime) or trial_period_days (integer 1–730). When a trial is set, the subscription starts with status: TRIALING and the initial charge is skipped. The first charge fires when the trial ends.

collection_method: When set to charge_automatically (default), the first invoice is finalized and charged as part of the request.

Body
required
application/json

Request body for creating a new subscription.

Currency Validation:

  • currency is required at the subscription level
  • When using price_data: currency inside price_data must match the subscription currency
  • currency
    Type: string
    min length:  
    3
    max length:  
    3
    required

    Three-letter ISO currency code. Required at subscription level.

  • customer
    Type: string
    required

    ID of the customer to subscribe.

  • items
    Type: array 1…20
    required

    Subscription items. All recurring items must share the same billing interval. Items without recurring are one-time charges captured at creation and excluded from all future billing cycles.

  • billing_cycle_anchor
    Type: string | nullFormat: date-time

    Defines the billing cycle anchor date (ISO 8601). Mutually exclusive with billing_cycle_anchor_config.

  • billing_cycle_anchor_config
    Type: object · BillingCycleAnchorConfig

    Advanced billing cycle configuration. Allows precise control over when billing cycles occur. All fields are optional integers with specific ranges.

  • cancel_at
    Type: string | nullFormat: date-time

    Schedule cancellation for a specific date (ISO 8601). Cannot be used with cancel_at_period_end=true.

  • cancel_at_period_end
    Type: boolean

    If true, cancel at the end of the current billing period instead of immediately.

  • collection_method
    Type: stringenum

    How to collect payment from the customer:

    • charge_automatically — charge the default payment method automatically (default)
    • send_invoice — (coming soon) send an invoice and require manual payment
    values
    • charge_automatically
    • send_invoice
  • days_until_due
    Type: integer
    min:  
    1

    Number of days until the invoice is due. Required when collection_method=send_invoice.

  • default_payment_method
    Type: string

    ID of the payment method to use for this subscription.

  • livemode
    Type: boolean

    Whether this subscription is in live mode or test mode.

  • metadata
    Type: object

    Set of key-value pairs for storing additional information about the subscription.

Request body for creating a new subscription.

Currency Validation:

  • currency is required at the subscription level
  • When using price_data: currency inside price_data must match the subscription currency
Responses
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/v1/subscriptions
curl https://api.paypercut.io/v1/subscriptions \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "customer": "01KJQ34MWYH0TES77RDXA8T8TT",
  "currency": "usd",
  "default_payment_method": "pm_01HD7M6DRKZ4Q4QEVWJB0RC1S6",
  "items": [
    {
      "price": "01XXXXXXXXXXXXXXXXXXXXXXX",
      "unit_amount": 2999,
      "currency": "usd",
      "recurring": {
        "interval": "monthly",
        "interval_count": 1,
        "usage_type": "licensed"
      }
    }
  ],
  "metadata": {
    "plan": "premium"
  }
}'

{
  "id": "01HD7M6DRKZ4Q4QEVWJB0RC1S6",
  "customer": "01KJQ34MWYH0TES77RDXA8T8TT",
  "status": "ACTIVE",
  "start_date": "2026-01-01T00:00:00Z",
  "next_billing_date": "2026-02-01T00:00:00Z",
  "current_period_start": "2026-01-01T00:00:00Z",
  "current_period_end": "2026-02-01T00:00:00Z",
  "cancel_at_period_end": false,
  "cancel_at": null,
  "canceled_at": null,
  "paused_at": null,
  "trial_start": null,
  "trial_end": null,
  "trial_settings": null,
  "billing_cycle_anchor": "2026-01-01T00:00:00Z",
  "billing_cycle_anchor_config": null,
  "collection_method": "charge_automatically",
  "days_until_due": null,
  "default_payment_method": "pm_01HD7M6DRKZ4Q4QEVWJB0RC1S6",
  "currency": "USD",
  "on_behalf_of": null,
  "livemode": false,
  "ended_at": null,
  "cancellation_details": null,
  "billing_thresholds": null,
  "pending_setup_intent": null,
  "items": [
    {
      "id": "si_01HD7M6DRKZ4Q4QEVWJB0RC1S6",
      "price": "01XXXXXXXXXXXXXXXXXXXXXXX",
      "product": "01XXXXXXXXXXXXXXXXXXXXXXX",
      "quantity": 1,
      "billing_interval": "monthly",
      "unit_amount": 2999,
      "currency": "USD",
      "recurring": {
        "interval": "monthly",
        "interval_count": 1,
        "usage_type": "licensed"
      },
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "metadata": {
    "plan": "premium"
  },
  "created": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Subscription created successfully.