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).
Payments imported from another system
A payment already collected elsewhere can be recorded through POST /customers/{customerId}/charges/import.json with charges:write. The result is a paid one-shot charge with instruction=external and externally_managed=true. Original net amounts, taxes, and dates are preserved. No gateway capture or customer payment method is involved, and no subscription is created or renewed.
Partner commissions and eligible referrals follow the existing rules, and the import emits Charge.create and Charge.succeeded. The economic record cannot be edited or refunded through Donutwork's ordinary payment/status-change paths; invoice metadata remains separately editable. The backoffice shows an import badge next to the charge description, with the source system in its tooltip. See external charge import for the payload, source transaction key, and retry behavior.
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. For a direct charge, capture: false leaves it pending; a manual instruction creates it in awaiting_response without capture. SEPA follows its asynchronous payment flow.
Status Synchronization
Monitor the real-time status of the charge. Upon successful payment, the system triggers a Charge.succeeded 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 | string | Unique 24-character hexadecimal charge identifier. |
customer_id | string | The owner of the transaction. |
total | number | Gross total of the transaction, including taxes. |
type | string | Charge category; externally imported payments use one-shot. |
instruction | string | Payment instruction; external identifies an imported payment. |
externally_managed | boolean | True for imported charges whose payment is managed by the source system. |
paid_at | string or null | Payment date in ISO 8601; imported charges preserve the external payment date. |
metadata.paid | object | Detail-only payment metadata; imports include external_source, external_id, and currency. |
status | string | Current state: pending, paid, refunded, failed. |
services | array | List of items being billed with their tax profiles. |
invoice | object | Accounting metadata (number, date, external link), read and written through the dedicated invoice endpoint. |
date | string or object | List summaries expose the original creation date as ISO 8601; detail responses expose the last update as a date object. |
Relationship Call Graph
How Charges interact with external payment gateways: