SubscriptionUpdateRequest

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

  • default_payment_method
    Type: string

    ID of the new default payment method.

  • collection_method
    Type: "charge_automatically" or "send_invoice"enum

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

  • days_until_due
    Type: integer
    min:  
    1

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

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

  • cancel_at
    Type: string | nullFormat: date-time

    New scheduled cancellation date (ISO 8601).

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

  • billing_cycle_anchor
    Type: string | nullFormat: date-time

    New billing cycle anchor date (ISO 8601).

  • billing_cycle_anchor_config
    Type: BillingCycleAnchorConfig

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

    Properties: 5
  • trial_settings
    Type: TrialSettings

    Controls what happens when a trial period ends.

    Properties: 1
  • cancellation_details
    Type: CancellationDetails

    Details about why this subscription was cancelled.

    Properties: 2
  • on_behalf_of
    Type: string

    New connected account ID.

  • payment_behavior
    Type: "allow_incomplete" or "default_incomplete"enum

    Controls when and how charges are collected after the update. Only allow_incomplete and default_incomplete are accepted on update — error_if_incomplete and send_invoice are creation-only behaviors.

    • allow_incomplete — without anchor: charge attempted inline immediately after the update; success → active; failure → past_due. With billing_cycle_anchor: charge deferred to the anchor date; success → active; failure → past_due. Up to 3 total charge attempts; exhaustion → canceled.

    • default_incomplete — without anchor: charge attempted inline immediately after the update; success → active; failure → past_due. With billing_cycle_anchor: subscription stays incomplete until the anchor date; charge fires at the anchor date; success → active; failure → past_due. Up to 3 total charge attempts; exhaustion → incomplete_expired.

  • items
    Type: array 1…20

    Replace all subscription items with this new set.

  • metadata
    Type: object

    Updated metadata key-value pairs.

    Properties: 1