Charge Entity
Understanding financial transactions, one-time billables, and invoice metadata.
Charge Entity
A Charge (also referred to as a Transaction) represents a specific financial balance associated with a Customer. It can be generated automatically by a subscription renewal or created manually for one-off services.
Usage
The Charge entity is used to:
- Process ad-hoc payments for setup fees, consulting, or hardware.
- Store the history of recurring billing events.
- Manage association with legal documents (invoices and receipts).
- Track the real-time payment status (Pending, Paid, Refunded).
Expected Operational Flow
Lifecycle of a financial transaction:
Charge Generation
Create a charge object via POST /customers/{id}/charges.json. You can define multiple service lines, each with its own specific tax profile for granular accounting.
Execution & Capture
If capture: true is set, DonutWork immediately attempts to process the transaction using the customer's primary payment method. Otherwise, the charge remains awaiting_response.
Status Synchronization
Monitor the real-time status of the charge. Upon successful payment, the system triggers a Charge.Paid webhook to your application.
Invoicing & Compliance
Once paid, synchronize the transaction with your accounting software and use the PUT /.../invoice.json endpoint to attach the legal document details to the record.
Data Schema
The fields defining a Charge object:
| Field | Type | Description |
|---|---|---|
id | eid | Unique extended identifier. |
customer_id | string | The owner of the transaction. |
total | number | Net total of the transaction (including tax lines). |
status | string | Current state: pending, paid, refunded, failed. |
services | array | List of items being billed with their tax profiles. |
invoice | object | Metadata for accounting (number, date, external link). |
date | object | Precise timestamp of the creation event. |
Relationship Call Graph
How Charges interact with external payment gateways: