5 · Recurring billing & recovery

Instalment and subscription orders have a payment schedule. BillPro charges each payment on its date. On a metered order, you add each payment yourself. Use the API to check the schedule, handle declined payments and update cards.

Endpoints: Billing Events and Scheduled Payments · Order card

Steps

Check the order's schedule: GET /orders/{id}/scheduled_payments.
If a payment was declined and the card is still valid, charge it again: POST /scheduled_payments/{id}/execute. If auto-retry is on for your profile, BillPro also retries soft-declined payments by itself. You don't need to call the API for that.
If the card has expired or keeps being declined, move the order to another saved card. This also charges what's due. See Using saved cards.

flowchart TB
  Live["Live order"] --> Due["Scheduled payment
  is charged"]
  Due -->|Approved| Next["Next payment
  runs on schedule"]
  Due -->|Declined| Card{"Card still
  valid?"}
  Card -->|Yes| Retry["Charge again
  /scheduled_payments/{id}/execute"]
  Card -->|"No"| Fix["Move to another saved card
  /orders/{id}/replace_card"]
  Retry --> Due
  Fix -->|"Charges what's due"| Next

Manage the schedule

Action	Endpoint
Charge a payment now	`POST /scheduled_payments/{id}/execute`
Reschedule or change a payment	`PATCH /scheduled_payments/{id}`
Skip upcoming payments	`POST /orders/{order_id}/scheduled_payments/skip`
Merge upcoming payments	`POST /orders/{order_id}/scheduled_payments/merge`
Add a payment to a metered order	`POST /orders/{order_id}/scheduled_payments`

On a metered order, send the amount to charge and process_date. A process_date of now schedules the payment for now: execute it to charge straight away.

Using saved cards

Situation	Endpoint
Move the order to another saved card	`POST /orders/{id}/replace_card`
Charge everything that's due to a saved card	`POST /orders/{id}/pay_with_card` with `operation: recover_failed_payments`

Both calls charge every payment that's due and unpaid, merged into one payment. You don't need to execute those payments afterwards.

The card must already be saved for the customer: get its ID from List customer cards. The API can't collect a new card on a live order.

Manage individual payments in Billing Events and Scheduled Payments. When your integration is ready, see 6 · Going live, or go back to the Overview.