Cowdidocs
API ReferenceInvoice financing

Submit an invoice for buyer review

POST
/v1/merchants/{merchantId}/invoice-financing/applications

Submits one of the merchant's invoices for the buyer to review, and returns today's discount estimate. Requires the merchant:financing.invoices:write permission on the merchant. Returns 404 when the merchant does not belong to the caller's organization. Repeated submissions with the same buyer, seller, invoice number, amount, currency and due date resume the accepted application. Recovery preserves its original documents and payout destinations. Returns 409 for conflicting figures. Saves the application and approval event atomically. An optional Idempotency-Key replays completed responses.

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

Unique identifier of the merchant.

Formatuuid

Header Parameters

Idempotency-Key*string

Unique key that de-duplicates retries of this request: the first call executes and its response is stored, identical retries replay it, and reusing a key with a different request body is rejected with 409 Conflict.

Lengthlength <= 255

Request Body

application/json

Fields to submit an invoice for buyer review and financing.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/merchants/a50e8400-e29b-41d4-a716-446655440000/invoice-financing/applications" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "invoice_number": "INV-2026-00042",    "invoice_amount": {      "value": 100000,      "currency": "KES"    },    "due_date": "2026-11-01",    "document_ids": [      "950e8400-e29b-41d4-a716-446655440000"    ],    "disbursement_destinations": [      {        "type": "string"      }    ]  }'
{  "id": "650e8400-e29b-41d4-a716-446655440000",  "loan_product_type": "ACME_INVOICE_FINANCING",  "organization_id": "cowdi",  "merchant_id": "a50e8400-e29b-41d4-a716-446655440000",  "user_id": "660e8400-e29b-41d4-a716-446655440111",  "submitted_by": "660e8400-e29b-41d4-a716-446655440111",  "status": "ACTIVE",  "invoice_number": "INV-2026-00042",  "invoice_amount": {    "value": 100000,    "currency": "KES"  },  "due_date": "2026-11-01",  "discount_rate": {    "basis_points": 500,    "period": {      "value": 1,      "unit": "DAYS"    },    "day_count_convention": "ACTUAL_365"  },  "min_loan_amount": {    "value": 100000,    "currency": "KES"  },  "max_loan_amount": {    "value": 5000000,    "currency": "KES"  },  "min_tenure": {    "value": 1,    "unit": "DAYS"  },  "max_tenure": {    "value": 1,    "unit": "DAYS"  },  "timezone": "Africa/Nairobi",  "document_ids": [    "950e8400-e29b-41d4-a716-446655440000"  ],  "disbursement_destinations": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "destination": {        "type": "string",        "paybill_number": 400200,        "account_number": "string"      }    }  ],  "created_at": "2026-09-01T10:15:30Z",  "resubmission_of": "650e8400-e29b-41d4-a716-446655440000",  "approval_workflow_run_id": "e430dfb1-7d1a-4ebc-b9d6-92d3fdd8aed0",  "selected_destination_id": "c0caf160-abf0-4e4d-8303-7f2d1f37d132",  "approved_at": "2019-08-24T14:15:22Z",  "rejected_at": "2019-08-24T14:15:22Z",  "rejection_reason": "string",  "estimate": {    "estimated_disbursement_date": "2026-10-01",    "due_date": "2026-11-01",    "estimated_discount": {      "value": 15000,      "currency": "KES"    },    "estimated_payout": {      "value": 485000,      "currency": "KES"    }  },  "funding": {    "disbursement_id": "550e8400-e29b-41d4-a716-446655440000",    "status": "PENDING",    "facility_account_id": "550e8400-e29b-41d4-a716-446655440000",    "transaction_id": "0fec1e58-b197-4052-99cf-2218496c5482",    "authorized_at": "2026-09-01T10:15:30Z",    "failure_reason": "Account limit exceeded"  }}
{  "code": "BAD_REQUEST",  "description": "Bad Request"}
{  "code": "UNAUTHORISED",  "description": "Unauthorised"}
{  "code": "FORBIDDEN",  "description": "Forbidden"}
{  "id": "650e8400-e29b-41d4-a716-446655440000",  "loan_product_type": "ACME_INVOICE_FINANCING",  "organization_id": "cowdi",  "merchant_id": "a50e8400-e29b-41d4-a716-446655440000",  "user_id": "660e8400-e29b-41d4-a716-446655440111",  "submitted_by": "660e8400-e29b-41d4-a716-446655440111",  "status": "ACTIVE",  "invoice_number": "INV-2026-00042",  "invoice_amount": {    "value": 100000,    "currency": "KES"  },  "due_date": "2026-11-01",  "discount_rate": {    "basis_points": 500,    "period": {      "value": 1,      "unit": "DAYS"    },    "day_count_convention": "ACTUAL_365"  },  "min_loan_amount": {    "value": 100000,    "currency": "KES"  },  "max_loan_amount": {    "value": 5000000,    "currency": "KES"  },  "min_tenure": {    "value": 1,    "unit": "DAYS"  },  "max_tenure": {    "value": 1,    "unit": "DAYS"  },  "timezone": "Africa/Nairobi",  "document_ids": [    "950e8400-e29b-41d4-a716-446655440000"  ],  "disbursement_destinations": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "destination": {        "type": "string",        "paybill_number": 400200,        "account_number": "string"      }    }  ],  "created_at": "2026-09-01T10:15:30Z",  "resubmission_of": "650e8400-e29b-41d4-a716-446655440000",  "approval_workflow_run_id": "e430dfb1-7d1a-4ebc-b9d6-92d3fdd8aed0",  "selected_destination_id": "c0caf160-abf0-4e4d-8303-7f2d1f37d132",  "approved_at": "2019-08-24T14:15:22Z",  "rejected_at": "2019-08-24T14:15:22Z",  "rejection_reason": "string",  "estimate": {    "estimated_disbursement_date": "2026-10-01",    "due_date": "2026-11-01",    "estimated_discount": {      "value": 15000,      "currency": "KES"    },    "estimated_payout": {      "value": 485000,      "currency": "KES"    }  },  "funding": {    "disbursement_id": "550e8400-e29b-41d4-a716-446655440000",    "status": "PENDING",    "facility_account_id": "550e8400-e29b-41d4-a716-446655440000",    "transaction_id": "0fec1e58-b197-4052-99cf-2218496c5482",    "authorized_at": "2026-09-01T10:15:30Z",    "failure_reason": "Account limit exceeded"  }}
{  "id": "650e8400-e29b-41d4-a716-446655440000",  "loan_product_type": "ACME_INVOICE_FINANCING",  "organization_id": "cowdi",  "merchant_id": "a50e8400-e29b-41d4-a716-446655440000",  "user_id": "660e8400-e29b-41d4-a716-446655440111",  "submitted_by": "660e8400-e29b-41d4-a716-446655440111",  "status": "ACTIVE",  "invoice_number": "INV-2026-00042",  "invoice_amount": {    "value": 100000,    "currency": "KES"  },  "due_date": "2026-11-01",  "discount_rate": {    "basis_points": 500,    "period": {      "value": 1,      "unit": "DAYS"    },    "day_count_convention": "ACTUAL_365"  },  "min_loan_amount": {    "value": 100000,    "currency": "KES"  },  "max_loan_amount": {    "value": 5000000,    "currency": "KES"  },  "min_tenure": {    "value": 1,    "unit": "DAYS"  },  "max_tenure": {    "value": 1,    "unit": "DAYS"  },  "timezone": "Africa/Nairobi",  "document_ids": [    "950e8400-e29b-41d4-a716-446655440000"  ],  "disbursement_destinations": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "destination": {        "type": "string",        "paybill_number": 400200,        "account_number": "string"      }    }  ],  "created_at": "2026-09-01T10:15:30Z",  "resubmission_of": "650e8400-e29b-41d4-a716-446655440000",  "approval_workflow_run_id": "e430dfb1-7d1a-4ebc-b9d6-92d3fdd8aed0",  "selected_destination_id": "c0caf160-abf0-4e4d-8303-7f2d1f37d132",  "approved_at": "2019-08-24T14:15:22Z",  "rejected_at": "2019-08-24T14:15:22Z",  "rejection_reason": "string",  "estimate": {    "estimated_disbursement_date": "2026-10-01",    "due_date": "2026-11-01",    "estimated_discount": {      "value": 15000,      "currency": "KES"    },    "estimated_payout": {      "value": 485000,      "currency": "KES"    }  },  "funding": {    "disbursement_id": "550e8400-e29b-41d4-a716-446655440000",    "status": "PENDING",    "facility_account_id": "550e8400-e29b-41d4-a716-446655440000",    "transaction_id": "0fec1e58-b197-4052-99cf-2218496c5482",    "authorized_at": "2026-09-01T10:15:30Z",    "failure_reason": "Account limit exceeded"  }}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

List invoice applications GET

Lists the merchant's invoice financing applications, paginated with `size`, `after`, and `before`. Requires the `merchant:financing.invoices:read` permission on the merchant. Returns 404 when the merchant does not belong to the caller's organization.

Get an invoice application GET

Returns one invoice application with its dated discount estimate and its payout. The payout fixes the estimate to its authorization date. Requires the `merchant:financing.invoices:read` permission on the merchant. Returns 404 when the merchant does not belong to the caller's organization, or the application does not exist for that merchant.