---
title: "Subscriptions API: Fixed Billing Dates and Proration"
description: "Subscriptions can now bill every customer on a fixed day, with an optional prorated first charge for customers who join mid-cycle."
date: "2026-09-24"
url: "https://docs.komoju.com/en/changelog/subscriptions-fixed-billing-dates-and-proration"
source_url: "https://docs.komoju.com/en/changelog/subscriptions-fixed-billing-dates-and-proration.md"
language: en
---

## What Changed

Previously, a subscription charged the customer on the day it was created. `POST /subscriptions` now accepts two optional parameters for billing on a fixed day:

- `payment_cycle`: sets the billing day. Pass `anchor_date` (`YYYY-MM-DD`), or use `day_of_month` (1–31) for monthly subscriptions, `day_of_week` (1 for Monday to 7 for Sunday) for weekly subscriptions, or `month` with `day_of_month` for yearly subscriptions. `timezone` takes an IANA identifier such as `Asia/Tokyo`. If omitted, the merchant's default timezone is used.
- `proration_logic`: sets how the first cycle is charged.
- `prorata` immediately charges a prorated amount for the days until the billing date, then charges the full amount from the billing date onward.
- `none` charges nothing at signup and charges the full amount on the billing date. Until then, the subscription stays in `awaiting` status. If `payment_cycle` is provided without `proration_logic`, `none` is used.

If the billing date is today or in the past, the full amount is charged immediately. Charges run at 09:00 in the applicable timezone.

The subscription object now also returns `started_at`, `proration_logic`, and `payment_cycle`. The `status` field can now be `awaiting`.

## Developer Impact

Existing subscriptions and requests without `payment_cycle` work as before. To bill all subscribers on the same day, such as the 1st of each month, add `payment_cycle` to new subscription requests. If your integration reads subscription statuses, handle the new `awaiting` status.