v2
OpenAPI 3.1.02026-07-3139137119.0 KBinvoices
Create Invoice
Creates and publishes an invoice backed by a SALE pay order. The recipient is emailed a PDF invoice with a hosted payment link. Pass id to publish an existing draft.
post/invoices
Headers
Authorization-Signaturestring required
HMAC-SHA256 signature header: 'APIKey=<api_key>,signature=<hex>,timestamp=<unix_timestamp>'. The signature is computed over METHOD + path (with the /v3 prefix stripped) + timestamp.
Request body
Example request
{
"from": {
"email": "billing@acme.com",
"name": "Acme Inc."
},
"invoice": {
"date": "2026-07-15",
"due_date": "2026-08-15",
"no": "INV-001"
},
"items": [
{
"name": "Consulting",
"quantity": "2",
"tax": "10",
"unitPrice": "100.00"
}
],
"recipient": {
"email": "jane@example.com",
"name": "Jane Doe"
}
}Response
Invoice created
Example response
{
"data": {
"from": {
"email": "billing@acme.com",
"name": "Acme Inc."
},
"invoice": {
"date": "2026-07-15",
"due_date": "2026-08-15",
"no": "INV-001"
},
"items": [
{
"name": "Consulting",
"quantity": "2",
"tax": "10",
"unitPrice": "100.00"
}
],
"recipient": {
"email": "jane@example.com",
"name": "Jane Doe"
}
},
"id": "cuidjkhg3e289y74u5t6v",
"orders": [
{
"created_at": "2023-01-01T00:00:00Z",
"fulfillment": {
"amount": {
"raw": "100000000",
"ui": "100.0",
"value_usd": 100
},
"asset": {
"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"chain_id": 1,
"decimals": 6,
"id": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48-1",
"name": "USD Coin",
"price_usd": 1,
"symbol": "USDC"
},
"custom_fee_bps": 50,
"fiat_unit": "USD",
"rate_usd": "1.00",
"recipient": "0x1234...abcd",
"swap": {
"slippage_bps": 50,
"trade_type": "EXACT_INPUT"
}
},
"hosted_url": "https://pay.coinvoyage.io/pay/cuidjkhg3e289y74u5t6v",
"id": "cuidjkhg3e289y74u5t6v",
"metadata": {
"items": [
{
"currency": "USD",
"description": "High-quality widget with extra features",
"image": "https://example.com/images/widget.png",
"name": "Premium Widget",
"quantity": 2,
"unit_price": 49.99
}
],
"refund": {
"additional_info": "Item was never shipped",
"currency": "USD",
"name": "Order Cancellation",
"reason": "Customer requested refund",
"refund_amount": 99.98
}
},
"mode": "SALE",
"organization_id": "org_123",
"payment": {
"destination_tx_hash": "0x5678...efgh",
"estimated_duration_seconds": 120,
"expires_at": "2023-01-01T00:00:00Z",
"fee_tx_hash": "0xfee1...fee2",
"input": {
"amount": {
"raw": "100000000",
"ui": "100.0",
"value_usd": 100
},
"balance": {
"raw": "100000000",
"ui": "100.0",
"value_usd": 100
},
"breakdown": {
"base": {
"raw": "100000000",
"ui": "100.0",
"value_usd": 100
},
"fees": {
"custom_fee": {
"raw": "100000000",
"ui": "100.0",
"value_usd": 100
},
"protocol_fee": {
"raw": "100000000",
"ui": "100.0",
"value_usd": 100
},
"relayer_fee": {
"raw": "100000000",
"ui": "100.0",
"value_usd": 100
},
"total_fee": {
"raw": "100000000",
"ui": "100.0",
"value_usd": 100
}
},
"gas": {
"raw": "100000000",
"ui": "100.0",
"value_usd": 100
},
"total": {
"raw": "100000000",
"ui": "100.0",
"value_usd": 100
}
},
"currency": {
"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"chain_id": 1,
"decimals": 6,
"id": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48-1",
"name": "USD Coin",
"price_usd": 1,
"symbol": "USDC"
}
},
"output": {
"amount": {
"raw": "100000000",
"ui": "100.0",
"value_usd": 100
},
"amount_out_minimum": {
"raw": "100000000",
"ui": "100.0",
"value_usd": 100
},
"currency": {
"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"chain_id": 1,
"decimals": 6,
"id": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48-1",
"name": "USD Coin",
"price_usd": 1,
"symbol": "USDC"
}
},
"payment_rail": "CRYPTO",
"recipient": "0x1234...abcd",
"refund": {
"address": "0x1234...abcd",
"reason": "execution failed: provider error",
"tx_hash": "0x9abc...ijkl"
},
"source_tx_hash": "0x1234...abcd",
"steps": [
{
"action": "swap",
"kind": "deposit",
"rail": "CRYPTO"
}
]
},
"settings": {
"card_payments": true,
"hide_footer": true
},
"status": "PENDING",
"updated_at": "2023-01-01T00:00:00Z"
}
],
"organization_id": "org_123",
"payment_url": "https://pay.coinvoyage.io/invoices/cuidjkhg3e289y74u5t6v"
}