Subscriptions API: Fixed Billing Dates and Proration

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.