Skip to main content
The Orders & Sales domain is the transactional core of the Genuka platform. It manages the full lifecycle of a sale: from order creation through state transitions (quotation → sales order → invoice), payment tracking, invoice generation, and post-sale documents such as credit notes. Related sub-resources include order products, order activities, order subscriptions, and per-order payments. Base URL https://api.genuka.com · Auth Authorization: Bearer <token> + X-Company: <companyId> · See Getting Started for shared conventions, pagination & error formats.

​
Endpoints at a glance

​
Orders

​
GET /2023-11/admin/orders

List orders with rich filtering, sorting, and optional relationship includes.
  • Query parameters:
Request example:
Success response 200 OK:
Error responses:
  • 400 Missing X-Company header: {"message":"Company id required","error":"company_id_required","code":400}
  • 401 Invalid or missing token.
  • 403 Token lacks order read permission.

​
POST /2023-11/admin/orders

Create a new order. Triggers UpsertOrderProcess which handles customer upsert, product creation, address linking, and—if billing status is already paid—runs payment processing automatically.
  • Request body:
Request example:
Success response 200 OK — returns an OrderDetailResource:
Error responses:
  • 400 Missing X-Company header.
  • 401 Unauthorized.
  • 500 Internal error with message describing the failure.

​
POST /2023-11/admin/orders/export

Enqueue an asynchronous export of the current order query. Accepts the same filter and include parameters as the list endpoint, plus:
  • Request body:
Request example:
Success response — two possible shapes depending on the number of matching orders: Sync (< 500 orders): 200 OK — binary file download. Content-Type is application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for XLSX, text/csv for CSV, or application/pdf for PDF. No JSON body. Async (≥ 500 orders): 202 Accepted — the export is queued; the user will receive an email with the download link.
Error responses:
  • 401 User not authenticated.
  • 422 Unsupported format: {"message":"The given data was invalid.","errors":{"format":["Unsupported export format."]}}
  • 500 Export failure.

​
GET /2023-11/admin/orders/export/fields

Return the list of column names available for order exports. Request example:
Success response 200 OK:

​
POST /2023-11/admin/orders/import

Import orders from a spreadsheet file (single-request upload).
  • Request body (multipart/form-data):
Request example:
Success response 200 OK:
Error responses:
  • 422 Validation failure — file missing or wrong MIME type.
  • 500 Import processing error.

​
POST /2023-11/admin/orders/import-chunk

Upload a single chunk of a large import file (for chunked/resumable uploads). All chunks for a single upload share the same uploadId.
  • Request body (multipart/form-data):
Success response 200 OK:
Error responses:
  • 400 File not found or file is empty.
  • 422 Validation failure.

​
POST /2023-11/admin/orders/merge-chunk

Merge previously uploaded chunks into a single file and run the import.
  • Request body:
Success response 200 OK:
Error responses:
  • 422 Validation failure.
  • 500 Merge or import error with message.

​
GET /2023-11/admin/orders/overview

Return order KPI metrics for the given date range — used to populate the orders dashboard overview.
  • Query parameters:
Request example:
Success response 200 OK:
Error responses:
  • 422 Invalid date format.

​
PUT /2023-11/admin/orders/status/bulk-update

Update the shipping and/or billing status for multiple orders in one call. For billing status transitions to paid, the unpaid remainder is resolved automatically.
  • Request body:
Request example:
Success response 200 OK:
Error responses:
  • 400 Ghost order detected (Cannot update a ghost order).
  • 500 Business exception during processing.

​
GET /2023-11/admin/orders/{orderId}

Retrieve full details of a single order, including all relationships.
  • Path parameters:
Request example:
Success response 200 OK:
Error responses:
  • 404 Order not found: {"status":"error","code":404,"data":null,"message":"The order does not exist"}
  • 401 Unauthorized.

​
PUT /2023-11/admin/orders/{orderId}

Update an existing order. Runs the same UpsertOrderProcess as creation. Cannot remove products or decrease quantities if a final paid invoice exists.
  • Path parameters:
  • Request body: All fields are optional (partial update). Pass "type": "simple" with "metadata" to perform a lightweight metadata-only patch without full order reprocessing.
Request example:
Success response 200 OK — returns full OrderDetailResource:
Error responses:
  • 400 Cannot update an invoiced order that has a final paid invoice if products are being removed or quantities decreased.
  • 404 Order not found.

​
DELETE /2023-11/admin/orders/{orderId}

Cancel (soft-delete) an order. Orders with invoices or payments are transitioned to CANCELLED state; their invoices are undone. Pass force=true to permanently delete an order with no invoices, payments, or returns.
  • Path parameters:
  • Query parameters:
Request example:
Success response 200 OK — soft-delete returns OrderDetailResource with deleted_at populated:
For ?force=true (permanent delete with no related documents), returns:
Error responses:
  • 404 Order not found.
  • 500 Processing error.

​
GET /2023-11/admin/orders/{orderId}/activities

List the activity log for an order (paginated).
  • Path parameters:
  • Query parameters:
Request example:
Success response 200 OK:
Error responses:
  • 404 Order not found.

​
GET /2023-11/admin/orders/{orderId}/products

Return all order product lines for an order, including their pivot metadata and linked product records.
  • Path parameters:
Request example:
Success response 200 OK — raw array of OrderProduct models with eager-loaded product:
Error responses:
  • 404 Order not found.
  • 500 Internal error.

​
PATCH /2023-11/admin/orders/{orderId}/products/{orderProductId}/status

Update the fulfillment status of a single order product line.
  • Path parameters:
  • Request body:
Request example:
Success response 200 OK:
Error responses:
  • 404 Order or order product not found.
  • 500 Internal error.

​
POST /2023-11/admin/orders/{orderId}/restore

Restore a cancelled order by duplicating it as a new active order with a fresh reference. Billing/shipping statuses are reset to pending.
  • Path parameters:
Request example: Request body: None — no body required for this action endpoint.
Success response 200 OK — returns OrderDetailResource of the newly created order:
Error responses:
  • 400 Order is not cancelled.
  • 404 Order not found.
  • 500 Internal error.

​
PUT /2023-11/admin/orders/{orderId}/state

Transition an order to a different document state. Valid states: 1 (Invoice), 2 (Quotation), 3 (Sales Order). Converting a Sales Order to an Invoice creates a new linked invoice-state order. Converting to Invoice also deducts stock if stock tracking is enabled.
  • Path parameters:
  • Request body:
Request example:
Success response 200 OK — returns OrderDetailResource:
Error responses:
  • 400 Invalid state value, or insufficient stock when transitioning to Invoice state (includes descriptive message about which product/warehouse).
  • 404 Order not found.

​
POST /2023-11/admin/orders/{order}/notify

Send an order confirmation notification to the customer (email) and to all shop users who have the VIEW_ORDERS permission.
  • Path parameters:
  • Query parameters / request body (optional):
Request example:
Success response 200 OK:
Error responses:
  • 500 Notification delivery error with message.

​
POST /2023-11/admin/orders/{order}/payments

Record a payment against an order. Runs PaidOrderProcess which updates the billing status, creates accounting book entries, and optionally generates a credit note.
  • Path parameters:
  • Request body:
Request example:
Success response 200 OK:
Error responses:
  • 500 Payment processing error with message.

​
PUT /2023-11/admin/orders/{order}/payments/{payment}

Update an existing payment on an order (e.g. correct amount, method, or date). Runs UpdatePaymentProcess and logs an activity entry.
  • Path parameters:
  • Request body:
Request example:
Success response 200 OK — returns OrderDetailResource:
Error responses:
  • 400 Processing error with message.

​
DELETE /2023-11/admin/orders/{order}/payments/{payment}

Soft-delete a payment from an order. Runs DeletePaymentProcess which reverses billing status changes and logs an activity entry.
  • Path parameters:
Request example:
Success response 200 OK — returns OrderDetailResource:
Error responses:
  • 400 Processing error with message.

​
POST /2023-11/admin/orders/{order}/payments/{payment}/restore

Restore a previously soft-deleted payment. Runs RestorePaymentProcess and logs an activity entry.
  • Path parameters:
Request example: Request body: None — no body required for this action endpoint.
Success response 200 OK — returns OrderDetailResource:
Error responses:
  • 400 Processing error with message.

​
PUT /2023-11/admin/orders/{order}/status

Update shipping and/or billing status for a single order. Billing status changes to pending automatically create a credit note reversing existing inbound payments.
  • Path parameters:
  • Request body:
Allowed shipping statuses: pending, taken_in_charge, delivered, partial_delivery. Allowed billing statuses: pending, paid, partially_paid, unpaid, canceled. Request example:
Success response 200 OK — returns OrderDetailResource:
Error responses:
  • 400 Invalid shipping status or business rule violation.
  • 500 BusinessException with message.

​
Order Subscriptions

​
GET /2023-11/admin/order_subscriptions

List order-to-subscription link records (paginated).
  • Query parameters:
Request example:
Success response 200 OK:

​
Invoices

​
GET /2023-11/admin/invoices

List invoices with filtering and sorting (paginated).
  • Query parameters:
Request example:
Success response 200 OK:

​
POST /2023-11/admin/invoices

Create an invoice from an existing order or from a set of delivery IDs. The order must have at least one product, and the deliveries must contain at least one item.
  • Request body:
Request example:
Success response 200 OK — returns full InvoiceResource:
Error responses:
  • 400 Neither order_id nor delivery_ids provided.
  • 404 Order not found.
  • 422 Order has no products, or deliveries contain no items.
  • 500 Internal error.

​
GET /2023-11/admin/invoices/{invoice}

Retrieve a single invoice with its company, order, order shop/customer, lines, and credit notes.
  • Path parameters:
Request example:
Success response 200 OK:
Error responses:
  • 404 Invoice not found.

​
PUT /2023-11/admin/invoices/{invoice}

Update invoice status.
  • Path parameters:
  • Request body:
Request example:
Success response 200 OK — returns full InvoiceResource:

​
DELETE /2023-11/admin/invoices/{invoice}

Delete a pending invoice (soft-delete). Only invoices with status = pending can be deleted.
  • Path parameters:
Request example:
Success response 204 No Content. Error responses:
  • 403 Invoice is not in pending status: {"message":"You can only delete pending invoices."}

​
DELETE /2023-11/admin/invoices/{invoice}/payments/{payment}

Remove a payment from an invoice. Runs DeletePaymentProcess.
  • Path parameters:
Request example:
Success response 204 No Content. Error responses:
  • 404 Invoice or payment not found.

​
Invoice Rendering (Public)

These endpoints are publicly accessible (no Authorization header required) and return HTML views or PDF files rather than JSON.

​
GET /2023-11/invoices/{orderId}

Render the order invoice as an HTML page. Supports ?receipt=1 to switch to a compact receipt view with a QR code.
  • Path parameters:
  • Query parameters:
Success response 200 OK — HTML content (text/html).

​
GET /2023-11/invoices/{orderId}/invoice

Render the order invoice as a downloadable PDF (A4 format). Supports ?receipt=1 for a receipt HTML view instead.
  • Path parameters:
Same query parameters as the HTML view above. Success response 200 OK — PDF binary (application/pdf) or HTML if ?receipt is present.

​
GET /2023-11/invoice/{orderId}

Public alias for GET /admin/orders/{orderId} — returns the same OrderDetailResource JSON. Used by external pages (e.g. customer-facing invoice portal).
  • Path parameters:
Request example:
Success response 200 OK — same shape as GET /2023-11/admin/orders/{orderId}:
Error responses:
  • 404 Order not found.

​
PUT /2023-11/invoice/{order}/signature

Attach a base64-encoded signature image to an order. The signature is stored in the signature Spatie media collection and metadata is recorded on the order.
  • Path parameters:
  • Request body:
Request example:
Success response 200 OK — returns full OrderDetailResource with signature populated:

​
Invoice Generator (Public)

A lightweight stateless invoice generator that accepts arbitrary data, caches it for 30 minutes behind a token, and renders a printable HTML page.

​
POST /2023-11/invoice-generator/prepare

Store invoice data in cache and return a short-lived token and URL.
  • Request body: Any JSON object. Recognized top-level keys:
Request example:
Success response 200 OK:

​
GET /2023-11/invoice-generator/{token}

Render the previously prepared invoice as a printable HTML page (auto-prints via JavaScript). The token expires after 30 minutes.
  • Path parameters:
Success response 200 OK — HTML content (text/html). Error responses:
  • 404 Token not found or expired.

​
Credit Notes

​
GET /2023-11/admin/credit-notes

List credit notes (paginated), with filtering and sorting.
  • Query parameters:
Request example:
Success response 200 OK:

​
GET /2023-11/admin/credit-notes/{creditNote}

Retrieve full details of a single credit note, including lines, taxes, book entries, and refund payments.
  • Path parameters:
Request example:
Success response 200 OK — same shape as the list item above, with lines fully populated:
Error responses:
  • 404 Credit note not found.

​
Checkout

​
GET /2023-11/checkout

Render the Mamoni payment checkout HTML page for a given order. This is a public page loaded in a browser; it is not a JSON API endpoint.
  • Query parameters:
Success response 200 OK — HTML content (text/html), renders the Mamoni payment form. Error responses:
  • 404 Order not found or order does not belong to the specified company.