Create a new invoice

POST

/api/v1/invoices

Invoices

Request

Authorization

API Key

Add parameter in header

x-api-key

Example:

x-api-key: ********************

Header Params

Body Params application/json

Examples

Responses

🟢201Created

application/json

Invoice created successfully

Body

🟠400Bad Request

🟠401Unauthorized

🔴500Server Error

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST '/api/v1/invoices' \
--header 'x-business-id;' \
--header 'Idempotency-Key;' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerName": "John Doe",
    "customerEmail": "john@example.com",
    "customerPhone": "+234123456789",
    "customerAddress": "123 Main St, Lagos, Nigeria",
    "items": [
        {
            "description": "Web Development Service",
            "quantity": 2,
            "unitPrice": 50000,
            "currency": "NGN"
        },
        {
            "description": "SEO Optimization",
            "quantity": 1,
            "unitPrice": 25000,
            "currency": "NGN"
        }
    ],
    "dueDate": "2025-02-01T00:00:00Z",
    "notes": "Payment due within 30 days",
    "taxRate": 7.5,
    "discountAmount": 5000,
    "metadata": {
        "project_id": "proj_123",
        "client_type": "premium"
    }
}'

Response Example

201 - sample

{
    "success": true,
    "message": "Invoice created successfully",
    "data": {
        "id": "inv_123456",
        "invoiceNumber": "INV-202501-0001",
        "businessId": "biz_123",
        "customerName": "John Doe",
        "customerEmail": "john@example.com",
        "customerPhone": "+234123456789",
        "customerAddress": "123 Main St, Lagos, Nigeria",
        "subtotal": 125000,
        "taxAmount": 9375,
        "discountAmount": 5000,
        "totalAmount": 129375,
        "currency": "NGN",
        "status": "PENDING",
        "dueDate": "2025-02-01T00:00:00Z",
        "notes": "Payment due within 30 days",
        "paymentUrl": "https://payment.rayswap.exchange/invoice/inv_123456",
        "items": [
            {
                "id": "item_123",
                "description": "Web Development Service",
                "quantity": 2,
                "unitPrice": 50000,
                "totalPrice": 100000,
                "currency": "NGN"
            },
            {
                "id": "item_124",
                "description": "SEO Optimization",
                "quantity": 1,
                "unitPrice": 25000,
                "totalPrice": 25000,
                "currency": "NGN"
            }
        ],
        "createdAt": "2025-01-01T12:00:00Z",
        "updatedAt": "2025-01-01T12:00:00Z",
        "metadata": {
            "project_id": "proj_123",
            "client_type": "premium"
        }
    }
}

Modified at 2025-09-04 20:35:45

Reset sandbox transactions to PENDING for testing

Send invoice email to customer