POST /api/v1/items/sell-amount β Item-Line Sell Amount Retrieval
Given a Transaction Code (TRNC) and a Ticket Number, returns the matching lineβs sell_amount and document context within the tenant. Auth scheme reuses tenant + API token + Bearer JWT.
Headers
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Authorization: Bearer <JWT>
Body
{
"trnc": "TKTT", // one of: TKTT, EMDS, RFND, ADMA, ACMA, CANX, OTHER (case-insensitive)
"ticket_no": "123-4567890123", // accepts 13 digits or 3-10 hyphen; normalised internally
"status": "FINALISED", // optional: DRAFT, FINALISED, REFUNDED, VOIDED
"pnr": "ABC123", // optional, 6-char alphanumeric; if supplied must match
"customer_phone": "+94771234567" // optional, E.164; restrict search to this customer
}
Success Response
{
"ok": true,
"result": {
"sell_amount": "0.00",
"currency": "USD",
"doc_type": "INVOICE", // INVOICE | REFUND | ADM | ACM | VOID | EMD | OTHER
"doc_no": "INV-2025-00123",
"doc_date": "2025-10-07",
"status": "FINALISED",
"line_id": 12345,
"pnr": "ABC123",
"ticket_no": "123-4567890123",
"supplier": { "id": 77, "name": "SriLankan Airlines" }
}
}
Errors
- 400 unknown tenant/domain
- 401 missing/invalid API token or JWT / expired
- 403 user suspended
- 404 item line not found for given trnc/ticket_no (and filters)
- 409 multiple matches (includes candidates: doc_no, doc_date)
- 422 validation errors (bad trnc, ticket_no, status, pnr, customer_phone)
Examples
curl
curl -X POST https://tenant.example.com/api/v1/items/sell-amount \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{
"trnc":"TKTT",
"ticket_no":"123-4567890123",
"status":"FINALISED",
"pnr":"ABC123"
}'
JavaScript
fetch('https://tenant.example.com/api/v1/items/sell-amount', {
method:'POST',
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
body: JSON.stringify({ trnc:'TKTT', ticket_no:'1234567890123' })
}).then(r=>r.json()).then(console.log);
Python
import requests
payload = {'trnc':'TKTT','ticket_no':'123-4567890123','status':'FINALISED'}
r = requests.post('https://tenant.example.com/api/v1/items/sell-amount',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
json=payload)
print(r.json())
GET /api/v1/invoices/{invoice_no}/download β Download Invoice PDF
Downloads a generated PDF of the specified invoice. Same auth scheme as other v1 APIs.
Request
Method: GET
URL: /api/v1/invoices/{invoice_no}/download
Path Params:
invoice_no (required, string)
Headers:
Authorization: Bearer <JWT>
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Body: (none)
Success Response
Status: 200 OK
Headers:
Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice_{invoice_no}.pdf"
Body:
<binary pdf bytes>
Examples
curl
curl -L -X GET "https://tenant.example.com/api/v1/invoices/I000123/download" \
-H "Authorization: Bearer <jwt>" \
-H "X-API-Token: pat_ABC" \
-H "X-Tenant-Domain: tenant.example.com" \
-o invoice_123.pdf
JavaScript
fetch('https://tenant.example.com/api/v1/invoices/I000123/download', {
headers: {
'Authorization': 'Bearer <jwt>',
'X-API-Token': 'pat_ABC',
'X-Tenant-Domain': 'tenant.example.com'
}
}).then(r => r.blob()).then(b => {
const url = URL.createObjectURL(b);
const a = document.createElement('a');
a.href = url; a.download = 'invoice_I000123.pdf'; a.click();
URL.revokeObjectURL(url);
});
Python
import requests
u = 'https://tenant.example.com/api/v1/invoices/I000123/download'
h = {'Authorization':'Bearer <jwt>', 'X-API-Token':'pat_ABC', 'X-Tenant-Domain':'tenant.example.com'}
r = requests.get(u, headers=h, stream=True)
with open('invoice_I000123.pdf','wb') as f:
for chunk in r.iter_content(8192):
if chunk: f.write(chunk)
Error Codes
- 400 unknown tenant/domain
- 401 invalid/missing API token or JWT
- 403 user suspended / forbidden
- 404 invoice not found
Filenames may include the invoice number; treat the response as binary.
API Authentication
Authenticate via POST /api/v1/auth/login. Always use HTTPS.
Use the access_token from this login only. Tokens issued to the mobile app or to the customer chat widget are refused here with 401.
Request
Headers:
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Body:
{
"user email": "[email protected]",
"password": "secret"
}
Success Response
{"ok":true,"token_type":"Bearer","access_token":"","expires_in":3600,
"user":{"id":1,"email":"[email protected]","name":"Test"}}
Examples
curl
curl -X POST https://tenant.example.com/api/v1/auth/login \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{"user email":"[email protected]","password":"secret"}'
JavaScript
fetch('https://tenant.example.com/api/v1/auth/login', {
method:'POST',
headers:{
'Content-Type':'application/json',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
},
body: JSON.stringify({'user email':'[email protected]','password':'secret'})
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.post('https://tenant.example.com/api/v1/auth/login',
headers={'X-API-Token':'pat_ABC','X-Tenant-Domain':'tenant.example.com'},
json={'user email':'[email protected]','password':'secret'})
print(r.json())
Error Codes
- 400 unknown tenant
- 401 invalid token / credentials
- 403 suspended
- 422 bad email
Tokens are hashed server-side. Rotate tokens regularly.
GET /api/v1/deposits/status β Customer Deposit Status
Identify by customer phone; filter and list deposit requests.
Request
Headers:
Authorization: Bearer <jwt>
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Query Parameters:
phone (required, E.164) e.g., +12345678901
status (optional, comma list) Pending, Approved, Rejected, Cancelled
date_from (optional, YYYY-MM-DD) inclusive
date_to (optional, YYYY-MM-DD) inclusive
min_amount / max_amount (optional) decimal strings (2β3 dp, >= 0)
reference (optional) substring match (case-insensitive)
page (optional, default 1) integer, >= 1
page_size (optional, default 25) max 200
sort (optional, default -request_datetime)
allowed: request_datetime, -request_datetime, amount, -amount, status
Body
{
"phone": "+12345678901",
"status": "Pending,Approved",
"date_from": "2025-09-01",
"date_to": "2025-09-30",
"min_amount": "100.00",
"max_amount": "500.00",
"reference": "ref-",
"page": 1,
"page_size": 25,
"sort": "-request_datetime"
}
Success Response
{
"ok": true,
"customer": {"id": 42, "phone": "+12345678901", "name": "Acme Co"},
"filtered_count": 2,
"total_count": 5,
"page": 1,
"page_size": 25,
"rows": [
{
"id": 101,
"reference": "Ref-001",
"request_datetime": "2025-09-08T12:00:00+00:00",
"amount": "150.00",
"customer_name": "Acme Co",
"payment_method": "Cash",
"status": "Pending",
"approved_datetime": null
},
{
"id": 99,
"reference": "Ref-000",
"request_datetime": "2025-09-07T08:30:12+00:00",
"amount": "200.00",
"customer_name": "Acme Co",
"payment_method": "Bank Transfer",
"status": "Approved",
"approved_datetime": "2025-09-07T09:05:00+00:00"
}
],
"sum_amount_filtered": "350.00" // present when filters applied
}
Examples
curl
curl -X GET https://tenant.example.com/api/v1/deposits/status \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{
"phone":"+12345678901",
"status":"Pending,Approved",
"date_from":"2025-09-01",
"date_to":"2025-09-30"
}'
JavaScript
fetch('https://tenant.example.com/api/v1/deposits/status', {
method:'GET',
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
body: JSON.stringify({ phone:'+12345678901', status:'Approved', sort:'-amount' })
}).then(r=>r.json()).then(console.log);
Python
import requests
payload = {
'phone': '+12345678901',
'status': 'Pending,Approved',
'page': 1,
'page_size': 50
}
r = requests.get('https://tenant.example.com/api/v1/deposits/status',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
json=payload)
print(r.json())
Error Codes
- 400 unknown tenant/domain
- 401 invalid/missing API token or JWT
- 403 user suspended
- 404 customer not found
- 422 invalid query
Note: All date/times reflect tenant timezone.
GET /api/v1/customers/ledger β Customer Ledger
Identify the customer by phone and list ledger entries. Supports filters, paging and sorting.
Request
Headers:
Authorization: Bearer <jwt>
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Query Parameters:
phone (required, E.164) e.g., +12345678901
date_from (optional, YYYY-MM-DD) inclusive
date_to (optional, YYYY-MM-DD) inclusive
type (optional, comma list) INVOICE, RECEIPT, REFUND, CREDIT_NOTE, DEBIT_MEMO, CREDIT_MEMO, ADJUSTMENT, OTHER
page (optional, default 1)
page_size (optional, default 25, max 200)
sort (optional, default -date) allowed: date, -date, amount, -amount, type
Body
{
"phone": "+12345678901",
"date_from": "2025-09-01",
"date_to": "2025-09-30",
"type": "INVOICE,RECEIPT,REFUND",
"page": 1,
"page_size": 25,
"sort": "-date"
}
Success Response
{
"ok": true,
"customer": {"id": 42, "phone": "+12345678901", "name": "Acme Co"},
"currency": "USD",
"filtered_count": 3,
"total_count": 10,
"page": 1,
"page_size": 25,
"rows": [
{
"id": 501,
"date": "2025-09-08T00:00:00+00:00",
"type": "INVOICE",
"doc_no": "INV-000123",
"doc_url": "https://tenant.example.com/invoices/pdf/123",
"pnr": "ABC123",
"ticket_no": "1234567890123",
"debit": "150.00",
"credit": "0.00"
},
{
"id": 845,
"date": "2025-09-07T00:00:00+00:00",
"type": "RECEIPT",
"doc_no": "R00045",
"doc_url": "https://tenant.example.com/receipts/pdf/45",
"pnr": null,
"ticket_no": null,
"debit": "0.00",
"credit": "150.00"
},
{
"id": 877,
"date": "2025-09-06T00:00:00+00:00",
"type": "REFUND",
"doc_no": "RN-0005",
"doc_url": "https://tenant.example.com/refund-notes/pdf/5",
"pnr": null,
"ticket_no": null,
"debit": "0.00",
"credit": "50.00"
}
],
"sum_debit_filtered": "150.00",
"sum_credit_filtered": "200.00"
}
Errors
- 400 unknown tenant/domain
- 401 invalid/missing API token or JWT
- 403 user suspended
- 404 customer not found
- 422 invalid query
Note: Times reflect tenant timezone; amounts in tenant currency.
POST /api/v1/customers/fees - Customer Fee List
Identify the customer by phone and list the tenantβs customer fee definitions. This returns fee metadata, not transactions.
Headers
Authorization: Bearer <JWT>
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Content-Type: application/json
Body
{
"phone": "+12345678901", // required, E.164
"code": "CF" // optional, 2-letter filter, case-insensitive
}
Response
{
ok: true,
customer: { id, phone, name },
rows: [
{
name: string, // Fee name
code: string, // 2-letter code
default_amount: string, // 2 decimals (tenant currency)
description: string|null
}
]
}
Errors
- 400 unknown tenant/domain
- 401 missing/invalid API token or JWT / expired token
- 403 user suspended
- 404 customer not found
- 422 invalid query (phone)
Examples
curl
curl -X POST https://tenant.example.com/api/v1/customers/fees \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{
"phone": "+12345678901",
"code": "CF"
}'
JavaScript
fetch('https://tenant.example.com/api/v1/customers/fees', {
method:'POST',
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
body: JSON.stringify({ phone: '+12345678901', code: 'CF' })
}).then(r=>r.json()).then(console.log);
Python
import requests
payload = { 'phone': '+12345678901', 'code': 'CF' }
r = requests.post('https://tenant.example.com/api/v1/customers/fees',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
json=payload)
print(r.json())
Tickets API (Staff)
Create and manage tickets via the API. Uses staff authentication (Bearer JWT) plus tenant API token. These endpoints are separate from customer-chat APIs.
Auth
Headers:
Authorization: Bearer <jwt>
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
POST /api/v1/tickets
Create a new ticket. Accepts JSON or multipart form data (attachments).
Body (JSON):
{
"subject": "Payment issue",
"description": "Customer reports a failed payment.",
"priority": "high",
"category_id": 3,
"customer_id": 42, // or use customer_phone + name/email
"customer_phone": "+12345678901",
"customer_name": "Acme Co",
"customer_email": "[email protected]",
"department_id": 2,
"assigned_to_id": 7,
"cc_user_ids": [5, 9]
}
Response:
{
"ok": true,
"ticket": { ... },
"permissions": { "canView": true, "canManage": true, "canComment": true },
"lastSync": "2026-01-23T12:34:56.000000"
}
GET /api/v1/tickets
List tickets visible to the authenticated staff user.
Query params:
status (optional, comma list) open,in_progress,resolved,closed
priority (optional, comma list) low,medium,high,urgent
assigned_to (optional) user id or "unassigned"
q (optional) search term (subject/reference/contact)
Response:
{
"ok": true,
"tickets": [ ... ],
"summary": {
"counts": { "open": 2, "in_progress": 1, "resolved": 0, "closed": 5 },
"priorities": [ { "value": "low", "label": "Low" }, ... ],
"statuses": [ { "value": "open", "label": "Open" }, ... ]
}
}
GET /api/v1/tickets/<ticket_id>
View a single ticket and its thread.
Response:
{
"ok": true,
"ticket": { ... },
"permissions": { "canView": true, "canManage": false, "canComment": true },
"lastSync": "2026-01-23T12:34:56.000000"
}
PATCH /api/v1/tickets/<ticket_id>
Update ticket status and/or add a reply.
Body (JSON):
{
"status": "resolved", // optional
"reply": "Issue resolved. Please confirm." // optional
}
Supports multipart form data with attachments when sending a reply.
Errors
- 400 validation errors
- 401 missing/invalid API token or JWT
- 403 forbidden / suspended / tickets feature disabled
- 404 ticket not found
- 409 duplicate ticket
Example (curl)
curl -X POST https://tenant.example.com/api/v1/tickets \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{
"subject":"Payment issue",
"description":"Customer reports a failed payment.",
"priority":"high",
"category_id":3,
"customer_phone":"+12345678901"
}'
Customer Chat APIs
Enable an embedded customer support experience by issuing a customer-chat JWT and using the chat ticket endpoints.
These APIs power /tickets/customer-chat/frame, which can be embedded as an iframe or React component.
POST /api/v1/customer-chat/login
Issue a chat JWT for a single customer. Requires the tenant API token.
Headers:
X-Tenant-Domain: tenant.example.com
X-API-Token: pat_xxx
Body (JSON):
{
"phone": "+12345678901",
"email": "[email protected]" // optional verification
}
Response:
{
"ok": true,
"message": "Customer chat login successful",
"token": "...",
"token_type": "Bearer",
"expires_in": 21600,
"customer": { ... },
"company": { ... }
}
POST /api/v1/customer-chat/tickets
Create a new support ticket on behalf of the authenticated customer. Supports JSON or multipart bodies (for attachments).
Headers:
Authorization: Bearer <chat-jwt>
X-Tenant-Domain: tenant.example.com # optional
Body (multipart/form-data):
subject=Issue with invoice
message=My latest invoice looks incorrect.
[email protected]
Response:
{
"ticket": { ... },
"lastSync": "2025-10-23T09:05:08.123456"
}
GET /api/v1/customer-chat/tickets
List tickets that belong to the authenticated customer.
curl https://tenant.example.com/api/v1/customer-chat/tickets \
-H "Authorization: Bearer <chat-jwt>"
GET /api/v1/customer-chat/tickets/<ticket_id>
Fetch ticket metadata and the latest conversation history.
GET /api/v1/customer-chat/tickets/<ticket_id>/messages
Poll for new messages using ?since=<ISO timestamp>.
POST /api/v1/customer-chat/tickets/<ticket_id>/messages
Send a customer reply (supports text + attachments).
curl -X POST https://tenant.example.com/api/v1/customer-chat/tickets/101/messages \
-H "Authorization: Bearer <chat-jwt>" \
-F message="Thanks, please advise" \
-F [email protected]
GET /api/v1/customer-chat/attachments/<attachment_id>
Download an attachment visible to the customer.
Embedding the frame
Load the frame with the customer JWT:
<iframe
src="https://tenant.example.com/tickets/customer-chat/frame?token=<chat-jwt>"
style="width:100%;height:600px;border:0;"
title="Support chat"></iframe>
Or configure via window.CustomerChatConfig before the scripts load:
<script>
window.CustomerChatConfig = {
token: '<chat-jwt>',
apiBase: '/api/v1/customer-chat',
pollInterval: 4000
};
</script>
POST /api/v1/airline-commissions β Airline Commission Settings
List tenant Airline Commission Settings with optional filters for VC and Origin. This endpoint accepts JSON body parameters and supports query strings for compatibility. Existing clients can continue using commission_percent; newer additive fields describe the customer commission rule configuration.
Headers
Authorization: Bearer <jwt>
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Content-Type: application/json
Body
{
"vc": "EK", // optional, two-letter IATA
"origin": "CMB", // optional, three-letter IATA (alias: origin_point)
"customer_phone": "+94770000000", // optional, accepted for compatibility
"q": "Direct", // optional, search channel/VC/origin
"page": 1, // optional, default 1
"page_size": 25 // optional, default 25, max 200
}
Success Response
{
"ok": true,
"page": 1,
"page_size": 25,
"total_count": 2,
"rows": [
{
"id": 12,
"channel": "Direct",
"vc": "EK",
"origin_point": "CMB",
"commission_percent": "5.50",
"applies_to_all_customers": true,
"commission_action": "MARKUP",
"commission_mode": "PERCENT",
"commission_value": "5.50",
"fm_percent": "2.00",
"applicable_for_yq": false,
"created_at": "2025-09-13T10:00:00Z",
"updated_at": "2025-09-13T11:00:00Z"
}
]
}
Response Notes
commission_percent
Backward-compatible field for existing API consumers.
applies_to_all_customers
true when the rule applies to all customers.
commission_action
"MARKUP" or "DISCOUNT"
commission_mode
"PERCENT" or "FIXED"
commission_value
Numeric rule value as a string with 2 decimals.
fm_percent
Airline-side FM percentage stored on the rule.
applicable_for_yq
true when the airline-side commission setting is marked applicable for YQ.
Examples
curl
curl -X POST https://tenant.example.com/api/v1/airline-commissions \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{
"vc":"EK",
"origin":"CMB",
"customer_phone":"+94770000000",
"page":1,
"page_size":25
}'
JavaScript
fetch('https://tenant.example.com/api/v1/airline-commissions', {
method: 'POST',
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
body: JSON.stringify({ vc:'EK', origin:'CMB', customer_phone:'+94770000000', page:1, page_size:25 })
}).then(r=>r.json()).then(console.log);
Python
import requests
payload = {'vc':'EK','origin':'CMB','customer_phone':'+94770000000','page':1,'page_size':25}
r = requests.post('https://tenant.example.com/api/v1/airline-commissions',
json=payload,
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
})
print(r.json())
VC must be exactly two uppercase letters; origin exactly three uppercase letters. customer_phone is optional; when provided, customer-specific rules are filtered for that customer and all-customer rules remain visible. Without customer_phone, only all-customer rules are returned. Parameters are accepted via JSON body; query strings are also supported for compatibility. The endpoint remains backward compatible and does not require any new request fields.
POST /api/v1/invoice-lines/void β Void Invoice Line
Void a single invoice line (Air Ticket only). Optionally create a void fee invoice.
Request
Headers:
Authorization: Bearer <jwt>
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Body (identify by phone + invoice + ticket):
{
"phone": "+12345678901", // required, E.164
"invoice_no": "INV-001234", // required (alias: invoice_number)
"ticket_no": "1234567890123", // required (10β13 digits or 3-10 pattern)
"no_void_invoice": false, // optional; if true, no fee invoice is created
"void_fee": "25.00" // optional; when creating fee invoice
}
Legacy (still supported):
{
"line_id": 12345,
"no_void_invoice": false,
"void_fee": "25.00"
}
Success Response
{
"ok": true,
"voided_line": {"id": 12345, "status": "Voided"},
"invoice": {"id": 6789, "number": "INV-001234", "total_amount": "0.00"},
"void_fee_invoice": {"id": 6790, "number": "INV-001235"}, // NEW invoice created for the void fee; null if no fee invoice was created
"references": {
"reversal_reference": "VOID-INV-001234-12345",
"allocation_reference": "ALLOC-INV-001234" // if excess payment was moved to unallocated
}
}
When a void fee invoice is created, void_fee_invoice contains the newly created invoice's id and number β quote this new invoice number back to the customer when confirming the void. When no_void_invoice is true (or no fee applies), void_fee_invoice is null.
Examples
curl
curl -X POST https://tenant.example.com/api/v1/invoice-lines/void \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{
"phone": "+12345678901",
"invoice_no": "INV-001234",
"ticket_no": "1234567890123",
"no_void_invoice": false,
"void_fee": "25.00"
}'
JavaScript
fetch('https://tenant.example.com/api/v1/invoice-lines/void', {
method:'POST',
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
body: JSON.stringify({
phone: '+12345678901',
invoice_no: 'INV-001234',
ticket_no: '1234567890123',
no_void_invoice: false,
void_fee: '25.00'
})
}).then(r=>r.json()).then(console.log);
Python
import requests
payload = {
'phone': '+12345678901',
'invoice_no': 'INV-001234',
'ticket_no': '1234567890123',
'no_void_invoice': False,
'void_fee': '25.00'
}
r = requests.post('https://tenant.example.com/api/v1/invoice-lines/void',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
json=payload)
print(r.json())
Errors
- 400 unknown tenant/domain
- 401 invalid/missing API token or JWT
- 403 user suspended
- 404 customer / invoice / invoice line not found
- 422 invalid request (phone / ticket_no / void_fee) or non-Air Ticket line
List Customers
Use GET /api/v1/customers with a valid JWT and API token.
Returns customers for the authenticated tenant only. Supports pagination, search and simple filters.
Request
Headers:
Authorization: Bearer <jwt>
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Query:
page=1
per_page=20 (max 100)
q=John (optional: name, business name, email, phone or customer code)
is_active=true (optional: true or false)
customer_type=Customer (optional: Customer, Agent or Corporate)
Body:
(none)
Success Response
{
"ok": true,
"customers": [
{
"id": 1,
"customer_type": "Customer",
"customer_name": "John Doe",
"full_name": "John Doe",
"business_name": "",
"customer_code": "ABCD",
"phone": "+12345678901",
"email": "[email protected]",
"is_active": true,
"due_term": 0,
"created_at": "2026-06-28T10:00:00"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 1,
"total_pages": 1
}
}
Examples
curl
curl -G https://tenant.example.com/api/v1/customers \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
--data-urlencode "page=1" \
--data-urlencode "per_page=20" \
--data-urlencode "q=John" \
--data-urlencode "is_active=true" \
--data-urlencode "customer_type=Customer"
JavaScript
const params = new URLSearchParams({
page: '1',
per_page: '20',
q: 'John',
is_active: 'true',
customer_type: 'Customer'
});
fetch(`https://tenant.example.com/api/v1/customers?${params}`, {
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
}
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.get('https://tenant.example.com/api/v1/customers',
params={'page':1,'per_page':20,'q':'John','is_active':'true','customer_type':'Customer'},
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
})
print(r.json())
Error Codes
- 400 unknown tenant/domain
- 401 invalid token / unauthorized
- 403 forbidden or suspended
- 422 invalid filter value
Create Customer
Use POST /api/v1/customers with a valid JWT and API token.
Customers created via this endpoint are automatically synced to the tenant's Head Office and all sibling branches under the same HO. If the automatic sync fails, the response still returns 201 but includes a warning field β the record can be retried via the tenant's manual Sync button.
Request Fields
| Field | Type | Required | Notes |
|---|---|---|---|
| customer_type | string | Yes | Customer, Agent, or Corporate |
| customer_name | string | Yes | 1β200 characters |
| phone | string | Yes | E.164 format, e.g. +12345678901 |
| string | Yes | Valid email address | |
| business_registration_no | string | Conditional | Agent/Corporate only. Required when credit_limit > 0 |
| credit_limit | number | No | Agent/Corporate only. Must be ≥ 0. Requires business_registration_no when > 0 |
Request
Headers:
Authorization: Bearer <jwt>
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Body (Customer type):
{
"customer_type": "Customer",
"customer_name": "John Doe",
"phone": "+12345678901",
"email": "[email protected]"
}
Body (Agent type with credit limit):
{
"customer_type": "Agent",
"customer_name": "Acme Travels",
"phone": "+12345678902",
"email": "[email protected]",
"business_registration_no": "REG-001234",
"credit_limit": 5000
}
Success Response
{
"ok": true,
"message": "Customer created",
"customer": {
"id": 1,
"customer_type": "Agent",
"customer_name": "Acme Travels",
"customer_code": "ACME",
"phone": "+12345678902",
"email": "[email protected]",
"business_registration_no": "REG-001234",
"credit_limit": "5000.00"
}
}
warning (string, optional) is only present when the automatic HO/branch sync failed; it is omitted on full success:
{
"ok": true,
"message": "Customer created",
"customer": { ... },
"warning": "Customer saved, but auto-sync to branches failed β use the Sync button to retry."
}
Examples
curl
curl -X POST https://tenant.example.com/api/v1/customers \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{"customer_type":"Agent","customer_name":"Acme Travels","phone":"+12345678902","email":"[email protected]","business_registration_no":"REG-001234","credit_limit":5000}'
JavaScript
fetch('https://tenant.example.com/api/v1/customers', {
method:'POST',
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
body: JSON.stringify({
customer_type:'Agent',
customer_name:'Acme Travels',
phone:'+12345678902',
email:'[email protected]',
business_registration_no:'REG-001234',
credit_limit:5000
})
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.post('https://tenant.example.com/api/v1/customers',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
},
json={
'customer_type':'Agent',
'customer_name':'Acme Travels',
'phone':'+12345678902',
'email':'[email protected]',
'business_registration_no':'REG-001234',
'credit_limit':5000
})
print(r.json())
Validation Rules
credit_limitcan only be set forAgentorCorporatecustomer types.- When
credit_limit > 0,business_registration_nomust be provided. business_registration_nois stored only forAgentandCorporatetypes.
Error Codes
- 400 unknown tenant
- 401 invalid token / unauthorized
- 403 forbidden
- 409 duplicate phone
- 422 validation errors (see
errorsobject in response)
Create Supplier
Use POST /api/v1/suppliers/create with a valid JWT and API token.
Suppliers created via this endpoint are automatically synced to the tenant's Head Office and all sibling branches under the same HO. If the automatic sync fails, the response still returns 201 but includes a warning field β the record can be retried via the tenant's manual Sync button.
Request Fields
| Field | Type | Required | Notes |
|---|---|---|---|
| business_name | string | Yes | Supplier's business name |
| phone | string | Yes | Any parseable phone number (defaults to LK region), normalized to E.164 |
| string | No | Valid email address |
Request
Headers:
Authorization: Bearer <jwt>
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Body:
{
"business_name": "Acme Supplies",
"phone": "+94771234567",
"email": "[email protected]"
}
Success Response
{
"id": 1,
"business_name": "Acme Supplies",
"phone_number": "+94771234567",
"supplier_code": "SUP0001"
}
warning (string, optional) is only present when the automatic HO/branch sync failed; it is omitted on full success:
{
"id": 1,
"business_name": "Acme Supplies",
"phone_number": "+94771234567",
"supplier_code": "SUP0001",
"warning": "Supplier saved, but auto-sync to branches failed β use the Sync button to retry."
}
Examples
curl
curl -X POST https://tenant.example.com/api/v1/suppliers/create \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{"business_name":"Acme Supplies","phone":"+94771234567","email":"[email protected]"}'
JavaScript
fetch('https://tenant.example.com/api/v1/suppliers/create', {
method:'POST',
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
body: JSON.stringify({
business_name:'Acme Supplies',
phone:'+94771234567',
email:'[email protected]'
})
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.post('https://tenant.example.com/api/v1/suppliers/create',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
},
json={
'business_name':'Acme Supplies',
'phone':'+94771234567',
'email':'[email protected]'
})
print(r.json())
Error Codes
- 400 unknown tenant/domain, missing fields, or invalid phone number
- 401 invalid token
- duplicate business name or phone returns 400 with
"error": "supplier already exists"
Customer Wallet Summary
Use GET /api/v1/customers/wallet with a valid JWT and API token.
Retrieve wallet IDs, balances and credit limit details for a customer by phone.
Request
Headers:
Authorization: Bearer <jwt>
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Query:
phone=+94771234567 (E.164)
Body:
(none)
Success Response
{
"ok": true,
"currency": "USD",
"credit_wallet": {
"wallet_id": "TBO12341",
"balance": "-100.00",
"currency": "USD",
"credit_limit": "500.00",
"remaining_limit": "400.00",
"credit_limit_expiry": "2025-08-01T00:00:00"
},
"prepaid_wallet": {
"wallet_id": "TBO12342",
"balance": "50.00",
"currency": "USD"
}
}
Examples
curl
curl -G https://tenant.example.com/api/v1/customers/wallet \
-H "Authorization: Bearer <jwt>" \
-H "X-API-Token: pat_ABC" \
-H "X-Tenant-Domain: tenant.example.com" \
--data-urlencode "phone=+94771234567"
JavaScript
fetch('https://tenant.example.com/api/v1/customers/wallet?phone=+94771234567', {
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
}
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.get('https://tenant.example.com/api/v1/customers/wallet',
params={'phone':'+94771234567'},
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
})
print(r.json())
Error Codes
- 400 unknown tenant
- 401 invalid token / unauthorized
- 403 suspended
- 422 invalid phone
- 404 customer not found
Supplier Lookup
Use GET /api/v1/suppliers/lookup with a valid JWT and API token.
Look up a single supplier by either phone or supplier_identification_no and get back the full supplier record, including its markup settings.
Note: suppliers only have a markup/markup_type setting ("percent" or "fixed") β there is no separate "discount" field in this system.
Query Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
| phone | string | One of phone / supplier_identification_no | Exact match against the supplier's phone number. Takes precedence if both params are given. |
| supplier_identification_no | string | One of phone / supplier_identification_no | Exact match against the supplier's identification number. |
Request
Headers:
Authorization: Bearer <jwt>
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Query:
phone=+94771234567
(or)
supplier_identification_no=SUP-ID-0001
Body:
(none)
Success Response
{
"ok": true,
"supplier": {
"id": 12,
"supplier_code": "SUP0012",
"business_name": "Example Airlines",
"supplier_type": "Airlines",
"phone_number": "+94771234567",
"email": "[email protected]",
"supplier_identification_no": "SUP-ID-0001",
"address_line_1": "123 Main St",
"address_line_2": "",
"city": "Colombo",
"country": "Sri Lanka",
"due_term": 30,
"markup": 5.0,
"markup_type": "percent",
"is_reconcilable": true,
"auto_reconcile": false,
"reconcile_time": null,
"unreconciled_balance": 0.0,
"is_active": true,
"auto_due_alert": false,
"email_verified": false,
"created_at": "2025-01-15T09:30:00",
"global_supplier_id": 4,
"branch_supplier_reference": "GSUP0004",
"supplier_sync_status": "Synced"
}
}
Examples
curl
curl -G https://tenant.example.com/api/v1/suppliers/lookup \
-H "Authorization: Bearer <jwt>" \
-H "X-API-Token: pat_ABC" \
-H "X-Tenant-Domain: tenant.example.com" \
--data-urlencode "phone=+94771234567"
JavaScript
fetch('https://tenant.example.com/api/v1/suppliers/lookup?phone=+94771234567', {
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
}
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.get('https://tenant.example.com/api/v1/suppliers/lookup',
params={'supplier_identification_no': 'SUP-ID-0001'},
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
})
print(r.json())
Error Codes
- 400 unknown tenant/domain
- 401 invalid token / unauthorized
- 403 forbidden / suspended
- 422 phone or supplier_identification_no is required
- 404 supplier not found
Branch Limit
Use GET /api/v1/branch/limit with a valid JWT and API token.
Returns the current tenant branch credit limit, total debtor outstanding, and available limit.
available_limit = max(branch_credit_limit - total_debtors_due, 0)
Request
Headers:
Authorization: Bearer <jwt>
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Body:
(none)
Success Response
{
"ok": true,
"branch": {
"company_id": 57,
"name": "Valorian-journeys",
"domain": "valorian-journeys.thetravelbo.com",
"branch_code": "VALORIP6"
},
"currency": "LKR",
"branch_credit_limit": "100000.00",
"total_debtors_due": "25000.00",
"available_limit": "75000.00"
}
Examples
curl
curl -X GET https://tenant.example.com/api/v1/branch/limit \
-H "Authorization: Bearer <jwt>" \
-H "X-API-Token: pat_ABC" \
-H "X-Tenant-Domain: tenant.example.com"
JavaScript
fetch('https://tenant.example.com/api/v1/branch/limit', {
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
}
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.get('https://tenant.example.com/api/v1/branch/limit',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
})
print(r.json())
Error Codes
- 400 unknown tenant/domain
- 401 invalid token / unauthorized
- 403 forbidden / suspended
Credit Limit Request
A customer asks for a credit limit from the customer portal / chat app. The request goes to the Head Office of the company the customer logged in to, where it is approved or rejected (see Credit Limit Approval).
Authenticate with the customer-chat JWT from POST /api/v1/customer-chat/login (see Customer Chat).
- Only Agent or Corporate customers with a Business Registration No can request a limit.
- A customer can have only one
Pendingrequest at a time. - Status:
Pending→Approved|Rejected|Cancelled.
POST /api/v1/customer-chat/credit-limit/requests
Create a request.
Headers:
Authorization: Bearer <chat-jwt>
Content-Type: application/json
Body:
{
"requested_limit": 500000, // required, greater than 0
"requested_expiry": "2027-01-31 18:00", // optional, YYYY-MM-DD HH:MM (local time), later than now -- today is fine;
// a date alone means the end of that day (23:59:59)
"reason": "Peak season bookings" // optional
}
Response (201):
{
"ok": true,
"request": {
"id": 12,
"status": "Pending",
"customer_id": 10,
"customer_code": "ACME",
"customer_name": "Acme Travels",
"company_id": 32,
"current_limit": null,
"requested_limit": "500000.00",
"requested_expiry": "2027-01-31T18:00:00",
"reason": "Peak season bookings",
"approved_limit": null,
"approved_expiry": null,
"decided_by": null,
"decided_at": null,
"decision_note": null,
"created_at": "2026-11-05T09:15:02"
}
}
GET /api/v1/customer-chat/credit-limit/requests
The customer's current limit and their requests, newest first.
Headers:
Authorization: Bearer <chat-jwt>
Response:
{
"ok": true,
"current_limit": "300000.00",
"current_expiry": "2027-01-31T18:00:00",
"requests": [ { ...request... } ]
}
POST /api/v1/customer-chat/credit-limit/requests/<id>/cancel
Cancel the customer's own Pending request.
Headers:
Authorization: Bearer <chat-jwt>
Response:
{ "ok": true, "request": { ...request, "status": "Cancelled"... } }
Examples
curl
curl -X POST https://tenant.example.com/api/v1/customer-chat/credit-limit/requests \
-H "Authorization: Bearer <chat-jwt>" \
-H "Content-Type: application/json" \
-d '{"requested_limit": 500000, "requested_expiry": "2027-01-31 18:00", "reason": "Peak season bookings"}'
JavaScript
fetch('https://tenant.example.com/api/v1/customer-chat/credit-limit/requests', {
method:'POST',
headers:{
'Authorization':'Bearer <chat-jwt>',
'Content-Type':'application/json'
},
body: JSON.stringify({requested_limit: 500000, requested_expiry: '2027-01-31 18:00', reason: 'Peak season bookings'})
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.post('https://tenant.example.com/api/v1/customer-chat/credit-limit/requests',
headers={'Authorization':'Bearer <chat-jwt>'},
json={'requested_limit': 500000, 'requested_expiry': '2027-01-31 18:00', 'reason': 'Peak season bookings'})
print(r.json())
Error Codes
- 400 requested_limit required / must be a number / must be greater than 0
- 400 requested_expiry must be a date and time (YYYY-MM-DD HH:MM) / must be later than now
- 400 Credit limits are only for Agent or Corporate customers
- 400 A Business Registration No is needed on the customer
- 401 unauthorized (missing or expired chat JWT)
- 404 Request not found (cancel)
- 409 Request #id is still waiting for a decision / is already Approved, Rejected or Cancelled
Credit Limit Approval
Head Office staff list the credit limit requests of the whole network (Head Office and every branch) and approve or reject them. The same can be done in the app on Customers → Credit Limit Requests.
- Log in with a Head Office user. A branch login gets
403 Credit limits are approved at Head Office. - The user's role needs the Approve / Reject actions on the Credit Limit Requests page (Permissions screen). They are blocked until granted.
- Approving sets the credit limit and expiry on the Head Office customer and syncs it to every branch. The approver may approve a different amount or expiry than requested.
Headers (all endpoints)
Authorization: Bearer <jwt>
X-API-Token: pat_xxx
X-Tenant-Domain: ho.example.com
Content-Type: application/json
GET /api/v1/credit-limit/requests
Optional query status: Pending, Approved, Rejected or Cancelled (all when omitted).
GET /api/v1/credit-limit/requests?status=Pending
Response:
{
"ok": true,
"requests": [
{
"id": 12,
"status": "Pending",
"company_id": 32,
"company_name": "Kurunagala",
"customer_id": 10,
"customer_code": "ACME",
"customer_name": "Acme Travels",
"current_limit": null,
"requested_limit": "500000.00",
"requested_expiry": "2027-01-31T18:00:00",
"reason": "Peak season bookings",
...
}
]
}
GET /api/v1/credit-limit/requests/<id>
One request: {"ok": true, "request": { ... }}.
POST /api/v1/credit-limit/requests/<id>/approve
Body (all optional):
{
"approved_limit": 300000, // defaults to the requested limit
"expiry": "2027-01-31 18:00", // YYYY-MM-DD HH:MM, later than now (today is fine); omit for no expiry
"note": "Start lower, review in January"
}
Response:
{
"ok": true,
"synced_to_branches": true, // false: saved at Head Office; retry the branch sync with the customer's Sync button
"request": {
"id": 12,
"status": "Approved",
"requested_limit": "500000.00",
"approved_limit": "300000.00",
"approved_expiry": "2027-01-31T18:00:00",
"decided_by": "HO Admin",
"decided_at": "2026-11-05T10:02:44",
"decision_note": "Start lower, review in January",
...
}
}
POST /api/v1/credit-limit/requests/<id>/reject
Body:
{ "note": "Too high for current trading" } // required
Response:
{ "ok": true, "request": { ..., "status": "Rejected", "decision_note": "Too high for current trading" } }
Examples
curl
curl -X POST https://ho.example.com/api/v1/credit-limit/requests/12/approve \
-H "Authorization: Bearer <jwt>" \
-H "X-API-Token: pat_ABC" \
-H "X-Tenant-Domain: ho.example.com" \
-H "Content-Type: application/json" \
-d '{"approved_limit": 300000, "expiry": "2027-01-31 18:00"}'
JavaScript
fetch('https://ho.example.com/api/v1/credit-limit/requests?status=Pending', {
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'ho.example.com'
}
}).then(r=>r.json()).then(console.log);
Python
import requests
h = {'Authorization':'Bearer <jwt>', 'X-API-Token':'pat_ABC', 'X-Tenant-Domain':'ho.example.com'}
r = requests.post('https://ho.example.com/api/v1/credit-limit/requests/12/reject',
headers=h, json={'note': 'Too high for current trading'})
print(r.json())
Error Codes
- 400 unknown tenant/domain
- 400 status must be one of Pending, Approved, Rejected, Cancelled
- 400 approved_limit must be a number / expiry must be later than now / A note is required to reject a request
- 401 invalid token / unauthorized
- 403 Credit limits are approved at Head Office / forbidden (no Approve or Reject permission) / suspended
- 404 Request not found
- 409 Request #id is already Approved / Rejected / Cancelled
- 409 This customer is not linked to a Head Office customer yet -- sync it to Head Office first
- 503 Head Office database is not reachable
Create Deposit Request
Use POST /api/v1/deposit-requests/create with a valid JWT and API token.
Valid cash_bank_id values come from Bank and Cash List; valid payment_method values come from Payment Methods.
Request
Headers:
Authorization: Bearer <jwt>
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Body:
{
"customer_phone": "+12345678901",
"wallet_id": "TBOXYZ12", // one of customer's wallet IDs (outstanding or unallocated)
"cash_bank_id": 5, // preferred: Cash/Bank record id (active)
// or
// "account_id": 2, // fallback: underlying account id (must map to an active Cash/Bank)
"payment_method": "Cash",
"amount": "100.00",
"deposit_date": "2024-05-01",
"reference": "Ref123"
}
Notes:
- Phone is sanitized to E.164; avoid hidden characters from copy/paste.
- Either wallet_id or legacy wallet_type ("due" | "unallocation") is accepted; wallet_id preferred.
- Currency defaults to tenant currency when omitted.
Success Response
{"ok":true,"deposit_request":{"id":1,"status":"Submitted","customer_id":1,"amount":"100.00","currency":"USD"}}
Examples
curl
curl -X POST https://tenant.example.com/api/v1/deposit-requests/create \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{"customer_phone":"+12345678901","wallet_id":"TBOXYZ12","cash_bank_id":5,"payment_method":"Cash","amount":"100.00"}'
JavaScript
fetch('https://tenant.example.com/api/v1/deposit-requests/create', {
method:'POST',
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
body: JSON.stringify({
customer_phone:'+12345678901',
wallet_id:'TBOXYZ12',
cash_bank_id:5,
payment_method:'Cash',
amount:'100.00'
})
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.post('https://tenant.example.com/api/v1/deposit-requests/create',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
json={
'customer_phone':'+12345678901',
'wallet_id':'TBOXYZ12',
'cash_bank_id':5,
'payment_method':'Cash',
'amount':'100.00'
})
print(r.json())
Error Codes
- 400 unknown tenant/domain
- 401 invalid/missing API token or JWT
- 403 user suspended
- 404 customer not found / account not found
- 422 validation errors
Batch Deposit Request (one bank deposit, multiple customers)
Use POST /api/v1/deposit-requests/create-batch with a valid JWT and API token.
Records one physical bank deposit that belongs to several customers. One deposit request is created per
customer entry, all sharing a generated batch_id, bank account, date and reference. On approval,
the batch posts one bank debit for the total while keeping separate customer receipts and customer ledger
entries for each customer.
Valid cash_bank_id values come from Bank and Cash List; valid payment_method values come from Payment Methods.
Request
Headers:
Authorization: Bearer <jwt>
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Body:
{
"cash_bank_id": 5, // preferred: Cash/Bank record id (active)
// or
// "account_id": 2, // fallback: underlying account id (must map to an active Cash/Bank)
"payment_method": "Bank Deposit",
"deposit_date": "2024-05-01", // optional, defaults to today
"reference": "DEP-8891", // shared by all created deposit requests
"total_amount": "1500.00", // must equal the sum of customer amounts
"customers": [ // 1 to 50 entries, no duplicate phones
{
"customer_phone": "+12345678901",
"wallet_id": "TBOXYZ12",
"amount": "1000.00",
"allocations": [ // optional; omitted means customer-scoped FIFO
{ "invoice_number": "INV001", "amount": "750.00" }
]
},
{ "customer_phone": "+12345678902", "wallet_type": "unallocation", "amount": "500.00" }
]
}
Notes:
- The sum of all customer amounts must exactly equal total_amount, otherwise 422.
- All-or-nothing: if any customer entry is invalid (unknown phone, duplicate,
inactive wallet, bad amount), no deposit requests are created.
- Per customer, either wallet_id or legacy wallet_type ("due" | "unallocation")
is accepted; wallet_id preferred.
- allocations is optional and is supported only for due wallets. Every invoice must
belong to that customer, have an outstanding balance, and cannot be duplicated or
over-allocated. The allocation total cannot exceed the customer amount; any remainder
is held in that customer's unallocated wallet.
- When allocations is omitted, the due payment retains customer-scoped FIFO allocation.
- payment_method "Cheque" requires cheque_no, which becomes the shared reference.
- Currency defaults to tenant currency when omitted.
- Approving any pending request in the batch approves the whole pending batch.
- Receipt ids are assigned only after approval; the create response returns request ids and batch_id.
- The staff Deposit Requests approval screen shows one approval row per batch_id.
- Each receipt displays only its own CustomerReceiptLine allocations; other customers
sharing the batch journal never appear on that receipt, PDF, or emailed PDF.
- source_company_id is supported for inter-tenant (Head Office bank) deposits,
with the same semantics as Create Deposit Request.
Success Response
{
"ok": true,
"batch_id": "BDR-0C4F2D9A8B7E6A10",
"total_amount": "1500.00",
"count": 2,
"deposit_requests": [
{"id": 101, "status": "Pending", "customer_id": 7, "amount": "1000.00", "currency": "USD"},
{"id": 102, "status": "Pending", "customer_id": 9, "amount": "500.00", "currency": "USD"}
]
}
Examples
curl
curl -X POST https://tenant.example.com/api/v1/deposit-requests/create-batch \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{"cash_bank_id":5,"payment_method":"Bank Deposit","reference":"DEP-8891","total_amount":"1500.00","customers":[{"customer_phone":"+12345678901","wallet_id":"TBOXYZ12","amount":"1000.00"},{"customer_phone":"+12345678902","wallet_type":"unallocation","amount":"500.00"}]}'
JavaScript
fetch('https://tenant.example.com/api/v1/deposit-requests/create-batch', {
method:'POST',
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
body: JSON.stringify({
cash_bank_id:5,
payment_method:'Bank Deposit',
reference:'DEP-8891',
total_amount:'1500.00',
customers:[
{customer_phone:'+12345678901', wallet_id:'TBOXYZ12', amount:'1000.00'},
{customer_phone:'+12345678902', wallet_type:'unallocation', amount:'500.00'}
]
})
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.post('https://tenant.example.com/api/v1/deposit-requests/create-batch',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
json={
'cash_bank_id':5,
'payment_method':'Bank Deposit',
'reference':'DEP-8891',
'total_amount':'1500.00',
'customers':[
{'customer_phone':'+12345678901', 'wallet_id':'TBOXYZ12', 'amount':'1000.00'},
{'customer_phone':'+12345678902', 'wallet_type':'unallocation', 'amount':'500.00'}
]
})
print(r.json())
Error Codes
- 400 unknown tenant/domain
- 401 invalid/missing API token or JWT
- 403 user suspended
- 404 account not found
- 422 validation errors β includes
total_amountmismatch and per-customer errors keyed by list index, e.g.{"errors":{"customers":{"1":{"customer_phone":"customer not found"}}}}
Bank and Cash List
Use GET /api/v1/cash-banks with a valid JWT and API token.
Returns the tenant's own active Cash and Bank accounts (source: "local"), plus, for a branch,
any Head Office bank accounts mirrored to it (source: "mirrored") that do not yet have a local
account record. Use these id/account_id values as cash_bank_id when
calling Create Deposit Request.
Request
Headers:
Authorization: Bearer <jwt>
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Query Parameters:
type (optional) "Cash", "Bank", "Directors Current Account", or "Cheque" β filter to a single type
Body:
(none)
Success Response
{
"ok": true,
"cash_banks": [
{
"id": 5,
"source": "local",
"account_id": 12,
"type": "Bank",
"name": "Main Bank Account",
"bank_name": "Commercial Bank",
"account_number": "1234567890"
},
{
"id": null,
"source": "mirrored",
"global_bank_account_id": 3,
"type": "Bank",
"name": "HO Consolidated Account",
"bank_name": "HSBC",
"account_number": "9988776655",
"branch_account_reference": "BR-001",
"sync_status": "SYNCED"
}
]
}
Examples
curl
curl -X GET "https://tenant.example.com/api/v1/cash-banks?type=Bank" \
-H "Authorization: Bearer <jwt>" \
-H "X-API-Token: pat_ABC" \
-H "X-Tenant-Domain: tenant.example.com"
JavaScript
fetch('https://tenant.example.com/api/v1/cash-banks', {
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
}
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.get('https://tenant.example.com/api/v1/cash-banks',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
})
print(r.json())
Error Codes
- 400 unknown tenant/domain
- 401 invalid/missing API token or JWT
- 403 user suspended
- 422 invalid
typevalue
Payment Methods
Use GET /api/v1/payment-methods with a valid JWT and API token.
Returns the payment methods accepted by Create Deposit Request.
Request
Headers:
Authorization: Bearer <jwt>
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Body:
(none)
Success Response
{
"ok": true,
"payment_methods": [
{"code": "Cash", "label": "Cash"},
{"code": "Bank Transfer", "label": "Bank Transfer"},
{"code": "Bank Deposit", "label": "Bank Deposit"},
{"code": "Cheque", "label": "Cheque"}
]
}
Examples
curl
curl -X GET https://tenant.example.com/api/v1/payment-methods \
-H "Authorization: Bearer <jwt>" \
-H "X-API-Token: pat_ABC" \
-H "X-Tenant-Domain: tenant.example.com"
JavaScript
fetch('https://tenant.example.com/api/v1/payment-methods', {
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
}
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.get('https://tenant.example.com/api/v1/payment-methods',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
})
print(r.json())
Error Codes
- 400 unknown tenant/domain
- 401 invalid/missing API token or JWT
- 403 user suspended
HO and Branch List
Use GET /api/v1/branches with a valid JWT and API token.
Returns the full network for the caller's tenant: the Head Office and all of its linked branches, regardless of whether the caller itself is the Head Office or a branch.
Request
Headers:
Authorization: Bearer <jwt>
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Body:
(none)
Success Response
{
"ok": true,
"head_office": {
"company_id": 10,
"name": "Acme Travel HQ",
"domain": "acme.thetravelbo.com",
"code": "ACME"
},
"branches": [
{
"company_id": 57,
"name": "Valorian-journeys",
"domain": "valorian-journeys.thetravelbo.com",
"branch_code": "VALORIP6",
"tenant_type": "BRANCH"
}
]
}
Examples
curl
curl -X GET https://tenant.example.com/api/v1/branches \
-H "Authorization: Bearer <jwt>" \
-H "X-API-Token: pat_ABC" \
-H "X-Tenant-Domain: tenant.example.com"
JavaScript
fetch('https://tenant.example.com/api/v1/branches', {
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
}
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.get('https://tenant.example.com/api/v1/branches',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com'
})
print(r.json())
Error Codes
- 400 unknown tenant/domain
- 401 invalid/missing API token or JWT
- 403 user suspended
Allocate Unallocated Deposit
Use POST /api/v1/receipts/allocate with a valid JWT and API token.
Request
Headers:
Authorization: Bearer <jwt>
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Body:
{
"customer_phone": "+12345678901",
"allocation_date": "2024-05-01",
"allocations": [
{"invoice_number": "INV001", "amount": "50.00"}
]
}
Success Response
{"ok":true,"allocation":{"reference":"CA0001","customer_id":1,"total_allocated":"50.00","lines":[{"invoice_id":1,"invoice_number":"INV001","allocated":"50.00","outstanding":"0.00"}]}}
Examples
curl
curl -X POST https://tenant.example.com/api/v1/receipts/allocate \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{"customer_phone":"+12345678901","allocation_date":"2024-05-01","allocations":[{"invoice_number":"INV001","amount":"50.00"}]}'
JavaScript
fetch('https://tenant.example.com/api/v1/receipts/allocate', {
method:'POST',
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
body: JSON.stringify({
customer_phone:'+12345678901',
allocation_date:'2024-05-01',
allocations:[{invoice_number:'INV001',amount:'50.00'}]
})
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.post('https://tenant.example.com/api/v1/receipts/allocate',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
json={
'customer_phone':'+12345678901',
'allocation_date':'2024-05-01',
'allocations':[{'invoice_number':'INV001','amount':'50.00'}]
})
print(r.json())
Error Codes
- 400 unknown tenant/domain
- 401 invalid/missing API token or JWT
- 403 user suspended
- 404 customer/invoice/account not found
- 422 validation errors or insufficient deposit
Create Automated Invoice from GDS Tray
Use POST /api/v1/invoices/gds-tray/create with a valid JWT and API token. Only Draft invoices are editable.
Request
Headers:
Authorization: Bearer <jwt>
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Idempotency-Key: unique-value (optional)
Body:
{
"pnr": "ABC123",
"customer_phone": "+12345678901", // or "customer_id": 1
"customer_reference": "ACME",
"items": [
{"ticket_no": "123-1234567890", "sell_amount": "100.00"}
],
"finalize": true,
"allow_update_existing_draft": true,
"force_new": false
}
Success Response
{
"ok": true,
"invoice_id": 1,
"invoice_number": "INV1",
"view_url": "https://tenant.example.com/invoices/view/1",
"edit_url": "https://tenant.example.com/invoices/edit/1",
"invoice": {
"id": 1,
"number": "INV1",
"status": "Finalised",
"pnr": "ABC123",
"customer_id": 1,
"invoice_date": "2024-01-02",
"currency": "USD",
"totals": {"base": "100.00", "sell": "110.00", "tax": "10.00", "grand": "110.00"},
"passengers": [{"id": 1, "first_name": "JOHN MR", "last_name": "DOE", "pax_type": "ADT"}],
"lines": [{"ticket_no": "1231234567890", "base_fare": "100.00", "tax": "10.00", "sell_amount": "110.00", "action": "created"}]
}
}
Examples
curl
curl -X POST https://tenant.example.com/api/v1/invoices/gds-tray/create \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-value" \
-d '{"pnr":"ABC123","customer_phone":"+12345678901","items":[{"ticket_no":"123-1234567890","sell_amount":"100.00"}]}'
JavaScript
fetch('https://tenant.example.com/api/v1/invoices/gds-tray/create', {
method:'POST',
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json',
'Idempotency-Key':'unique-value'
},
body: JSON.stringify({
pnr:'ABC123',
customer_phone:'+12345678901',
items:[{ticket_no:'123-1234567890',sell_amount:'100.00'}]
})
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.post('https://tenant.example.com/api/v1/invoices/gds-tray/create',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json',
'Idempotency-Key':'unique-value'
},
json={
'pnr':'ABC123',
'customer_phone':'+12345678901',
'items':[{'ticket_no':'123-1234567890','sell_amount':'100.00'}]
})
print(r.json())
Error Codes
- 400 unknown tenant/domain
- 401 invalid/missing API token or JWT
- 403 user suspended
- 404 customer not found / GDS Tray not found / Ticket not found
- 409 PNR already billed on a Finalised invoice / ticket already billed elsewhere / idempotency conflict
- 422 validation errors
Notes
- Either
customer_phoneorcustomer_idmust be provided. - PNR must correspond to an AIR file whose company code matches the tenant.
- Passenger and fare details come from the AIR file;
itemsonly override sell amounts. - Each
items.ticket_nomust match a ticket in the AIR file; unknown tickets return βTicket not foundβ. - Only Draft invoices are editable; Finalised invoices are locked.
Idempotency-Keyprevents duplicate invoices on retries: the same key with the same body returns the invoice already created; the same key with a different body returns409 idempotency conflictwith that invoice'sinvoice_no. Keys are kept per tenant and do not expire.- Duplicate PNRs or ticket numbers return a 409 conflict.
Interactive Sandbox β Create GDS Tray Invoice
This sandbox sends real requests to the API Base URL you provide. Use valid tenant, token and credentials.
If you see an unauthorized error, confirm the API token, tenant domain and JWT, then login again.
Headers / Auth
Request Body
items
Request Preview
Wallet Hold (VIA credit reservation)
Before creating a VIA invoice, reserve the invoice amount against the customer's wallet/credit-limit balance. This closes the race where two concurrent invoice requests could both pass a balance check and over-credit the customer. Pass the order_no from this endpoint to POST /api/v1/invoices/via/create: the hold is then checked and captured together with the invoice. (order_no is optional on invoice creation for now; we recommend always sending it.)
1. Reserve a hold β POST /api/v1/wallet/hold
A customer has two separate wallets β you must say which one to hold against. Call GET /customers/wallet?phone=<customer_phone> first to get the customer's credit_wallet.wallet_id (the due/credit-limit wallet) and prepaid_wallet.wallet_id (the unallocated/deposit wallet), then pass the one you want as wallet_id below. There is no default β a request without wallet_id is rejected.
JSON fields:
customer_phoneβ required β E.164 format, e.g.+12345678901wallet_idβ required β the specific wallet to reserve against: the customer'scredit_wallet.wallet_idorprepaid_wallet.wallet_idfromGET /customers/wallet. Requests without it are rejected with400 wallet_id required; awallet_idthat doesn't belong to this customer returns422 invalid wallet_id.amountβ required β decimal string, e.g."130.00"currencyβ optional
Headers:
Authorization: Bearer <jwt>
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Idempotency-Key: booking-58213-hold (optional, recommended)
Body:
{
"customer_phone": "+12345678901",
"wallet_id": "1000042",
"amount": "130.00",
"currency": "USD"
}
Success response (201)
{
"ok": true,
"order_no": "H12-3f9a1b2c4d5e",
"wallet_id": "1000042",
"amount": "130.00",
"status": "held",
"expires_at": "2026-08-05T10:20:00",
"domain": "tenant.example.com"
}
The hold expires automatically 20 minutes after creation if it is not captured by a matching create_via_invoice call; an expired hold no longer counts against the customer's balance.
Tickets issued but the invoice call failed or timed out? Call POST /api/v1/invoices/via/create again with the same order_no (and the same Idempotency-Key and body) — it is accepted even after the 20 minutes. The invoice is created, the order is captured and kept on record with its original expiry, and the response shows "hold": {"order_no": "...", "captured_after_expiry": true}. The hold amount is not a limit on the invoice. Only an unknown order, a released hold (booking cancelled) or an order already used for another invoice is refused.
Error responses
- 400 wallet_id required
- 404 customer not found
- 422 invalid wallet_id β
wallet_iddoes not belong to this customer'scredit_walletorprepaid_wallet - 409 insufficient credit β response includes
availableandrequested(for the specified wallet only) - 422 invalid amount
- 409 idempotency conflict β the
Idempotency-Keywas already used with a different body (response includes that hold'sorder_no) - 422 invalid idempotency key β longer than 100 characters
Duplicate prevention: Idempotency-Key
Send a unique Idempotency-Key header (up to 100 characters, e.g. your booking id plus -hold) so a retried request β after a timeout or a dropped connection β never reserves the credit twice.
- Same key, same body: no new hold is made. The original hold is returned with HTTP 200 and
"replayed": true, showing its currentstatus(held,captured,releasedorexpired). - Same key, different body: HTTP 409
idempotency conflict; nothing is reserved. - Keys are kept per tenant and do not expire. Once a hold has expired or been released, use a new key to reserve again.
- Without the header every call creates a new hold.
{
"ok": true,
"replayed": true,
"order_no": "H12-3f9a1b2c4d5e",
"wallet_id": "1000042",
"amount": "130.00",
"status": "held",
"expires_at": "2026-08-05T10:20:00",
"domain": "tenant.example.com"
}
2. Release a hold early β POST /api/v1/wallet/hold/<order_no>/release
Call this if the booking/transaction is abandoned before an invoice is created, to free the reserved credit immediately instead of waiting for the 20-minute expiry. Idempotent β releasing an already-released/expired/captured hold simply returns its current status.
curl -X POST https://tenant.example.com/api/v1/wallet/hold/H12-3f9a1b2c4d5e/release \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC"
{
"ok": true,
"order_no": "H12-3f9a1b2c4d5e",
"status": "released",
"domain": "tenant.example.com"
}
404 if order_no is not found for this tenant.
Create Automated Invoice from VIA
Use POST /api/v1/invoices/via/create with a valid JWT and API token. Only Draft invoices are editable.
Wallet hold (recommended): call POST /api/v1/wallet/hold (see the "Wallet Hold (VIA)" tab) to reserve the invoice amount and obtain an order_no, then pass that order_no in this request. When order_no is sent, the hold is captured atomically with the invoice — also when the hold has expired (tickets already issued; the order is kept on record). If the order is unknown, released or already used for another invoice, the invoice is not created. order_no is optional for now: without it the invoice is created without a hold.
Request
JSON fields:
order_noβ optional for now (recommended) β theorder_noreturned byPOST /api/v1/wallet/holdcustomer_phoneβ E.164 format, e.g.+12345678901service_typeβ one ofFlights,Reissue Tickets,Hotel,ADM,ACM, or the name of one of your Service/Product categories (for exampleVisaorTour) when the Service/Product module is enabled for your company. Any other value returns422with"service_type": "invalid". See Other services (Visa, Hotel, Packages …).pnrβ booking reference, e.g.ABCDEFinvoice.invoice_dateβYYYY-MM-DD, e.g.2024-01-02invoice.currency- currency code, e.g.USDfinalize- optional boolean; defaults totrue. Setfalseonly when the integration expects a Draft invoice without an invoice number.passengers[].first_nameβ e.g.Johnpassengers[].last_nameβ e.g.Doelines[].typeβAir Ticket,Reissue,Other,ADM,RefundorACMlines[].sub_typeβ forAir Ticket:IATA,EMD,Budget; forOther:Hotel,Packages,Transfer,Visa,Insurance,Otherlines[].ticket_noβ required for IATA, 10β13 digits with optional dash, e.g.4567893123or123-4567890123lines[].designatorβ cabin designator when sub_type is IATA, e.g.Ylines[].pax_indexβ index into passengers array for Air Ticket lineslines[].supplier_id- ID of the ticket supplier (must exist); provide either this orlines[].supplier_identification_nolines[].supplier_identification_no- supplier identification no (must exist); provide either this orlines[].supplier_idlines[].supplier_phone- optional E.164 phone that resolves to the supplierlines[].base_fareβ e.g.80.00lines[].taxβ required for Air Ticket, e.g.20.00lines[].supplier_commissionβ e.g.10.00lines[].sell_amountβ e.g.110.00lines[].trnc(orlines[].TRNC) - optional transaction code:TKTT,EMDS,RFND,ADMA,ACMA,CANX,OTHS(orOTHER)lines[].rp_pcc- optional RP PCC valuelines[].segments- optional segment array with keys likefrom,to,flight,depDate,arrDate,depTime,arrTime,bookingClass,groupIndicator- All monetary fields must be nonβnegative decimal strings; invalid values return
422 consultant_idβ optional β Travel Consultant: numeric user ID or email of the staff member to assign as consultant (invoice.staff_id). Defaults to the authenticated user.created_staff_idβ optional β Created Staff: numeric user ID or email of the staff member to record as creator (invoice.created_by). Defaults to the authenticated user.
Headers:
Authorization: Bearer <jwt>
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Idempotency-Key: unique-value (optional)
Body:
{
"order_no": "H12-3f9a1b2c4d5e",
"customer_phone": "+12345678901",
"service_type": "Flights",
"pnr": "ABCDEF",
"consultant_id": 5,
"created_staff_id": 3,
"invoice": {"invoice_date": "2024-01-02", "currency": "USD"},
"passengers": [
{"pax_type": "ADT", "first_name": "John", "last_name": "Doe"}
],
"lines": [
{
"type": "Air Ticket",
"sub_type": "IATA",
"ticket_no": "123-4567890123",
"designator": "Y",
"pax_index": 0,
"base_fare": "80.00",
"tax": "20.00",
"supplier_commission": "10.00",
"sell_amount": "110.00",
"supplier_id": 1,
"trnc": "TKTT",
"rp_pcc": "AB12",
"segments": [
{
"from": "CMB",
"to": "DXB",
"flight": "EK651",
"depDate": "2024-01-10",
"arrDate": "2024-01-10",
"depTime": "08:30",
"arrTime": "11:30",
"bookingClass": "Y",
"groupIndicator": "OUTBOUND"
}
]
}
]
}
Finalised Success Response
{
"ok": true,
"invoice_id": 1,
"invoice_number": "INV1",
"status": "Finalised",
"view_url": "https://tenant.example.com/invoices/view/1",
"edit_url": "https://tenant.example.com/invoices/edit/1",
"invoice": {
"id": 1,
"number": "INV1",
"status": "Finalised",
"pnr": "ABCDEF",
"customer_id": 1,
"customer_phone": "+12345678901",
"service_type": "Flights",
"invoice_date": "2024-01-02",
"currency": "USD",
"totals": {"base": "80.00", "sell": "110.00", "tax": "20.00", "grand": "130.00"},
"passengers": [{"id": 1, "pax_type": "ADT", "first_name": "John", "last_name": "Doe"}],
"lines": [{"ticket_no": "123-4567890123", "supplier_commission": "10.00", "sell_amount": "110.00", "pax_index": 0, "supplier_id": 1, "action": "created", "line_id": 12345, "TRNC": "TKTT", "rp_pcc": "AB12", "segments": [{"from": "CMB", "to": "DXB", "flight": "EK651", "depDate": "2024-01-10", "arrDate": "2024-01-10", "depTime": "08:30:00", "arrTime": "11:30:00", "bookingClass": "Y", "groupIndicator": "OUTBOUND"}]}]
}
}
Draft Success Response
Returned only when the request explicitly sends "finalize": false.
{
"ok": true,
"invoice_id": 1,
"invoice_number": null,
"status": "Draft",
"message": "Invoice saved as draft; no invoice number assigned until finalised.",
"view_url": "https://tenant.example.com/invoices/view/1",
"edit_url": "https://tenant.example.com/invoices/edit/1",
"invoice": {
"id": 1,
"number": null,
"status": "Draft",
"pnr": "ABCDEF"
}
}
Other services (Visa, Hotel, Packages, Transfer, Insurance)
Services that are not air tickets — a visa, a hotel booking, a package, a transfer or insurance — use the same endpoint with a line of type "Other" and the service in sub_type (Visa, Hotel, Packages, Transfer, Insurance or Other). There are no tickets, designators or segments.
service_type– useHotel(built in), or the name of your own Service/Product category (e.g.Visa) if one exists."service_type": "Visa"is refused with422{"errors": {"service_type": "invalid"}}unless a category with exactly that name exists and the Service/Product module is enabled.pnr– still required: exactly 6 letters/digits (use your own booking reference, e.g.VISA01).lines[].type="Other",lines[].sub_type="Visa"(an unknown sub-type returnslines[n].sub_type: invalid).lines[].base_fare(supplier cost),lines[].supplier_commissionandlines[].sell_amount(price to the customer) are required decimal strings.lines[].taxis optional and defaults to0.- A supplier is required: send
lines[].supplier_id,lines[].supplier_identification_noorlines[].supplier_phone(E.164). An unknown supplier returnsnot found. passengers,pax_index,ticket_no,designator,rp_pccandsegmentsare optional and normally omitted. The line's transaction code defaults toOTHS.- The customer is found by
customer_phone;order_no,finalizeandIdempotency-Keywork exactly as for flights.
Sample request – Visa
POST /api/v1/invoices/via/create
Headers:
Authorization: Bearer <jwt>
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Idempotency-Key: visa-2024-0001 (optional)
Body:
{
"order_no": "H12-3f9a1b2c4d5e",
"customer_phone": "+12345678901",
"service_type": "Hotel",
"pnr": "VISA01",
"invoice": {"invoice_date": "2024-01-02", "currency": "LKR"},
"lines": [
{
"type": "Other",
"sub_type": "Visa",
"base_fare": "8000.00",
"supplier_commission": "0.00",
"sell_amount": "10000.00",
"supplier_phone": "+19876543211"
}
]
}
curl
curl -X POST https://tenant.example.com/api/v1/invoices/via/create -H "Authorization: Bearer <jwt>" -H "X-API-Token: pat_xxx" -H "X-Tenant-Domain: tenant.example.com" -H "Content-Type: application/json" -d '{"order_no":"H12-3f9a1b2c4d5e","customer_phone":"+12345678901","service_type":"Hotel","pnr":"VISA01","invoice":{"invoice_date":"2024-01-02","currency":"LKR"},"lines":[{"type":"Other","sub_type":"Visa","base_fare":"8000.00","supplier_commission":"0.00","sell_amount":"10000.00","supplier_phone":"+19876543211"}]}'
Success response (201)
{
"ok": true,
"invoice_id": 1,
"invoice_number": "I000001",
"status": "Finalised",
"view_url": "https://tenant.example.com/invoices/view/1",
"edit_url": "https://tenant.example.com/invoices/edit/1",
"hold": {"order_no": "H12-3f9a1b2c4d5e", "captured_after_expiry": false},
"invoice": {
"id": 1,
"number": "I000001",
"status": "Finalised",
"pnr": "VISA01",
"customer_id": 1,
"customer_phone": "+12345678901",
"service_type": "Hotel",
"invoice_date": "2024-01-02",
"currency": "LKR",
"totals": {"base": "8000.00", "sell": "10000.00", "tax": "0.00", "grand": "10000.00"},
"passengers": [],
"lines": [{"line_id": 1, "action": "created", "ticket_no": null, "sell_amount": "10000.00", "supplier_commission": "0.00", "supplier_id": 999, "pax_index": null, "TRNC": "OTHS", "rp_pcc": null, "segments": []}]
}
}
Using your own "Visa" service category
If your company has a Service/Product category named Visa, send "service_type": "Visa" with the same line; the invoice is then created with service type Visa (invoice.service_type in the response). Without that category the call returns:
422
{"domain": "tenant.example.com", "errors": {"service_type": "invalid"}}
Other errors
422 {"errors": {"lines[0].sub_type": "invalid"}} // sub_type not one of Hotel, Packages, Transfer, Visa, Insurance, Other
422 {"errors": {"lines[0].supplier_id": "required"}} // no supplier given
422 {"errors": {"pnr": "invalid format"}} // pnr must be 6 letters/digits
404 {"error": "customer not found"} // no customer with that customer_phone
Examples
curl
curl -X POST https://tenant.example.com/api/v1/invoices/via/create \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{"order_no":"H12-3f9a1b2c4d5e","customer_phone":"+12345678901","service_type":"Flights","pnr":"ABCDEF","invoice":{"invoice_date":"2024-01-02","currency":"USD"},"passengers":[{"pax_type":"ADT","first_name":"John","last_name":"Doe"}],"lines":[{"type":"Air Ticket","sub_type":"IATA","ticket_no":"123-4567890123","designator":"Y","pax_index":0,"base_fare":"80.00","tax":"20.00","supplier_commission":"10.00","sell_amount":"110.00","supplier_phone":"+19876543211","trnc":"TKTT","rp_pcc":"AB12","segments":[{"from":"CMB","to":"DXB","flight":"EK651","depDate":"2024-01-10","arrDate":"2024-01-10","depTime":"08:30","arrTime":"11:30","bookingClass":"Y","groupIndicator":"OUTBOUND"}]}]}'
JavaScript
fetch('https://tenant.example.com/api/v1/invoices/via/create', {
method:'POST',
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
body: JSON.stringify({
order_no:'H12-3f9a1b2c4d5e',
customer_phone:'+12345678901',
service_type:'Flights',
pnr:'ABCDEF',
invoice:{invoice_date:'2024-01-02',currency:'USD'},
passengers:[{pax_type:'ADT',first_name:'John',last_name:'Doe'}],
lines:[{type:'Air Ticket',sub_type:'IATA',ticket_no:'123-4567890123',designator:'Y',pax_index:0,base_fare:'80.00',tax:'20.00',supplier_commission:'10.00',sell_amount:'110.00',supplier_phone:'+19876543211',trnc:'TKTT',rp_pcc:'AB12',segments:[{from:'CMB',to:'DXB',flight:'EK651',depDate:'2024-01-10',arrDate:'2024-01-10',depTime:'08:30',arrTime:'11:30',bookingClass:'Y',groupIndicator:'OUTBOUND'}]}]
})
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.post('https://tenant.example.com/api/v1/invoices/via/create',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
json={
'order_no':'H12-3f9a1b2c4d5e',
'customer_phone':'+12345678901',
'service_type':'Flights',
'pnr':'ABCDEF',
'invoice':{'invoice_date':'2024-01-02','currency':'USD'},
'passengers':[{'pax_type':'ADT','first_name':'John','last_name':'Doe'}],
'lines':[{'type':'Air Ticket','sub_type':'IATA','ticket_no':'123-4567890123','designator':'Y','pax_index':0,'base_fare':'80.00','tax':'20.00','supplier_commission':'10.00','sell_amount':'110.00','supplier_phone':'+19876543211','trnc':'TKTT','rp_pcc':'AB12','segments':[{'from':'CMB','to':'DXB','flight':'EK651','depDate':'2024-01-10','arrDate':'2024-01-10','depTime':'08:30','arrTime':'11:30','bookingClass':'Y','groupIndicator':'OUTBOUND'}]}]
})
print(r.json())
Error Codes
- 400 unknown tenant/domain
- 401 invalid/missing API token or JWT
- 403 user suspended
- 404 customer not found
- 409 PNR already billed on a Finalised invoice / ticket already billed elsewhere / idempotency conflict
- 409
hold not found— no wallet hold with thisorder_no - 409
hold released— the order's hold was released (booking cancelled) - 409
hold already used— theorder_nowas already used for another invoice (response includes itsinvoice_no) - 409 invoice finalisation failed; the invoice was saved as Draft but could not be finalised
- 422 validation errors
Notes
- Only Draft invoices are editable; Finalised invoices are locked.
order_nois optional for now; when sent it must come from a successfulPOST /api/v1/wallet/holdcall β see the "Wallet Hold (VIA)" tab.- Retrying after a failure or timeout: first check
GET /api/v1/invoices/lookup?order_no=...(orticket_no/pnr). If nothing is found, send the same request again with the sameIdempotency-Key, body andorder_no— accepted even after the hold's 20 minutes. If the first call did succeed, the retry returns 200 with that same invoice; nothing is created or charged twice. - The success response includes
"hold": {"order_no", "captured_after_expiry"}when anorder_nowas sent. The hold amount does not limit the invoice total. - When
finalizeis omitted ortrue, a successful response must includestatus: "Finalised"and a non-nullinvoice_number. - When
finalize: false, a Draft response withinvoice_number: nullis expected and should not be treated as an API failure. Idempotency-Keyprevents duplicate invoices on retries: the same key with the same body returns the invoice already created; the same key with a different body returns409 idempotency conflictwith that invoice'sinvoice_no. Keys are kept per tenant and do not expire.- Duplicate PNRs or ticket numbers return a 409 conflict.
- Each item in
invoice.lines[]now includesline_id(integer),TRNC, and can includerp_pccandsegments.
Invoice Lookup (read-only)
Find invoices by ticket number, wallet-hold order_no or PNR β for example to check whether a booking was already invoiced before retrying. GET /api/v1/invoices/lookup only reads; it never changes anything.
Request
GET /api/v1/invoices/lookup?ticket_no=1761234567890
Headers:
Authorization: Bearer <jwt>
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Query parameters β at least one of the first three:
ticket_noβ ticket number; spaces and dashes are ignored (176-1234567890=1761234567890)order_noβ theorder_noof a wallet hold; finds the invoice that captured itpnrβ booking reference (not case-sensitive)customer_phoneβ optional, E.164; only that customer's invoices
Several parameters together must all match. At most 50 invoices are returned, newest first.
Success response (200)
{
"ok": true,
"count": 1,
"invoices": [
{
"invoice_number": "INV-000123",
"status": "Finalised",
"invoice_date": "2026-10-21",
"currency": "LKR",
"total_amount": "110.00",
"customer": {"name": "John Doe", "phone": "+12345678901"},
"pnrs": ["ABC123"],
"order_nos": ["H12-3f9a1b2c4d5e"],
"lines": [
{"ticket_no": "1761234567890", "pnr": "ABC123", "passenger": "John Doe",
"type": "Air Ticket", "sell_price": "110.00", "status": "Normal"}
]
}
],
"domain": "tenant.example.com"
}
No match returns "count": 0 and an empty list. For an order_no whose hold has not been used by an invoice, the response also carries hold_status: held, released, expired or not_found.
Errors
- 400
lookup key requiredβ none ofticket_no,order_no,pnrgiven - 422
invalid ticket_no - 401
invalid token/unauthorized; 403forbidden(JWT for another tenant); 400unknown tenant/domain
Examples
curl "https://tenant.example.com/api/v1/invoices/lookup?order_no=H12-3f9a1b2c4d5e" \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC"
const r = await fetch('/api/v1/invoices/lookup?pnr=ABC123', {
headers: {'Authorization': 'Bearer <jwt>', 'X-Tenant-Domain': 'tenant.example.com', 'X-API-Token': 'pat_ABC'}
});
const data = await r.json();
import requests
r = requests.get('https://tenant.example.com/api/v1/invoices/lookup',
params={'ticket_no': '176-1234567890'},
headers={'Authorization': 'Bearer <jwt>', 'X-Tenant-Domain': 'tenant.example.com',
'X-API-Token': 'pat_ABC'})
print(r.json())
Split Invoice
Use POST /api/v1/invoices/split with a valid JWT and API token to split a single invoice into multiple invoices. Without ticket_no, it splits into one invoice per distinct ticket number found on its lines. With ticket_no, it identifies one or more item lines by their ticket(s) and splits them off β together, into a single new invoice β leaving every other line together in a second "remainder" invoice. Nothing on the source invoice is ever dropped: every line ends up on exactly one of the resulting invoices, and every created invoice (including the remainder) is returned in the response.
Request
JSON fields:
invoice_numberβ required β the invoice number of the invoice to splitticket_noβ optional β identifies the item line(s) to split off, matched against each line'sticket_noafter normalizing both sides (dashes and spaces stripped, upper-cased). Accepts a single string ("2000000000"), a comma-separated string ("1000000000,3000000000"), or a list of strings (["1000000000", "3000000000"]) to target more than one ticket at once β all matched lines land together in ONE new invoice. When provided, exactly two invoices are created: one holding the matched line(s) (and their linked passengers), and one "remainder" invoice holding every other line on the source, regardless of how many distinct tickets they carry. When omitted, the original "one invoice per distinct ticket group" behavior applies.finalizeβ optional boolean; defaults tofalse. Whentrue, each newly created invoice is finalised immediately (an invoice number is assigned to each).
Headers:
Authorization: Bearer <jwt>
Content-Type: application/json
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Body (split every ticket group):
{
"invoice_number": "INV1",
"finalize": false
}
Body (split off one ticket's line, e.g. INV1 has 3 lines):
{
"invoice_number": "INV1",
"ticket_no": "2000000000",
"finalize": false
}
Body (split off MULTIPLE tickets' lines together into one invoice,
e.g. INV1 has 3 lines and you want tickets 1 and 3 combined,
leaving ticket 2 as the remainder) -- a JSON list and a comma-separated
string are equivalent:
{
"invoice_number": "INV1",
"ticket_no": ["1000000000", "3000000000"],
"finalize": false
}
{
"invoice_number": "INV1",
"ticket_no": "1000000000,3000000000",
"finalize": false
}
Behavior
- Without
ticket_no: invoice lines are grouped by normalizedticket_no(dashes and spaces stripped, upper-cased). Each distinct ticket number produces one new invoice; lines with noticket_noare grouped together into their own invoice (reported withticket_no: null). - With
ticket_noas a single value, a comma-separated string, or a list: the line(s) whose normalizedticket_nomatches ANY of the requested value(s) go together into one new invoice; every other line on the source goes into a single "remainder" invoice. Each matched line's linked passenger (PaxDetail) is cloned onto the new invoice along with it β a line is never separated from its passenger. - If some but not all of the requested tickets in a list actually match a line on the invoice, the split still proceeds using whichever ones matched, and the response includes a
tickets_not_foundarray naming the ones that didn't β so a partial mismatch is always visible, never silent. If NONE of the requested tickets match, the request 404s exactly like the single-value case. - If the source invoice is Draft, its lines are carved into new Draft invoices and the nowβempty original draft is deleted, provided it has no accounting history. The response reports the source as
status: "Draft-deleted". - If the source invoice is Finalised, it is reversed first (creating a
REV-journal entry, identical to the manual "Reverse Invoice" action), and then the Draft child invoices are created, linked to the source viasource_invoice_id. The response reports the source asstatus: "Reversed". - An invoice that has already been split (or reinvoiced) β i.e. one that already has a linked child invoice β cannot be split again. This applies to a
ticket_no-filtered split too: it is still a one-shot operation per source invoice. - An invoice whose lines all share a single ticket group (nothing to split) is rejected β including when
ticket_nomatches every line on the invoice, leaving nothing for the remainder invoice. - When
finalize: true, each created invoice is assigned an invoice number and finalised; if finalisation of a given child fails, that entry is still returned as a Draft withfinalize_errorset, rather than failing the whole request.
Success Response 200
Example for a ticket_no-filtered split of a 3-line invoice (one line + its passenger split off, two lines + two passengers left in the remainder):
{
"ok": true,
"source_invoice": {
"invoice_id": null,
"invoice_number": "INV1",
"status": "Draft-deleted",
"reversal_reference": null
},
"created_invoices": [
{
"invoice_id": 101,
"invoice_number": null,
"ticket_no": "2000000000",
"ticket_nos": ["2000000000"],
"passengers": [
{"pax_id": 55, "first_name": "Jane", "last_name": "Roe", "pax_type": "ADT"}
],
"status": "Draft",
"finalized": false,
"finalize_error": null,
"view_url": "https://tenant.example.com/invoices/view/101",
"edit_url": "https://tenant.example.com/invoices/edit/101"
},
{
"invoice_id": 102,
"invoice_number": null,
"ticket_no": null,
"ticket_nos": ["1000000000", "3000000000"],
"passengers": [
{"pax_id": 56, "first_name": "John", "last_name": "Doe", "pax_type": "ADT"},
{"pax_id": 57, "first_name": "Sam", "last_name": "Fox", "pax_type": "ADT"}
],
"status": "Draft",
"finalized": false,
"finalize_error": null,
"view_url": "https://tenant.example.com/invoices/view/102",
"edit_url": "https://tenant.example.com/invoices/edit/102"
}
],
"domain": "tenant.example.com"
}
ticket_no is a single value when the invoice has exactly one distinct ticket number, otherwise null (e.g. the remainder invoice, or the no-ticket_no mode's "no ticket" bucket, or a multi-ticket split's combined invoice) β check ticket_nos for the full list. passengers lists every PaxDetail carried onto that invoice. A top-level tickets_not_found array is present (only when non-empty) if some of the requested ticket_no values in a list didn't match any line.
Examples
curl
curl -X POST https://tenant.example.com/api/v1/invoices/split \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{"invoice_number":"INV1","finalize":false}'
# Split off just one ticket's line (and its passenger)
curl -X POST https://tenant.example.com/api/v1/invoices/split \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{"invoice_number":"INV1","ticket_no":"2000000000","finalize":false}'
# Split off MULTIPLE tickets' lines together into one invoice
curl -X POST https://tenant.example.com/api/v1/invoices/split \
-H "Authorization: Bearer <jwt>" \
-H "X-Tenant-Domain: tenant.example.com" \
-H "X-API-Token: pat_ABC" \
-H "Content-Type: application/json" \
-d '{"invoice_number":"INV1","ticket_no":["1000000000","3000000000"],"finalize":false}'
JavaScript
fetch('https://tenant.example.com/api/v1/invoices/split', {
method:'POST',
headers:{
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
body: JSON.stringify({
invoice_number:'INV1',
ticket_no:['1000000000','3000000000'], // or a single string, e.g. '2000000000'
finalize:false
})
}).then(r=>r.json()).then(console.log);
Python
import requests
r = requests.post('https://tenant.example.com/api/v1/invoices/split',
headers={
'Authorization':'Bearer <jwt>',
'X-API-Token':'pat_ABC',
'X-Tenant-Domain':'tenant.example.com',
'Content-Type':'application/json'
},
json={
'invoice_number':'INV1',
'ticket_no':'2000000000',
'finalize':False
})
print(r.json())
Error Codes
| Status | Error | Meaning |
|---|---|---|
| 400 | unknown tenant/domain | Tenant could not be resolved from X-Tenant-Domain / host |
| 401 | invalid token | Missing or invalid X-API-Token |
| 401 | unauthorized | Missing/invalid Authorization: Bearer JWT, or user not found |
| 403 | forbidden | JWT company id does not match the resolved tenant |
| 403 | suspended | Authenticated user is suspended |
| 400 | invoice_number required | Request body is missing invoice_number |
| 404 | invoice not found | No invoice with the given invoice_number for this tenant |
| 409 | invoice status '...' cannot be split | Only Draft, Finalised, or Reversed invoices are eligible |
| 409 | invoice has already been split/reinvoiced | A linked child invoice already exists for this source |
| 404 | ticket_no not found on invoice | No line on the source invoice matches the normalized ticket_no |
| 400 | invoice has only one ticket group; nothing to split | All lines share the same (or no) ticket number, or ticket_no matched every line, leaving nothing for the remainder |
| 409 | duplicate ticket numbers detected on source invoice | The same ticket number appears on more than one line unexpectedly |
| 409 | reversal failed | Reversing a Finalised source invoice failed validation (see message) |
| 500 | reversal commit failed | The reversal succeeded logically but the commit raised an error |
| 409 | split failed | An integrity error occurred while creating the split invoices |
| 500 | split failed / split partially failed after reversal | An unexpected error occurred while creating the split invoices (after the source was already reversed, if applicable) |
Notes
- The source invoice must not already have a linked child (split or reinvoice) and must have more than one distinct ticket group (or, with
ticket_no, at least one other line left for the remainder). - Reversing a Finalised source (when splitting it) behaves exactly like the manual "Reverse Invoice" action, including moving payments to unallocated deposit and creating a
REV-journal entry. - Newly created invoices are always Drafts unless
finalize: trueis passed, in which case each is finalised individually and assigned its own invoice number. - A
ticket_no-filtered split is still one call per source invoice β the remainder invoice is a fresh Draft with noinvoice_number(unlessfinalize: true); to split it further, finalize it first (or use the invoice editor's split action) so it has aninvoice_numberthis endpoint can look up.
GET /api/v1/users β List Users
Returns a paginated list of users belonging to the tenant. Requires X-API-Token + Authorization: Bearer <jwt>.
Headers
Authorization: Bearer <jwt>
X-API-Token: pat_xxx
X-Tenant-Domain: tenant.example.com
Query Parameters
| Param | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
per_page | integer | 20 | Results per page (max 100) |
q | string | β | Search by name or email (case-insensitive) |
role | string | β | Filter by exact role (e.g. Sales Staff) |
include_suspended | boolean | false | Set to true to include suspended users |
Success Response 200
{
"ok": true,
"users": [
{
"id": 1,
"email": "[email protected]",
"name": "John Smith",
"role": "Sales Staff",
"is_suspended": false,
"last_login": "2026-06-30T10:00:00"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 5,
"total_pages": 1
}
}
Error Responses
401 {"ok": false, "error": "invalid token"}
401 {"ok": false, "error": "missing token"}
403 {"ok": false, "error": "suspended"}