Skip to main content
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.
Update a subscription
curl https://api.yorlet.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Yorlet-Version: 2025-08-21.preview" \
  -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 "Yorlet-Version: 2025-08-21.preview" \
  -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 "Yorlet-Version: 2025-08-21.preview" \
  -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 "Yorlet-Version: 2025-08-21.preview" \
  -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 "Yorlet-Version: 2025-08-21.preview" \
  -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 "Yorlet-Version: 2025-08-21.preview" \
  -H "Content-Type: application/json" \
  -d '{
        "pause_collection": {
          "behavior": "mark_uncollectible",
          "resumes_at": 1767225600
        }
      }'
BehaviorDescription
draftInvoices are created but left as drafts and never finalized
mark_uncollectibleInvoices are finalized but immediately marked uncollectible
voidInvoices 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 "Yorlet-Version: 2025-08-21.preview" \
  -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 "Yorlet-Version: 2025-08-21.preview" \
  -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.
ParameterTypeDescription
collection_methodstringcharge_automatically or send_invoice
default_payment_methodstring | nullThe identifier of the default payment method for the subscription
billing_anchortimestampDate to anchor recurring billing (Unix timestamp)
billing_anchor_configobjectAnchor config with day_of_month (1-31), as an alternative to billing_anchor
billing_cycle_resetbooleanWhether to reset the whole billing cycle around the new billing_anchor, rather than only the next period
end_datetimestamp | nullWhen billing ends (Unix timestamp)
end_date_configobjectDate object (day, month, year) as an alternative to end_date
cancel_attimestamp | nullDate to automatically cancel the subscription (must be at least one day in the future)
credit_note_dataobjectCredit note to issue automatically when the subscription closes, with type (customer_balance, out_of_band, or refund)
pause_collectionobject | nullPause collection with behavior (draft, mark_uncollectible, or void) and resumes_at (timestamp)
proration_behaviorstringcreate_prorations or none, applied when subscription items change
couponstringCoupon ID to apply to the subscription
add_invoice_itemsarrayOne-time invoice items added to the next invoice
phasesarraySubscription phases (only applies when the subscription’s interval is custom)
days_until_dueintegerDays before an invoice is due
days_before_collectionintegerDays before the billing date to create the invoice (0-7)
custom_fieldsarrayCustom fields on invoices (max 4, each with name and value)
payment_settingsobjectRestricts which payment method types can be used to pay invoices, via payment_method_types
descriptionstringThe description of the subscription
metadataobjectSet of key-value pairs to attach to the subscription