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

FieldTypeRequiredNotes
customer_typestringYesCustomer, Agent, or Corporate
customer_namestringYes1–200 characters
phonestringYesE.164 format, e.g. +12345678901
emailstringYesValid email address
business_registration_nostringConditionalAgent/Corporate only. Required when credit_limit > 0
credit_limitnumberNoAgent/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_limit can only be set for Agent or Corporate customer types.
  • When credit_limit > 0, business_registration_no must be provided.
  • business_registration_no is stored only for Agent and Corporate types.

Error Codes

  • 400 unknown tenant
  • 401 invalid token / unauthorized
  • 403 forbidden
  • 409 duplicate phone
  • 422 validation errors (see errors object 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

FieldTypeRequiredNotes
business_namestringYesSupplier's business name
phonestringYesAny parseable phone number (defaults to LK region), normalized to E.164
emailstringNoValid 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

FieldTypeRequiredNotes
phonestringOne of phone / supplier_identification_noExact match against the supplier's phone number. Takes precedence if both params are given.
supplier_identification_nostringOne of phone / supplier_identification_noExact 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 Pending request 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_amount mismatch 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 type value

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_phone or customer_id must be provided.
  • PNR must correspond to an AIR file whose company code matches the tenant.
  • Passenger and fare details come from the AIR file; items only override sell amounts.
  • Each items.ticket_no must match a ticket in the AIR file; unknown tickets return β€œTicket not found”.
  • Only Draft invoices are editable; Finalised invoices are locked.
  • Idempotency-Key prevents duplicate invoices on retries: the same key with the same body returns the invoice already created; the same key with a different body returns 409 idempotency conflict with that invoice's invoice_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. +12345678901
  • wallet_id – required – the specific wallet to reserve against: the customer's credit_wallet.wallet_id or prepaid_wallet.wallet_id from GET /customers/wallet. Requests without it are rejected with 400 wallet_id required; a wallet_id that doesn't belong to this customer returns 422 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_id does not belong to this customer's credit_wallet or prepaid_wallet
  • 409 insufficient credit β€” response includes available and requested (for the specified wallet only)
  • 422 invalid amount
  • 409 idempotency conflict β€” the Idempotency-Key was already used with a different body (response includes that hold's order_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 current status (held, captured, released or expired).
  • 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) – the order_no returned by POST /api/v1/wallet/hold
  • customer_phone – E.164 format, e.g. +12345678901
  • service_type – one of Flights, Reissue Tickets, Hotel, ADM, ACM, or the name of one of your Service/Product categories (for example Visa or Tour) when the Service/Product module is enabled for your company. Any other value returns 422 with "service_type": "invalid". See Other services (Visa, Hotel, Packages …).
  • pnr – booking reference, e.g. ABCDEF
  • invoice.invoice_date – YYYY-MM-DD, e.g. 2024-01-02
  • invoice.currency - currency code, e.g. USD
  • finalize - optional boolean; defaults to true. Set false only when the integration expects a Draft invoice without an invoice number.
  • passengers[].first_name – e.g. John
  • passengers[].last_name – e.g. Doe
  • lines[].type – Air Ticket, Reissue, Other, ADM, Refund or ACM
  • lines[].sub_type – for Air Ticket: IATA, EMD, Budget; for Other: Hotel, Packages, Transfer, Visa, Insurance, Other
  • lines[].ticket_no – required for IATA, 10–13 digits with optional dash, e.g. 4567893123 or 123-4567890123
  • lines[].designator – cabin designator when sub_type is IATA, e.g. Y
  • lines[].pax_index – index into passengers array for Air Ticket lines
  • lines[].supplier_id - ID of the ticket supplier (must exist); provide either this or lines[].supplier_identification_no
  • lines[].supplier_identification_no - supplier identification no (must exist); provide either this or lines[].supplier_id
  • lines[].supplier_phone - optional E.164 phone that resolves to the supplier
  • lines[].base_fare – e.g. 80.00
  • lines[].tax – required for Air Ticket, e.g. 20.00
  • lines[].supplier_commission – e.g. 10.00
  • lines[].sell_amount – e.g. 110.00
  • lines[].trnc (or lines[].TRNC) - optional transaction code: TKTT, EMDS, RFND, ADMA, ACMA, CANX, OTHS (or OTHER)
  • lines[].rp_pcc - optional RP PCC value
  • lines[].segments - optional segment array with keys like from, 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 – use Hotel (built in), or the name of your own Service/Product category (e.g. Visa) if one exists. "service_type": "Visa" is refused with 422 {"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 returns lines[n].sub_type: invalid).
  • lines[].base_fare (supplier cost), lines[].supplier_commission and lines[].sell_amount (price to the customer) are required decimal strings. lines[].tax is optional and defaults to 0.
  • A supplier is required: send lines[].supplier_id, lines[].supplier_identification_no or lines[].supplier_phone (E.164). An unknown supplier returns not found.
  • passengers, pax_index, ticket_no, designator, rp_pcc and segments are optional and normally omitted. The line's transaction code defaults to OTHS.
  • The customer is found by customer_phone; order_no, finalize and Idempotency-Key work 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 this order_no
  • 409 hold released — the order's hold was released (booking cancelled)
  • 409 hold already used — the order_no was already used for another invoice (response includes its invoice_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_no is optional for now; when sent it must come from a successful POST /api/v1/wallet/hold call β€” see the "Wallet Hold (VIA)" tab.
  • Retrying after a failure or timeout: first check GET /api/v1/invoices/lookup?order_no=... (or ticket_no / pnr). If nothing is found, send the same request again with the same Idempotency-Key, body and order_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 an order_no was sent. The hold amount does not limit the invoice total.
  • When finalize is omitted or true, a successful response must include status: "Finalised" and a non-null invoice_number.
  • When finalize: false, a Draft response with invoice_number: null is expected and should not be treated as an API failure.
  • Idempotency-Key prevents duplicate invoices on retries: the same key with the same body returns the invoice already created; the same key with a different body returns 409 idempotency conflict with that invoice's invoice_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 includes line_id (integer), TRNC, and can include rp_pcc and segments.

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 – the order_no of a wallet hold; finds the invoice that captured it
  • pnr – 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 of ticket_no, order_no, pnr given
  • 422 invalid ticket_no
  • 401 invalid token / unauthorized; 403 forbidden (JWT for another tenant); 400 unknown 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 split
  • ticket_no – optional – identifies the item line(s) to split off, matched against each line's ticket_no after 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 to false. When true, 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 normalized ticket_no (dashes and spaces stripped, upper-cased). Each distinct ticket number produces one new invoice; lines with no ticket_no are grouped together into their own invoice (reported with ticket_no: null).
  • With ticket_no as a single value, a comma-separated string, or a list: the line(s) whose normalized ticket_no matches 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_found array 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 via source_invoice_id. The response reports the source as status: "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_no matches 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 with finalize_error set, 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

StatusErrorMeaning
400unknown tenant/domainTenant could not be resolved from X-Tenant-Domain / host
401invalid tokenMissing or invalid X-API-Token
401unauthorizedMissing/invalid Authorization: Bearer JWT, or user not found
403forbiddenJWT company id does not match the resolved tenant
403suspendedAuthenticated user is suspended
400invoice_number requiredRequest body is missing invoice_number
404invoice not foundNo invoice with the given invoice_number for this tenant
409invoice status '...' cannot be splitOnly Draft, Finalised, or Reversed invoices are eligible
409invoice has already been split/reinvoicedA linked child invoice already exists for this source
404ticket_no not found on invoiceNo line on the source invoice matches the normalized ticket_no
400invoice has only one ticket group; nothing to splitAll lines share the same (or no) ticket number, or ticket_no matched every line, leaving nothing for the remainder
409duplicate ticket numbers detected on source invoiceThe same ticket number appears on more than one line unexpectedly
409reversal failedReversing a Finalised source invoice failed validation (see message)
500reversal commit failedThe reversal succeeded logically but the commit raised an error
409split failedAn integrity error occurred while creating the split invoices
500split failed / split partially failed after reversalAn 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: true is 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 no invoice_number (unless finalize: true); to split it further, finalize it first (or use the invoice editor's split action) so it has an invoice_number this 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

ParamTypeDefaultDescription
pageinteger1Page number
per_pageinteger20Results per page (max 100)
qstringβ€”Search by name or email (case-insensitive)
rolestringβ€”Filter by exact role (e.g. Sales Staff)
include_suspendedbooleanfalseSet 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"}