Invoice Lifecycle

Every invoice moves through a series of statuses from creation to acceptance (or failure).

Status diagram


┌───────┐     ┌────────┐     ┌─────────┐     ┌──────────┐
│ draft │────>│ queued │────>│ pending │────>│ accepted │
└───────┘     └────────┘     └─────────┘     └──────────┘
                                  │
                                  ├────>┌──────────┐
                                  │     │ rejected │
                                  │     └──────────┘
                                  │
                                  └────>┌────────┐     (retry, max 5)
                                        │ failed │────> queued
                                        └────────┘

accepted ────> cancelled (creates credit note)

Statuses

Status	Description	What you can do
`draft`	Created, not submitted	Edit, delete, or submit
`queued`	In the submission queue	Wait. Cannot modify.
`pending`	Sent to tax authority, awaiting response	Poll with `GET /invoices/:id/status` or wait for webhook
`accepted`	Tax authority accepted the invoice	Download PDF. Can cancel (creates credit note).
`rejected`	Tax authority rejected the invoice	Read error details. Create a corrected invoice.
`failed`	Submission failed (network, timeout)	Retry with `POST /invoices/:id/retry`. Max 5 attempts.
`cancelled`	Invoice voided	A credit note is created automatically.

What triggers each transition

From	To	Trigger
—	`draft`	`POST /i/v1/invoices`
`draft`	`queued`	`POST /i/v1/invoices/:id/submit`
`queued`	`pending`	Worker picks up the job
`pending`	`accepted`	Tax authority returns approval
`pending`	`rejected`	Tax authority returns rejection with errors
`pending`	`failed`	Network error, timeout, or tax authority unavailable
`failed`	`queued`	`POST /i/v1/invoices/:id/retry`
`accepted`	`cancelled`	`POST /i/v1/invoices/:id/cancel`

Webhook events by status

These are the events actively dispatched to your webhook endpoints:

Status change	Webhook event
→ `accepted`	`invoice.approved`
→ `rejected`	`invoice.rejected`
→ `failed` (submission error)	`invoice.failed`

Handling rejections

Rejected invoices cannot be resubmitted. You must create a new invoice with the corrections:

Retrieve the rejected invoice to inspect error details:

bash

curl https://gateway.useyona.com/i/v1/invoices/inv_rejected_id \
  -H "Authorization: Bearer sk_test_your_key_here"

Create a corrected invoice with a new invoice number:

bash

curl -X POST https://gateway.useyona.com/i/v1/invoices \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sellerId": "c7a1d3e5-8f2b-4a6c-9d0e-1f2a3b4c5d6e",
    "buyerId": "d8b2e4f6-9a3c-5b7d-0e1f-2a3b4c5d6e7f",
    "invoiceNumber": "INV-2026-001-R1",
    "invoiceDate": "2026-04-20",
    "lineItems": [{ "description": "Corrected line item", "quantity": 10, "unitPrice": 50000, "taxPercent": 7.5, "hsnCode": "9983", "unitCode": "HUR" }]
  }'

Submit the corrected invoice:

bash

curl -X POST https://gateway.useyona.com/i/v1/invoices/{corrected_id}/submit \
  -H "Authorization: Bearer sk_test_your_key_here"

Handling failures

Failed invoices can be retried up to 5 times:

bash

curl -X POST https://gateway.useyona.com/i/v1/invoices/inv_failed_id/retry \
  -H "Authorization: Bearer sk_test_your_key_here"

After 5 failures, the invoice.failed webhook fires. Investigate the error before creating a new invoice.

💡 SDK available

See SDK — Invoices for the programmatic interface.