AdvancedFeatures
Credit notes and invoice templates
List credit notes for the authenticated organization
GET /api/v1/credit-notes
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: credit_notes.view
Returns paginated credit notes filtered by organization_id, eager-loading the customer and original invoice relationships.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
page |
query | integer | no | |
per_page |
query | integer | no |
Responses
| Status | Description |
|---|---|
| 200 | For non-paginated data, return as before |
| 422 |
Example request
curl -X GET "https://kworia.com/api/v1/credit-notes" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Create a credit note from an invoice
POST /api/v1/credit-notes
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: credit_notes.create
Quick-create linked to an existing invoice (invoice_id, amount, reason, optional credit_type). Optional credit_note_type_code sets the UNCL1001 type code: FR-domestic routes (French seller and French customer) accept 261, 262, 381, 396, 502, 503; every other route accepts the Peppol BIS list 81, 83, 381, 396, 532 (422 otherwise). It is stored on the credit note and written into the credit note's UBL and CII (Factur-X) when they are generated. Credit notes are not sent over the PEPPOL network through this API. Omitted = 381 at send time. The amount must fit what is left to credit on the invoice (its total minus its credit notes that are not cancelled or void); otherwise 422 with error_code: credit_limit_exceeded, the sentence in error and message (e.g. "Credit note total (30.00) exceeds the creditable amount (21.00) for invoice INV-2026-0001.") and no field map in errors; nothing is created.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
invoice_id |
integer | yes | |
amount |
number | yes | |
reason |
string | yes | |
credit_type |
string | no | |
credit_note_type_code |
string | no |
Responses
| Status | Description |
|---|---|
| 201 | For non-paginated data, return as before |
| 422 |
Example request
curl -X POST "https://kworia.com/api/v1/credit-notes" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"invoice_id": 1,
"amount": 1,
"reason": "string",
"credit_type": "string",
"credit_note_type_code": "string"
}'
Show a credit note with its line items
GET /api/v1/credit-notes/{id}
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: credit_notes.view
Single-resource fetch mirroring the invoice/quote detail endpoints; includes items, customer and original_invoice.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer | yes |
Responses
| Status | Description |
|---|---|
| 200 | For non-paginated data, return as before |
Example request
curl -X GET "https://kworia.com/api/v1/credit-notes/{id}" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Download the credit-note PDF
GET /api/v1/credit-notes/{id}/pdf
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: credit_notes.view
Binary PDF, like the invoice/quote PDF endpoints. FNE (Côte d'Ivoire) organizations get the regulatory CI template with stamping/QR data automatically.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer | yes |
Responses
| Status | Description |
|---|---|
| 200 |
Example request
curl -X GET "https://kworia.com/api/v1/credit-notes/{id}/pdf" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Send the credit note to the customer
POST /api/v1/credit-notes/{id}/send
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: credit_notes.create
Delivers via the secure document portal + email. Optional recipients[] (defaults to the customer email) and message. A draft credit note is marked sent only after at least one successful delivery; total delivery failure returns 422 with error_code: delivery_failed (match on it; error and message are display text), a message per recipient under errors, and a stable code per recipient under error_codes (delivery_failed, pdf_generation_failed, fiscal_storage_unavailable, recipient_has_no_email, invalid_sender_email,...). A failure the service did not expect carries a generic message with a support reference, never the exception text. Sending a draft issues it: when its total exceeds what is left to credit on the invoice (its total minus the credit notes already issued, sent or applied), nothing is delivered, the credit note stays a draft, and the response is 422 with error_code: credit_limit_exceeded and the same sentence as on create.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
resend |
boolean | no | |
contact_ids |
array | no |
Responses
| Status | Description |
|---|---|
| 200 | For non-paginated data, return as before |
| 422 | |
| 409 |
Example request
curl -X POST "https://kworia.com/api/v1/credit-notes/{id}/send" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"resend": true,
"contact_ids": []
}'
List templates
GET /api/v1/templates
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: invoices.view
Responses
| Status | Description |
|---|---|
| 501 |
Example request
curl -X GET "https://kworia.com/api/v1/templates" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Create invoice template
POST /api/v1/templates
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: invoices.create
Responses
| Status | Description |
|---|---|
| 501 |
Example request
curl -X POST "https://kworia.com/api/v1/templates" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Create invoice from template
POST /api/v1/templates/{templateId}/create-invoice
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: invoices.create
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
templateId |
path | integer | yes |
Responses
| Status | Description |
|---|---|
| 501 |
Example request
curl -X POST "https://kworia.com/api/v1/templates/{templateId}/create-invoice" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"