Update a subscription

Once a subscription exists, you can update it to change its payment method, reschedule billing, pause or resume collection, schedule a cancellation, apply a coupon, and more. Only include the fields you want to change - fields you omit are left untouched.

curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "default_payment_method": "{{PAYMENT_METHOD_ID}}"
      }'

If the request completed successfully, the response contains the updated subscription object.

Subscription object

{
  "id": "sub_lrhplff1u4ZhIPSU",
  "object": "subscription",
  "default_payment_method": "pm_l34dl7phkOVU7wcI",
  // ... other fields on the Subscription object
}

Change the default payment method

Set default_payment_method to the ID of a payment method belonging to the subscription’s customer. Pass null to remove the default payment method.

Change the default payment method

curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "default_payment_method": "{{PAYMENT_METHOD_ID}}"
      }'

You can also switch how invoices are collected with collection_method (charge_automatically or send_invoice). Switching to send_invoice clears the default payment method type, since invoices are no longer charged automatically.

Reschedule billing

To move the point in the billing cycle that future periods are calculated from, set billing_anchor to a Unix timestamp. By default, this only affects the next period going forward.

Reanchor the next billing period

curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "billing_anchor": 1735689600
      }'

Set billing_cycle_reset to true to reset the entire current billing cycle around the new anchor, rather than only the next period.

To change when a subscription ends, set end_date to a Unix timestamp, or null to let it continue indefinitely.

Change the end date

curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "end_date": 1767225600
      }'

Schedule a cancellation

Set cancel_at to a Unix timestamp to automatically cancel the subscription at a future date. The date must be at least one day in the future. Pass null to remove a scheduled cancellation.

Schedule a cancellation

curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "cancel_at": 1767225600
      }'

You can also set credit_note_data on the same request to have Yorlet automatically issue a credit note when the subscription is later closed. To cancel a subscription immediately instead of scheduling it, use the Cancel a subscription endpoint.

Pause or resume collection

Set pause_collection to stop Yorlet from collecting payment on new invoices, while still generating them according to behavior. Pass null to resume collection immediately.

Pause collection

curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "pause_collection": {
          "behavior": "mark_uncollectible",
          "resumes_at": 1767225600
        }
      }'

Behavior	Description
`draft`	Invoices are created but left as drafts and never finalized
`mark_uncollectible`	Invoices are finalized but immediately marked uncollectible
`void`	Invoices are finalized and immediately voided

Apply a coupon

Set coupon to the ID of a coupon to apply a discount to the subscription.

Apply a coupon

curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "coupon": "{{COUPON_ID}}"
      }'

Add a one-off invoice item

Use add_invoice_items to add one-time charges to the next invoice generated by the subscription, without changing the recurring items.

Add a one-off invoice item

curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "add_invoice_items": [
          {
            "description": "Late payment fee",
            "type": "charge",
            "amount": 2500,
            "currency": "gbp",
            "tax_percent": 0
          }
        ]
      }'

To change the recurring items on a subscription (for example, updating the rent amount), use the Subscription Items API instead. Set proration_behavior on the subscription update to create_prorations or none to control whether prorated invoice items are generated when a subscription item changes.

Parameters

All parameters are optional - only include the fields you want to change.

Parameter	Type	Description
`collection_method`	string	`charge_automatically` or `send_invoice`
`default_payment_method`	string \| null	The identifier of the default payment method for the subscription
`billing_anchor`	timestamp	Date to anchor recurring billing (Unix timestamp)
`billing_anchor_config`	object	Anchor config with `day_of_month` (1-31), as an alternative to `billing_anchor`
`billing_cycle_reset`	boolean	Whether to reset the whole billing cycle around the new `billing_anchor`, rather than only the next period
`end_date`	timestamp \| null	When billing ends (Unix timestamp)
`end_date_config`	object	Date object (`day`, `month`, `year`) as an alternative to `end_date`
`cancel_at`	timestamp \| null	Date to automatically cancel the subscription (must be at least one day in the future)
`credit_note_data`	object	Credit note to issue automatically when the subscription closes, with `type` (`customer_balance`, `out_of_band`, or `refund`)
`pause_collection`	object \| null	Pause collection with `behavior` (`draft`, `mark_uncollectible`, or `void`) and `resumes_at` (timestamp)
`proration_behavior`	string	`create_prorations` or `none`, applied when subscription items change
`coupon`	string	Coupon ID to apply to the subscription
`add_invoice_items`	array	One-time invoice items added to the next invoice
`phases`	array	Subscription phases (only applies when the subscription’s `interval` is `custom`)
`days_until_due`	integer	Days before an invoice is due
`days_before_collection`	integer	Days before the billing date to create the invoice (0-7)
`custom_fields`	array	Custom fields on invoices (max 4, each with `name` and `value`)
`payment_settings`	object	Restricts which payment method types can be used to pay invoices, via `payment_method_types`
`description`	string	The description of the subscription
`metadata`	object	Set of key-value pairs to attach to the subscription

Developer tools

Essentials

Integrations

Platforms

Change the default payment method

Reschedule billing

Schedule a cancellation

Pause or resume collection

Apply a coupon

Add a one-off invoice item

Parameters

​Change the default payment method

​Reschedule billing

​Schedule a cancellation

​Pause or resume collection

​Apply a coupon

​Add a one-off invoice item

​Parameters

Change the default payment method

Reschedule billing

Schedule a cancellation

Pause or resume collection

Apply a coupon

Add a one-off invoice item

Parameters