Update a Subscription

​

Updates an existing subscription. All fields are optional — only provided fields are changed.

You can also review subscription state in the Merchant Dashboard.

Related guide: Subscriptions

Ending a trial early: Pass trial_end: "now" to end a trialing subscription's trial immediately. The billing schedule is rebuilt and the first charge fires right away.

Updating items: Providing items replaces all existing subscription items with the new set.

Path Parameters
  • id
    Type: string
    required

    Subscription ID (26-character ULID).

Body·
required
application/json

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: string enum

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

  • 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 | null Format: 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.

      values
      • now
  • billing_cycle_anchor
    Type: string | null Format: 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.

  • trial_settings
    Type: object ·

    Controls what happens when a trial period ends.

  • cancellation_details
    Type: object ·

    Details about why this subscription was cancelled.

  • on_behalf_of
    Type: string

    New connected account ID.

  • payment_behavior
    Type: string 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.

    values
    • allow_incomplete
    • default_incomplete
Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/v1/subscriptions/{id}
curl https://api.paypercut.io/v1/subscriptions/01HD7M6DRKZ4Q4QEVWJB0RC1S6 \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "default_payment_method": "01NEWPAYMENTMETHODXXXXXXXX"
}'

{
  "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": true,
  "cancel_at": null,
  "canceled_at": null,
  "paused_at": null,
  "trial_start": null,
  "trial_end": null,
  "billing_cycle_anchor": "2026-01-01T00:00:00Z",
  "collection_method": "charge_automatically",
  "days_until_due": null,
  "default_payment_method": "01NEWPAYMENTMETHODXXXXXXXX",
  "currency": "USD",
  "livemode": false,
  "ended_at": null,
  "cancellation_details": null,
  "items": [
    {
      "id": "01XXXXXXXXXXXXXXXXXXXXXXX",
      "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-15T00:00:00Z"
    }
  ],
  "created": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-15T00:00:00Z"
}

Subscription updated successfully.