Update a Subscription

​

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

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·SubscriptionUpdateRequest
required
application/json

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

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

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

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

  • metadata
    Type: object

    Updated metadata key-value pairs.

  • on_behalf_of
    Type: string

    New connected account ID.

  • trial_end
    • enum
      const:  
      now

      End the trial immediately.

      values
      • now

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

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": "pm_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": "pm_01NEWPAYMENTMETHODXXXXXXXX",
  "currency": "USD",
  "livemode": false,
  "ended_at": null,
  "cancellation_details": null,
  "items": [
    {
      "id": "si_01HD7M6DRKZ4Q4QEVWJB0RC1S6",
      "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.