Reference
Endpoints
Auth, customers, items, sales, purchasing, payments and receipts.
Every path below is relative to the base URL https://gulfpay-production.up.railway.app/api/v1. Unless marked Public, an endpoint requires a Authorization: Bearer <token> header and honours the X-Company-Id scope. A :idsegment is the resource's identifier. This is a representative reference of the most-used resources — the product exposes many more modules on the same conventions.
Looking for the complete list?
Shared document actions
PATCH /:id/status, PATCH /:id/lock, PATCH /:id/discount, PATCH /:id/charges and POST /:id/duplicate. Only the distinctive routes per resource are listed below to keep the reference readable.Authentication
See Authentication for the full login flow.
Exchange email + password for tokens (or a pre-auth OTP challenge).
Complete a two-factor login using the pre-auth token as the bearer.
Resend the one-time code for a pending OTP challenge.
Mint a new access token from a refresh token (token is not rotated).
Revoke the refresh token / clear the session cookie.
Return the current authenticated user.
Change the password and revoke every other session.
List the caller’s active sessions (current flagged).
Revoke one of the caller’s sessions.
Revoke every session except the current one.
Customers
List customers (paginated, searchable, sortable).
Check whether a customer name / identifier already exists.
Retrieve a single customer.
Retrieve a customer’s outstanding balance and financial summary.
Create a customer.
Update a customer.
Delete a customer.
Items
List items / products (paginated, searchable, sortable).
Check whether an item code / name already exists.
Retrieve a single item.
Create an item.
Update an item.
Delete an item.
Upload an item image (base64 body).
Fetch an item image (public so it can be embedded).
Remove an item image.
Vendors
List vendors / suppliers.
Check whether a vendor already exists.
Retrieve a single vendor.
Create a vendor.
Update a vendor.
Delete a vendor.
Sales documents
The sales cycle flows from quotation through to a paid invoice:
Quotations
List quotations.
Retrieve a quotation.
Create a quotation.
Update a quotation.
Change a quotation’s status.
Convert a quotation into a sales order.
Convert a quotation into a sales invoice.
Convert a quotation into a delivery note.
Delete a quotation.
Sales orders
List sales orders.
Retrieve a sales order.
Create a sales order.
Update a sales order.
Change a sales order’s status.
Convert a sales order into a sales invoice.
Convert a sales order into a delivery note.
Delete a sales order.
Delivery notes
List delivery notes.
Retrieve a delivery note.
Create a delivery note (moves stock out).
Update a delivery note.
Change a delivery note’s status.
Convert a delivery note into a sales invoice.
Delete a delivery note.
Sales invoices
List sales invoices.
Retrieve a sales invoice.
Create a sales invoice.
Update a sales invoice.
Change an invoice’s status.
Record a payment against the invoice.
Generate the ZATCA e-invoicing QR for the invoice.
Delete a sales invoice.
Sales returns
List sales returns / credit notes.
Create a sales return.
Create a sales return from an existing invoice.
Process the refund for an approved return.
Delete a sales return.
Creating a document posts a JSON body with header fields and line items:
curl -X POST https://gulfpay-production.up.railway.app/api/v1/quotations \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "X-Company-Id: cmp_123" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3b9a1c7e-2d54-4a11-8e0f-6c2b9d4a1f88" \
-d '{
"customerId": "cus_123",
"date": "2026-09-06",
"lines": [
{ "itemId": "itm_1", "quantity": 10, "unitPrice": 25.00, "taxRate": 15 }
]
}'Purchase documents
The purchase cycle mirrors the sales cycle:
Purchase orders
List purchase orders.
Retrieve a purchase order.
Create a purchase order.
Update a purchase order.
Convert a purchase order into a goods receipt.
Convert a purchase order into a purchase invoice.
Delete a purchase order.
Goods receipts
List goods receipts (GRNs).
Retrieve a goods receipt.
Create a goods receipt (moves stock in).
Update a goods receipt.
Convert a goods receipt into a purchase invoice.
Delete a goods receipt.
Purchase invoices
List purchase invoices / bills.
Retrieve a purchase invoice.
Create a purchase invoice.
Update a purchase invoice.
Record a payment against the bill.
Delete a purchase invoice.
Purchase returns
List purchase returns / debit notes.
Create a purchase return.
Create a purchase return from an existing bill.
Process the refund for an approved return.
Delete a purchase return.
Receipts & payments
Receipts record money received from customers; payments record money paid to vendors. Both can be allocated across one or more open documents.
Receipts (money in)
List customer receipts (money in).
List customers with outstanding balances to receive against.
Retrieve a receipt.
Create a receipt and allocate it to invoices.
Update a receipt.
Delete a receipt.
Payments (money out)
List vendor payments (money out).
List vendors with outstanding balances to pay against.
Retrieve a payment.
Create a payment and allocate it to bills.
Update a payment.
Delete a payment.