Skip to main content
Version: v2alpha1

Draft invoices using the API

Steps​

1. Issue draft invoice​

Issue an invoice as any other invoice, indicating the status as draft.

Request​

POST /invoices
{
  "status": "draft",
  [...]
}

Response​

201 Created
{
  "id": "inv_4ehg1mkv3mvt3256vcn8dspb4h",
  "status": "draft",
  [...]
}

2. Generate draft invoice document​

getpaid generates the invoice document asynchronously once the invoice is issued. Templates can be customized to include an indicator that the invoice is a draft, for example, a watermark or a "DRAFT" stamp.

It can be generated in various formats and provides and URL to download it.

3. Notify about draft document creation​

Once the invoice document creation is completed in each of the formats needed, a invoice_draft_document_updated webhook notification per document generated is sent to the configured webhook URL.

4. Update draft invoice​

If the invoice information requires changes, while it is in draft status, it can be updated using the Update Draft Invoice endpoint. The invoice document is regenerated and the invoice_draft_document_updated webhook notification is sent again with the new document ID.

5. Issue draft invoice​

If the invoice information is correct and the invoice is ready to be issued and sent to the buyer, the draft can be issued using the Issue Draft Invoice endpoint. The invoice is issued and the definitive document is generated as usual.

6. Send invoice buyer notification​

If the buyer notifications are configured and only when the draft is issued, getpaid sends a newly issued invoice notification to the buyer with the invoice documents attached.

7. Notify about buyer notification sent​

If the buyer notifications are configured and only when the draft is issued, once the notification is sent, a invoice_buyer_notification_sent webhook notification is sent to the configured webhook URL.

8. Cancel draft invoice​

If the invoice must be discarded, the draft can be cancelled using the Cancel Draft Invoice endpoint. The invoice cannot be updated or issued after its cancellation.