Create an Invoice with the API
Create finance invoices from an external system.
Use the invoices endpoints when an external system needs to create or update Agiled invoices.
Use API-created invoices only when the external system already has clean customer, line item, tax, and payment context.
For manual or low-volume invoices, use the finance UI. Use the API when invoice creation is part of a system integration or repeatable backend process.
Before You Start
Make sure the integration has:
- A full-access API key or a key with invoice write ability.
- The correct contact or account identifiers.
- Product, tax, currency, and line-item data formatted for the public API request body.
Create or resolve customer identifiers before invoice creation. Avoid creating duplicate customers just to attach an invoice.
Example Pattern
curl "$AGILED_API_BASE_URL/public/v1/invoices" \
-X POST \
-H "Authorization: Bearer $AGILED_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: invoice-external-1001" \
-d @invoice.jsonUse the generated OpenAPI reference for the exact request body fields supported by your current deployment.
Use an idempotency key based on the external invoice or order ID so retries do not create duplicate invoices.
Store the returned Agiled invoice ID next to the external invoice or order ID. That makes later updates, payment checks, and support review safer.
After Creation
Check the API response for the created invoice id. If your workflow needs to notify a customer or collect payment, continue in the finance document workflow inside Agiled.
Open the created invoice in Agiled and verify customer, totals, taxes, line items, status, and public payment behavior before automating larger volumes.
Troubleshooting
If invoice creation fails validation, check customer identifiers, line item shape, currency, tax fields, and required dates.
If duplicate invoices appear, confirm retries reuse the same idempotency key.
Customer-Facing Review
Before automating customer delivery, preview the invoice in Agiled. Confirm the customer, line items, tax, discount, due date, payment instructions, and public payment page are correct.
If the external system controls payment status, make sure paid, partial, and failed payments are reconciled before Agiled sends follow-up reminders or reports the invoice as outstanding.
Retry And Reconciliation
Use an idempotency key based on the external order or invoice ID. Store the Agiled invoice ID returned by the first successful request and use that ID for later updates, payment checks, or support review.
After a batch run, compare created invoice count and totals against the source system before sending reminders, payment links, or revenue reports.