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 · 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

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

  • metadata
    Type: object

    Updated metadata key-value pairs.

    • propertyName
      Type: anything
  • on_behalf_of
    Type: string

    New connected account ID.

  • trial_end
    • enum
      const:  
      now

      End the trial immediately.

      values
      • now
  • trial_settings
    Type: object · TrialSettings

    Controls what happens when a trial period ends.

    • end_behavior
      Type: object

      Behavior when the trial ends.