List financing invoices for a merchant
Returns a page of a merchant’s own financing invoices, newest first. Requires merchant:financing.invoices:read on the merchant; an organization-scoped role can grant that same permission across every merchant it manages. Use GET /v1/financing/invoices instead for an organization-wide roll-up across every merchant.
Authorization
oauth2 Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.
In: header
Path Parameters
Canonical sales-app merchant id, shared with Core. Legacy ids remain readable.
1 <= length <= 255Query Parameters
Page size from 1 to 100. Defaults to 20.
^\d+$Opaque cursor for the next page, taken from links.next. Mutually exclusive with before.
Opaque cursor for the previous page, taken from links.prev. Mutually exclusive with after.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/financing/merchants/01JZQ5W7M5Y83M6F1D6E0A2K8N/invoices"{ "data": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6", "attached_document_ids": [ "2daa2194-1f27-4d7b-a37c-8fc5cf0db85c" ], "deductions": [ { "id": "string", "kind": "VAT", "label": "string", "basis": "BASIS_POINTS", "basis_points": 0 } ], "vat": { "basis": "RATE", "rate_basis_points": 1, "paid": true }, "rejection_reason": "DUPLICATE_INVOICE", "rejection_note": "string", "rejected_by": "string", "rejected_at": "2019-08-24T14:15:22Z", "amount_minor_units": 250000, "currency": "KES", "details": { "property1": null, "property2": null }, "due_date": "2019-08-24", "issued_date": "2019-08-24", "status": "PENDING", "created_at": "2019-08-24T14:15:22Z" } ], "links": { "next": "string", "prev": "string" }}{ "code": "INVALID_PARAMS", "description": "user_id must be a UUID", "identifier": "string", "invalid_params": [ { "path": "user_id", "reason": "must be a UUID", "sub_code": "string" } ]}{ "code": "INVALID_PARAMS", "description": "user_id must be a UUID", "identifier": "string", "invalid_params": [ { "path": "user_id", "reason": "must be a UUID", "sub_code": "string" } ]}{ "code": "INVALID_PARAMS", "description": "user_id must be a UUID", "identifier": "string", "invalid_params": [ { "path": "user_id", "reason": "must be a UUID", "sub_code": "string" } ]}{ "code": "INVALID_PARAMS", "description": "user_id must be a UUID", "identifier": "string", "invalid_params": [ { "path": "user_id", "reason": "must be a UUID", "sub_code": "string" } ]}{ "code": "INVALID_PARAMS", "description": "user_id must be a UUID", "identifier": "string", "invalid_params": [ { "path": "user_id", "reason": "must be a UUID", "sub_code": "string" } ]}{ "code": "INVALID_PARAMS", "description": "user_id must be a UUID", "identifier": "string", "invalid_params": [ { "path": "user_id", "reason": "must be a UUID", "sub_code": "string" } ]}Attach an uploaded financing document POST
Attaches a document record after the client PUT the file to the presigned URL from POST .../uploads/presign. Requires `merchant:financing.documents:write` on the merchant. Returns 400 when `upload_ref` is expired or does not match this merchant, caller, and document type, or when the uploaded object is missing, oversized, or does not match the presigned content type and size. Returns 409 when the same upload has already been attached. Register the returned document as an invoice next, with POST .../invoices.
Submit or re-extract a financing invoice POST
A complete submission supplies invoice_number, invoice_amount, due_date and document_ids. Matching buyer, merchant, number and figures return the same invoice with its original documents and review state. Different figures return 409. The response details.submitted_document_ids contains the saved submission documents. To correct a REJECTED invoice, use POST .../invoices/{invoiceId}/resubmissions. The extraction body registers an invoice keyed on document_id (at most one invoice per document). The document must be `type: "INVOICE"`. Re-extraction updates an unsubmitted `PENDING` invoice in place; a submitted or reviewed invoice (`APPROVED`, `REJECTED`, `FINANCED`, or `PAID`) is immutable, and re-extraction is rejected once the new amount would be smaller than the deductions or VAT already recorded on the invoice. Requires `merchant:financing.invoices:write` on the merchant. Attach the document first, with POST .../documents.