A charge is an invoice on a contract. A contract may have one or many charges depending on how it was created.
How Charges Are Created
- One-time payments: a single charge is created
- Recurring (frequency-based) contracts: a new charge is generated each billing cycle (e.g., monthly) as the cycle becomes due
- Scheduled-charges contracts: the full set of charges is created upfront from the explicit
charges[]array supplied at contract creation. Each charge carries its ownamount,duedate, and optionalalt_key
Each charge tracks:
- The amount due
- When it's due
- How much has been paid
- How much is outstanding
- Whether it's been written off
For recurring and one-time contracts you don't create charges manually — they are generated automatically. For scheduled-charges contracts, all charges are materialised at the moment the contract is created. In both cases, to retrieve the charges on a contract use List contract charges.
Status Flow
| Status | Description |
|---|---|
ACTIVE | The charge has been raised but not yet fully paid |
PENDING | The charge has been paid but the transaction is still pending confirmation |
COMPLETED | The charge has been fully paid |
WRITTENOFF | The charge has been fully or partially written off |
Modifying Charges
You can update a charge to:
- Write off an outstanding balance by setting status to
WRITTENOFF - Change the amount due (cannot be less than the amount already paid)
- Change the due date: note that setting a past due date may trigger an immediate payment attempt