Added Recurring Billing to the Billing API

The Billing API now supports recurring billing, letting merchants set up automatically repeating billing requests on a weekly or monthly schedule. A new set of endpoints lets you create a recurring billing, list and retrieve them, and discontinue an active one.

New endpoints

• List recurring billings — GET https://api.coingate.com/v2/billing/recurrings
• Get recurring billing — GET https://api.coingate.com/v2/billing/recurrings/<id>
• Create recurring billing — POST https://api.coingate.com/v2/billing/recurrings
• Discontinue recurring billing — PATCH https://api.coingate.com/v2/billing/recurrings/<id>/discontinue

Creating a recurring billing

Send a POST request with the schedule, the billing contact, and the currencies. You must provide either an amount or a list of billing_request_items so the amount can be derived from products.

Required fields:

• start_at — date the first billing request is issued. It also acts as the anchor for every subsequent cycle: for monthly schedules the next billing date keeps start_at's day-of-month (clamped to the end of shorter months, and always the last day of the month when start_at itself falls on a month-end)
• frequency — how often a new billing request is generated; one of weekly or monthly
• billing_contact_id — the contact that will be billed
• currency_id — the currency the recurring billing is denominated in
• receive_currency_id — the currency you receive the settlement in

Optional fields:

• end_at — date after which no further billing requests are generated. If omitted, the recurring billing continues indefinitely until it is discontinued
• title — label shown on the generated billing requests
• amount — fixed amount to bill each cycle (required if billing_request_items is omitted)
• underpaid_cover_pct — percentage tolerance for underpaid requests
• callback_url — URL notified on billing events
• billing_request_items — array of { billing_product_id, quantity } used to build the amount from products (required if amount is omitted)

Response

Recurring billing responses include the schedule, its current state, and the billing requests it has produced:

• id
• status — one of active, canceled, or completed
• frequency — weekly or monthly
• start_at
• end_at
• next_billing_at — when the next billing request will be generated
• created_at
• billing_requests — array of the requests spawned by this recurring billing, each with id, status, created_at, and paid_at

The list endpoint is paginated and returns current_page, per_page, total_records, and total_pages alongside the recurring_billings array.

Discontinuing

Calling the discontinue endpoint stops an active recurring billing from generating further billing requests. Already-issued requests are unaffected.

Billing Requests API additions

Recurring billing is wired into the existing Billing Requests API:

• The List Billing Requests endpoint now accepts a recurring_billing_id query parameter to return only the requests generated by a given recurring billing — GET https://api.coingate.com/v2/billing/requests?recurring_billing_id=<id>
• Each billing request response now includes the recurring_billing_id it originated from (null for one-off requests) and a paid_at timestamp.