Invoices

Create and manage invoices with automatic tax calculation and PDF generation.

Create Invoice

Create a new invoice for a customer.

Endpoint: POST /v1/pay/invoices

Authentication: Required

Request Body:

Field	Type	Required	Description
`customer_id`	string	No*	ID of existing customer
`customer_email`	string	No*	Customer email (required if `customer_id` not provided)
`customer_name`	string	No*	Customer name (required if `customer_id` not provided)
`customer_address`	string	No	Customer address
`customer_phone`	string	No	Customer phone number in E.164 format
`currency`	string	Yes	Currency code (default: `"GMD"`)
`tax_rate`	number	No	Tax rate as percentage (0-100, default: 0)
`due_date`	string	Yes	Invoice due date (ISO 8601)
`notes`	string	No	Additional notes or terms
`items`	array	Yes	Invoice items (minimum 1)
`items[].product_id`	string	No**	Product ID (auto-fills description and unit_price)
`items[].description`	string	No**	Item description (required if `product_id` not provided)
`items[].quantity`	integer	Yes	Item quantity (minimum 1)
`items[].unit_price`	string	No**	Unit price as decimal (required if `product_id` not provided)
`is_draft`	boolean	No	Create as draft (default: `false`)
`metadata`	object	No	Custom metadata

*Either customer_id or customer_email+customer_name required
**Either product_id or description+unit_price required per item

Invoice Statuses:

draft - Not finalized, can be edited

pending - Waiting for payment

paid - Fully paid

partially_paid - Partially paid

overdue - Past due date, unpaid

cancelled - Cancelled

Payment Statuses:

unpaid - No payment received

partial - Partially paid

paid - Fully paid

cancelled - Invoice cancelled

TIP

Tax Calculation: Tax is calculated automatically as tax_amount = amount * (tax_rate / 100). The total_amount = amount + tax_amount.

Example:

HTTP

TypeScript

Python

Success Response (201):

{
  "data": {
    "id": "inv_abc123",
    "invoice_number": "INV-2024-12-0001",
    "customer_id": "cus_xyz789",
    "customer_email": "customer@example.com",
    "customer_name": "John Doe",
    "amount": "1000.00",
    "tax_rate": 15,
    "tax_amount": "150.00",
    "total_amount": "1150.00",
    "paid_amount": "0.00",
    "remaining_amount": "1150.00",
    "currency": "GMD",
    "status": "pending",
    "payment_status": "unpaid",
    "payment_url": "https://pay.jokoor.com/invoice/inv_abc123",
    "pdf_url": "/v1/pay/invoices/public/inv_abc123/pdf",
    "due_date": "2024-12-31T23:59:59Z",
    "issued_date": "2024-01-15T10:30:00Z",
    "subscription_id": null,
    "mode": "test",
    "livemode": false,
    "version": 1,
    "items": [
      {
        "description": "Web development services",
        "quantity": 1,
        "unit_price": "1000.00",
        "total": "1000.00"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

INFO

Payment URL: The payment_url is only available for invoices that can be paid online:

✅ Available for: pending, partially_paid, overdue invoices

❌ Not available for: draft, paid, cancelled invoices

When available, customers can visit this URL to pay the invoice online using Wave, Afrimoney, Card, etc.

Get Invoice

Get details of a specific invoice.

Endpoint: GET /v1/pay/invoices/{id}

Authentication: Required

Example:

HTTP

TypeScript

Python

List Invoices

Get a paginated list of invoices.

Endpoint: GET /v1/pay/invoices

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
`offset`	integer	No	Number of items to skip (default: 0)
`limit`	integer	No	Maximum number of items to return (default: 20, max: 100)
`status`	string	No	Filter by status
`customer_email`	string	No	Filter by customer email
`search`	string	No	Search in invoice number or customer name

Example:

HTTP

TypeScript

Python

Update Invoice

Update an invoice (only draft or pending invoices can be updated).

Endpoint: PUT /v1/pay/invoices/{id}

Authentication: Required

Request Body:

Field	Type	Required	Description
`customer_email`	string	No	Customer email
`customer_name`	string	No	Customer name
`customer_address`	string	No	Customer address
`customer_phone`	string	No	Customer phone
`tax_rate`	number	No	Tax rate as percentage (0-100)
`due_date`	string	No	Due date (ISO 8601)
`notes`	string	No	Notes or terms
`metadata`	object	No	Custom metadata

Finalize Invoice

Convert a draft invoice to pending status.

Endpoint: POST /v1/pay/invoices/{id}/finalize

Authentication: Required

Example:

HTTP

TypeScript

Python

Send Invoice

Send an invoice to the customer via email.

Endpoint: POST /v1/pay/invoices/{id}/send

Authentication: Required

Request Body:

Field	Type	Required	Description
`message`	string	No	Optional custom message to include in the email

Example:

HTTP

TypeScript

Python

Cancel Invoice

Cancel a pending or overdue invoice.

Endpoint: POST /v1/pay/invoices/{id}/cancel

Authentication: Required

Example:

HTTP

TypeScript

Python

Download Invoice PDF

Download an invoice as a PDF file.

Endpoint: GET /v1/pay/invoices/{id}/pdf

Authentication: Required

Example:

HTTP

TypeScript

Python

Success Response (200): PDF binary data

Paying Invoices

There are two ways customers can pay invoices:

Option 1: Online Payment (Recommended for Digital Payments)

For Wave, Afrimoney, Card, and other online payment methods, customers visit the invoice payment_url which provides a hosted payment page.

How it works:

You create and send invoice to customer

Customer receives invoice with payment_url

Customer clicks the URL

Hosted page handles payment method selection and processing

Payment completes automatically

Invoice status updates to paid

Customer Experience:

Customer receives invoice email
  ↓
Clicks "Pay Invoice" → visits payment_url
  ↓
Hosted page shows invoice details
  ↓
Customer selects payment method (Wave, Afrimoney, etc.)
  ↓
Completes payment with provider
  ↓
Returns to success page

Benefits:

✅ Automatic payment processing

✅ No manual work required

✅ Instant status updates

✅ Automatic receipt generation

✅ Multiple payment methods

✅ Mobile-friendly

Option 2: Offline Payment Recording (For Manual Payments)

For cash, bank transfers, checks, and other offline methods, use the Record Invoice Payment endpoint to manually record payments received outside the platform.

How it works:

Customer pays through offline method (cash, bank transfer, etc.)

You receive the payment

You call the API to record the payment

Invoice status updates

Receipt is automatically generated

When to use:

Customer pays with cash

Customer makes bank transfer to your account

Customer pays by check

Customer uses Western Union, MoneyGram, etc.

Any payment outside Jokoor platform

Example:

HTTP

TypeScript

Python

See Record Invoice Payment for full details.

Quick Decision Guide

Payment Method	Use This Option
Wave	Option 1 (Online - `payment_url`)
Afrimoney	Option 1 (Online - `payment_url`)
Card	Option 1 (Online - `payment_url`)
QMoney	Option 1 (Online - `payment_url`)
Cash	Option 2 (Offline - record payment)
Bank Transfer	Option 2 (Offline - record payment)
Check/Cheque	Option 2 (Offline - record payment)
Western Union	Option 2 (Offline - record payment)
MoneyGram	Option 2 (Offline - record payment)

WARNING

Important: Don't mix these up!

Online payments (Wave, etc.) → Customer uses payment_url

Offline payments (cash, etc.) → You call record payment endpoint

Using the wrong method will cause confusion and payment issues.

Invoices

Create Invoice#

Get Invoice#

List Invoices#

Update Invoice#

Finalize Invoice#

Send Invoice#

Cancel Invoice#

Download Invoice PDF#

Paying Invoices#

Option 1: Online Payment (Recommended for Digital Payments)#

Option 2: Offline Payment Recording (For Manual Payments)#

Quick Decision Guide#

Create Invoice

Get Invoice

List Invoices

Update Invoice

Finalize Invoice

Send Invoice

Cancel Invoice

Download Invoice PDF

Paying Invoices

Option 1: Online Payment (Recommended for Digital Payments)

Option 2: Offline Payment Recording (For Manual Payments)

Quick Decision Guide