SubscriptionCreateRequest

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.

    • Subscription item referencing an existing price from your product catalog.

      Currency Handling:

      • currency is optional at item level
      • Falls back to the subscription-level currency if not provided
      • At least one of item.currency or subscription.currency must be set
      • price
        Type: string
        required

        Price ID from your product catalog (ULID format).

      • recurring
        Type: object · RecurringConfig
        required

        Recurring billing configuration.

      • currency
        Type: string
        min length:  
        3
        max length:  
        3

        Three-letter ISO currency code (e.g. usd). Optional — falls back to subscription.currency if not provided.

      • quantity
        Type: integer
        min:  
        1

        Quantity of the subscription item.

      • unit_amount
        Type: number | null
        min:  
        0

        Unit amount override in cents. Falls back to the catalog price if omitted.

  • 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 | null · BillingCycleAnchorConfig

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

    • day_of_month
      Type: integer
      min:  
      1
      max:  
      31
      required

      Day of month for billing (1–31).

    • hour
      Type: integer | null
      min:  
      0
      max:  
      23

      Hour of day for billing in UTC (0–23).

    • minute
      Type: integer | null
      min:  
      0
      max:  
      59

      Minute of hour for billing (0–59).

    • month
      Type: integer | null
      min:  
      1
      max:  
      12

      Month of year for billing (1–12).

    • second
      Type: integer | null
      min:  
      0
      max:  
      59

      Second of minute for billing (0–59).

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

    • propertyName
      Type: anything
  • on_behalf_of
    Type: string

    Account ID for connected account scenarios.

  • trial_end
    Type: string | nullFormat: date-time

    End date of the trial period (ISO 8601 datetime). Mutually exclusive with trial_period_days; provide exactly one.

  • trial_period_days
    Type: integer
    min:  
    1
    max:  
    730

    Number of days for the trial period. Convenience alternative to trial_end — resolved to trial_end = now + trial_period_days at creation time. Mutually exclusive with trial_end.

  • trial_settings
    Type: object · TrialSettings

    Controls what happens when a trial period ends.

    • end_behavior
      Type: object

      Behavior when the trial ends.