Cowdidocs
API ReferenceInvoice financing

Get a financing invoice

GET
/v1/financing/merchants/{merchantId}/invoices/{invoiceId}

Returns one financing invoice belonging to the merchant. Requires merchant:financing.invoices:read on the merchant.

Authorization

oauth2
AuthorizationBearer <token>

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

merchantId*string

Canonical sales-app merchant id, shared with Core. Legacy ids remain readable.

Length1 <= length <= 255
invoiceId*string

Invoice id.

Formatuuid

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/550e8400-e29b-41d4-a716-446655440000"
{  "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"}
{  "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"    }  ]}

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.

Update a financing invoice PATCH

Replaces the set of documents attached to the invoice beyond its invoice document (the buyer's supporting documents), the deductions the buyer withholds from the payout and/or the VAT separated from the face value. Any of them, at least one. Each document is attached first via the documents endpoint; this names them on the invoice. Requires `org:merchants:write` — it changes the invoice, not the documents.