Skip to content
On this page

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"