SubscriptionUpdateRequest

Request body for updating an existing subscription. All fields are optional — only provided fields are changed.

  • billing_cycle_anchor
    Type: string | nullFormat: date-time

    New billing cycle anchor date (ISO 8601).

  • billing_cycle_anchor_config
    Type: object | null

    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

    New scheduled cancellation date (ISO 8601).

  • cancel_at_period_end
    Type: boolean

    If true, the subscription remains active until the end of the current billing period, then cancels. If false, re-activates a subscription that was previously set to cancel.

  • cancellation_details
    Type: object · CancellationDetails

    Details about why this subscription was cancelled.

    • comment
      Type: string | null
      max length:  
      5000

      Free-form text comment explaining the cancellation reason.

    • feedback
      Type: string | nullenum

      Predefined cancellation reason category provided by the customer.

      values
      • customer_service
      • low_quality
      • missing_features
      • other
      • switched_service
      • too_complex
      • too_expensive
      • unused
  • collection_method
    Type: stringenum

    New payment collection method. send_invoice is (coming soon).

    values
    • charge_automatically
    • send_invoice
  • days_until_due
    Type: integer
    min:  
    1

    New number of days until invoice is due (for send_invoice collection method).

  • default_payment_method
    Type: string

    ID of the new default payment method.

  • items
    Type: array 1…20

    Replace all subscription items with this new set.

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

  • metadata
    Type: object

    Updated metadata key-value pairs.

    • propertyName
      Type: anything
  • on_behalf_of
    Type: string

    New connected account ID.

  • trial_end

    New trial end date (ISO 8601 datetime), or "now" to end the trial immediately. When set to "now", the billing schedule is rebuilt and the first charge fires right away.

    • enum
      const:  
      now

      End the trial immediately.

      values
      • now
  • trial_settings
    Type: object

    Controls what happens when a trial period ends.

    • end_behavior
      Type: object

      Behavior when the trial ends.