> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yorlet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a subscription

> Learn how to update an existing subscription.

export const APIBadge = () => {
  return <div style={{
    display: 'inline-block',
    backgroundColor: 'rgb(var(--primary-light))',
    color: '#ffffff',
    padding: '1px 4px',
    borderRadius: '.375rem',
    borderColor: 'rgb(var(--gray-200))',
    borderWidth: '1px',
    position: 'relative',
    top: '-2px',
    marginLeft: '4px',
    fontSize: '11px',
    fontWeight: 700,
    letterSpacing: '0.05em',
    lineHeight: '11px'
  }}>
      API
    </div>;
};

Once a subscription exists, you can [update it<APIBadge />](https://docs.yorlet.com/api/billing/subscriptions/update) 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.

```bash Update a subscription theme={"theme":"dracula"}
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.

```json Subscription object theme={"theme":"dracula"}
{
  "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](https://docs.yorlet.com/api/payments/payment-methods/object) belonging to the subscription's customer. Pass `null` to remove the default payment method.

```bash Change the default payment method theme={"theme":"dracula"}
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.

```bash Reanchor the next billing period theme={"theme":"dracula"}
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
      }'
```

<Note>
  Set `billing_cycle_reset` to `true` to reset the *entire* current billing cycle around the new anchor, rather than only the next period.
</Note>

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

```bash Change the end date theme={"theme":"dracula"}
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.

```bash Schedule a cancellation theme={"theme":"dracula"}
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
      }'
```

<Note>
  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<APIBadge />](https://docs.yorlet.com/api/billing/subscriptions/cancel) endpoint.
</Note>

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

```bash Pause collection theme={"theme":"dracula"}
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
        }
      }'
```

| 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](https://docs.yorlet.com/api/billing/coupons/object) to apply a discount to the subscription.

```bash Apply a coupon theme={"theme":"dracula"}
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.

```bash Add a one-off invoice item theme={"theme":"dracula"}
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
          }
        ]
      }'
```

<Note>
  To change the recurring items on a subscription (for example, updating the rent amount), use the [Subscription Items API<APIBadge />](https://docs.yorlet.com/api/billing/subscription-items/update) 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.
</Note>

### 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                                                                          |