Subscription billing options | Documentación API de Recurrente

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

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.

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.

$ curl -X POST https://app.recurrente.com/api/checkouts \
>   -H "X-PUBLIC-KEY: your_public_key" \
>   -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.

$ curl -X POST https://app.recurrente.com/api/checkouts \
>   -H "X-PUBLIC-KEY: your_public_key" \
>   -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.

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:

1 {
2   "id": "su_nehndm7j",
3   "status": "active",
4   "current_period_start": "2050-04-10T15:00:00Z",
5   "current_period_end": "2050-04-15T15:00:00Z",
6   "next_payment_attempt_at": null
7 }

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