Bill creation in Credith is a complex transactional operation that touches six tables in a single database transaction. The server validates the cashier’s checkout machine, resolves the active CAI and CAI Range, formats the SAR-compliant bill number, deducts inventory for every line item, calculates ISV-15 tax, and then creates either a fully-paid cash payment plan or a multi-installment credit plan — all atomically. A failure at any step rolls back the entire transaction, so partial bills are never persisted.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/RoyGeova07/Credith/llms.txt
Use this file to discover all available pages before exploring further.
POST /api/bills
Creates a new invoice. No authentication is required on this endpoint; the userId in the request body is used to resolve the cashier’s checkout machine and store assignment.
Validations performed (in order)
- Cashier check —
userIdmust correspond to an existing user who has an active checkout machine assigned. - Store check — The user’s store must match the
storeIdin the request body. - CAI check — The store must have an active CAI with an active, non-exhausted range. The range lock is held (
SELECT FOR UPDATE) during the transaction to prevent race conditions. - Inventory check — Every product in
detailsmust exist in the store’s inventory with sufficientinStockquantity.
The
bill_number for each invoice is derived from the active CAI Range as minRange + currentNumber. After the bill is persisted, currentNumber is incremented by 1 on the range record. The fully formatted billNumberFinal follows the pattern {storeNumber:3}-{machineNumber:3}-{documentType}-{billNumber:8}, e.g. 001-001-01-00000001.Request body
UUID of the cashier (user) processing the sale. Must have an assigned checkout machine and a valid store association.
UUID of the store where the sale takes place. Must match the store on record for the given
userId.Payment method for this invoice. Accepted values:
"CASH" or "INSTALLMENT". Determines which payment-plan creation branch runs.Optional due date printed on the invoice, e.g.
"2025-12-31".Overall invoice-level discount percentage (stored for display; the monetary amount must be supplied in
discountAmount).Monetary discount applied to the invoice subtotal before ISV calculation.
Exonerated amount (ISV-exempt portion) for fiscal reporting.
Exempt amount for fiscal reporting.
One or more line items. The server re-validates each item’s
total as quantity × sellPrice × (1 - discountPercentage / 100).Customer information printed on the invoice.
Payment plan details. Required fields vary by
paymentType.Example — CASH bill
Example — INSTALLMENT bill
Response fields
Auto-generated primary key for the created bill.
Raw sequential number within the active CAI Range (
minRange + currentNumber at time of creation).Fully formatted SAR-compliant invoice number:
{storeNumber:3}-{machineNumber:3}-{documentType}-{billNumber:8}."CASH" or "INSTALLMENT".Sum of all line-item totals before any invoice-level discount.
ISV-15 tax amount (15% of the discounted subtotal).
Invoice-level monetary discount applied before tax.
Final invoice total:
(subtotal - discountAmount) + isv15Amount.Snapshot of the company name at time of invoice creation.
Snapshot of the company RTN (tax ID) at time of creation.
Full name of the user who processed the sale.
UUID of the CAI Range used to generate this invoice’s bill number.
The payment plan created alongside this bill. Shape varies by
paymentType — see Payment Plans for full field definitions.Error responses
| Status | Cause |
|---|---|
400 | Invalid paymentType, mismatched line-item total, or client already has an active installment plan |
404 | User, checkout machine, store, active CAI, CAI Range, company, or product inventory not found |
406 | CAI Range exhausted (nextBillNumber > maxRange), store mismatch between user and request, or insufficient stock |
500 | Unexpected server error |