> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recurrente.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recurrente.com/_mcp/server.

# Subscription billing options

> Control the billing day, proration, and first-charge deferral

When you create a product or checkout with `charge_type: "recurring"`, three fields work together to control when and how much the first charge is:

| Field                      | What it controls                                                           |
| -------------------------- | -------------------------------------------------------------------------- |
| `billing_cycle_anchor_day` | Day of the month (1–31) that recurring charges are anchored to             |
| `proration_behavior`       | Whether the first charge is prorated (`create_prorations`) or not (`none`) |
| `defer_to_billing_day`     | Whether the first charge is deferred until the anchor day                  |

> **Note**
>
> `billing_cycle_anchor_day` on its own does **not** change the first charge: it only takes effect when combined with `proration_behavior: create_prorations` **or** `defer_to_billing_day: true`.

## What happens in each combination

A customer subscribes on **April 10** to a monthly plan of **GTQ 300**, with `billing_cycle_anchor_day: 15`:

| Configuration                                                    | First charge (April 10)    | Next charge        |
| ---------------------------------------------------------------- | -------------------------- | ------------------ |
| None (`proration_behavior: none`, `defer_to_billing_day: false`) | GTQ 300                    | May 10             |
| `proration_behavior: create_prorations`                          | GTQ 50 (5 days: Apr 10→15) | April 15 (GTQ 300) |
| `defer_to_billing_day: true`                                     | GTQ 0 (card saved only)    | April 15 (GTQ 300) |

From the second charge on, charges happen on the 15th of each month.

> **Note**
>
> If the subscription has a free trial (`free_trial_interval`), both proration and deferral are ignored. The trial takes precedence.

## Example 1: Prorate the first charge

Charge only the days left until the anchor day. The next charge will be the full amount on the anchor day.

```bash
curl -X POST https://app.recurrente.com/api/checkouts \
  -H "X-SECRET-KEY: your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "name": "Monthly Membership",
        "currency": "GTQ",
        "amount_in_cents": 30000,
        "charge_type": "recurring",
        "billing_interval": "month",
        "billing_interval_count": 1,
        "billing_cycle_anchor_day": 15,
        "proration_behavior": "create_prorations"
      }
    ],
    "success_url": "https://yoursite.com/thanks",
    "cancel_url": "https://yoursite.com/cancelled"
  }'
```

At checkout, the customer will see the full monthly amount **minus a credit line item** for the unused days. The difference is the prorated amount charged today.

## Example 2: Defer the first charge until the anchor day

Don't charge anything when the subscription is created. Tokenize the card via SetupIntent; the first full charge happens automatically on the next anchor date.

```bash
curl -X POST https://app.recurrente.com/api/checkouts \
  -H "X-SECRET-KEY: your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "name": "Monthly Membership",
        "currency": "GTQ",
        "amount_in_cents": 30000,
        "charge_type": "recurring",
        "billing_interval": "month",
        "billing_interval_count": 1,
        "billing_cycle_anchor_day": 15,
        "defer_to_billing_day": true
      }
    ],
    "success_url": "https://yoursite.com/thanks",
    "cancel_url": "https://yoursite.com/cancelled"
  }'
```

When the customer completes the checkout, you'll receive a `setup_intent.succeeded` webhook (not `payment_intent.succeeded`) because no charge happened. The `subscription.create` webhook arrives at the same time with the subscription already active. The first real charge fires `payment_intent.succeeded` on the anchor day.

> **Note**
>
> `proration_behavior: create_prorations` and `defer_to_billing_day: true` are mutually exclusive: if both are enabled, proration wins and the first charge happens today with the prorated amount.

## Reading the next charge date

After creating a subscription, the response of `GET /api/subscriptions/{id}` includes `current_period_end`, which is the next automatic charge date:

```json
{
  "id": "su_nehndm7j",
  "status": "active",
  "current_period_start": "2050-04-10T15:00:00Z",
  "current_period_end": "2050-04-15T15:00:00Z",
  "next_payment_attempt_at": null
}
```

* If you used `proration_behavior: create_prorations`, `current_period_end` points to the next anchor date (when the first full charge happens).
* If you used `defer_to_billing_day: true`, `current_period_end` points to the anchor day (when the first charge happens).
* With neither flag, `current_period_end` is `created_at + billing_interval`.

## Considerations

* **Monthly intervals only.** The fields `billing_cycle_anchor_day`, `proration_behavior`, and `defer_to_billing_day` only apply when `billing_interval` is `month`.
* **If the month has fewer days than `billing_cycle_anchor_day`**, the charge happens on the last day of the month. For example, `billing_cycle_anchor_day: 31` charges on Feb 28.
* **Changing the price of an active subscription** is not possible via API (`PUT /api/products/{id}` does not allow editing prices with active subscriptions).