https://api.genuka.com · Auth Authorization: Bearer <token> + X-Company: <companyId> · See Getting Started for shared conventions, pagination & error formats.
Endpoints at a glance
Suppliers
GET /2023-11/admin/suppliers
List all suppliers for the authenticated company.
- Query parameters:
Request example:
200 OK):
400 Bad Request— missingX-Companyheader (company_id_required)401 Unauthorized— invalid or expired token
POST /2023-11/admin/suppliers
Create a new supplier. Either first_name or last_name must be provided. Either email or phone must be provided. The combination of name + email (or name + phone) must be unique within the company.
- Request body:
Request example:
200 OK):
400 Bad Request— validation failed (e.g. duplicate email+name within the company):500 Internal Server Error— unexpected database error
POST /2023-11/admin/suppliers/export
Export all suppliers for the company (or a specific shop) as a CSV file. The response is a binary CSV download.
- Request body:
Request example:
200 OK): Binary CSV file (Content-Disposition: attachment; filename="suppliers_<name>.csv").
Error responses:
401 Unauthorized— invalid token
GET /2023-11/admin/suppliers/{supplier}
Get full details for a single supplier including aggregated stats (total spent, total sold, top products, bills by day).
- Path parameters:
Request example:
200 OK):
404 Not Found— supplier does not exist or belongs to a different company
PUT /2023-11/admin/suppliers/{supplier}
Update a supplier. All fields are optional; only provided fields are changed. Email and phone uniqueness is validated ignoring the current supplier’s own values.
- Path parameters:
- Request body:
Request example:
200 OK):
400 Bad Request— duplicate email/phone within the company404 Not Found— supplier not found
DELETE /2023-11/admin/suppliers/{supplier}
Soft-delete a supplier. Pass force=true to permanently delete.
- Path parameters:
- Query parameters:
Request example:
200 OK):
404 Not Found— supplier not found
POST /2023-11/admin/suppliers/{supplier}/products/link
Bulk-assign catalog Product records to a supplier by setting supplier_id on each product.
- Path parameters:
- Request body:
Request example:
200 OK):
errors array contains human-readable messages for any products that failed to link.
Error responses:
404 Not Found— supplier not found
Supplier Products
Supplier products (supplierproducts) are purchasable items linked to bills. They may optionally reference a catalog ProductVariant.
GET /2023-11/admin/supplierProducts
List all supplier products for the company.
- Query parameters:
Request example:
200 OK):
POST /2023-11/admin/supplierProducts
Create a new supplier product. The handle is auto-generated from the title (slugified); if a collision exists, a random 8-character suffix is appended.
- Request body:
Request example:
200 OK):
GET /2023-11/admin/supplierProducts/handle/{supplierproduct}
Retrieve a supplier product by its handle slug. Same response shape as the ID-based show endpoint.
- Path parameters:
- Query parameters: Supports the same
includevalues as the list endpoint.
200 OK):
GET /2023-11/admin/supplierProducts/{supplierproduct}
Get a single supplier product by ID. Passing analytics=1 adds detailed analytics data (top suppliers, total bills, total sales, related products).
- Path parameters:
- Query parameters:
Request example:
200 OK):
404 Not Found— supplier product not found
PUT /2023-11/admin/supplierProducts/{supplierproduct}
Update a supplier product. The handle is regenerated from the new title.
- Path parameters:
- Request body:
Request example:
200 OK):
DELETE /2023-11/admin/supplierProducts/{supplierproduct}
Soft-delete a supplier product.
- Path parameters:
Request example:
200 OK):
PUT /2023-11/admin/supplierProducts/{supplierproduct}/{field}
Update a single named field on a supplier product. Supported fields include any model attribute, plus the special value shops which replaces the many-to-many shop associations.
- Path parameters:
- Request body:
Request example:
200 OK):
Bills
A Bill represents a purchase invoice from a supplier. It tracks line items (supplier products), billing information, payment status, and optionally shipping. Bills can also exist in apurchase_order state before being converted to a formal bill.
GET /2023-11/admin/bills
List all bills for the company.
- Query parameters:
Request example:
200 OK):
POST /2023-11/admin/bills
Create a new bill (purchase invoice). Products are linked via supplier_product_id on each line item. The reference number is auto-generated. Billing totals are derived from the billing.total value.
- Request body:
Request example:
200 OK):
422 Unprocessable Entity— validation errors from nested process tasks500 Internal Server Error— database error (response includesmessage)
POST /2023-11/admin/bills/export
Trigger an async export of bills. The export is queued and delivered via the company’s notification channel. Returns a job acknowledgment immediately.
- Request body:
Request example:
- Small dataset (< 500 rows) —
200 OK: Binary file download withContent-Disposition: attachment; filename="bills.<format>"and appropriateContent-Type(e.g.application/vnd.openxmlformats-officedocument.spreadsheetml.sheetfor xlsx). - Large dataset (≥ 500 rows) —
202 Accepted: Job queued; the file link is delivered by email.
401 Unauthorized— user not authenticated422 Unprocessable Entity— unsupported format value
GET /2023-11/admin/bills/export/fields
Return the list of available column names for bill exports.
Request example:
200 OK):
POST /2023-11/admin/bills/import
Import bills from an xlsx, xls, or csv file.
- Request body (multipart/form-data):
Request example:
200 OK):
422 Unprocessable Entity— file validation failed500 Internal Server Error— parsing/import error
POST /2023-11/admin/bills/purchase-order
Create a bill in the purchase order state (state = 2). If the expense type is not SUPPLIER, the bill is immediately marked as paid via PaidBillProcess and stock movements are applied.
- Request body: Same fields as
POST /2023-11/admin/bills. Key fields are listed below. Setstate: 2(or omit — the process will enforce state 2).
Request example:
200 OK):
GET /2023-11/admin/bills/{billId}
Get full details for a single bill including supplier, products, payments, credit notes, and accounting info.
- Path parameters:
Request example:
200 OK):
404 Not Found— bill not found (viafirstOrFail)
GET /2023-11/admin/bills/{billId}/products
Return the raw list of supplier products attached to a bill (without full BillDetailResource wrapping).
- Path parameters:
Request example:
200 OK):
404 Not Found— bill not found
PUT /2023-11/admin/bills/{bill}
Update an existing bill. All product lines are re-synced (existing pivot rows are replaced). Existing accounting book entries are reverted and recreated.
- Path parameters:
- Request body: Same fields as
POST /2023-11/admin/bills. Key fields are listed below.
Request example:
200 OK):
500 Internal Server Error— update failed (includesmessage)
DELETE /2023-11/admin/bills/{bill}
Soft-delete a bill. Pass force=true to permanently delete.
- Path parameters:
- Query parameters:
Request example:
200 OK): full BillDetailResource with deleted_at set. On force-delete (200 OK): {"message":"Bill deleted"}.
Error responses:
404 Not Found— bill not found
POST /2023-11/admin/bills/{bill}/payments
Add a payment to a bill. Creates a Payment record (type = OUTBOUND), updates the bill’s billing status (pending → partially_paid → paid based on totals).
- Path parameters:
- Request body:
Request example:
200 OK): Full BillDetailResource with updated payments array and billing.status. The payments array will contain the newly added payment:
500 Internal Server Error— payment creation failed
PUT /2023-11/admin/bills/{bill}/payments/{payment}
Update an existing payment on a bill (via UpdatePaymentProcess).
- Path parameters:
- Request body:
Request example:
200 OK): Full BillDetailResource with the updated payment reflected in payments[]. Same shape as GET /2023-11/admin/bills/{billId}.
400 Bad Request— update error (viaBusinessException)
DELETE /2023-11/admin/bills/{bill}/payments/{payment}
Delete a payment from a bill. The bill’s billing status is recalculated. Activity is logged.
- Path parameters:
Request example:
200 OK): Full BillDetailResource with the deleted payment removed from payments[] and billing.status recalculated. Same shape as GET /2023-11/admin/bills/{billId}.
400 Bad Request— deletion error
POST /2023-11/admin/bills/{bill}/payments/{payment}/restore
Restore a soft-deleted payment. Activity is logged.
- Path parameters:
- Query parameters:
Request example:
Request body: None — no body required for this action endpoint.
200 OK): Full BillDetailResource with the restored payment back in payments[] and billing.status recalculated. Same shape as GET /2023-11/admin/bills/{billId}.
400 Bad Request— restore error
PUT /2023-11/admin/bills/{bill}/state
Transition the bill’s state. Currently supports transitioning from purchase_order (2) to bill (1), which generates a new reference number and stores the original purchase order ID in metadata.
- Path parameters:
- Request body:
Request example:
200 OK): Full BillDetailResource with the updated state and new reference. Same shape as GET /2023-11/admin/bills/{billId}.
400 Bad Request— invalid state value
PUT /2023-11/admin/bills/{bill}/status
Update the bill’s shipping and/or billing status. Can also update metadata. If billing is present, a payment is processed via PaidBillProcess.
- Path parameters:
- Request body:
Request example:
200 OK): Full BillDetailResource with the updated shipping/billing status. Same shape as GET /2023-11/admin/bills/{billId}.
no_response: true is passed:
Bills of Materials
A Bill of Materials (BoM) defines a production recipe: it links input stocks (raw materials consumed) to output stocks (finished goods produced). Quantities are stored on the pivot.GET /2023-11/admin/bill-of-materials
List all bills of materials for the company.
- Query parameters:
Request example:
200 OK):
POST /2023-11/admin/bill-of-materials
Create a bill of materials with input and output stock references. Inputs and outputs are synced via pivot tables; existing associations are replaced.
- Request body:
Request example:
201 Created):
422 Unprocessable Entity—inputsoroutputsmissing404 Not Found— a stock ID in inputs or outputs does not exist
GET /2023-11/admin/bill-of-materials/reference/{billOfMaterial}
Retrieve a bill of materials by its reference value (route-model-bound by the billOfMaterial parameter slug). Response shape is identical to the ID-based show endpoint.
- Path parameters:
Request example:
200 OK):
GET /2023-11/admin/bill-of-materials/{billOfMaterial}
Get a single bill of materials by ID.
- Path parameters:
Request example:
200 OK):
PUT /2023-11/admin/bill-of-materials/{billOfMaterial}
Update a bill of materials. Inputs and outputs are fully re-synced (replacing existing pivot rows).
- Path parameters:
- Request body:
Request example:
200 OK):
DELETE /2023-11/admin/bill-of-materials/{billOfMaterial}
Soft-delete a bill of materials.
- Path parameters:
Request example:
200 OK):
Production Orders
A Production Order executes a Bill of Materials for a given number of cycles. On creation, the system checks stock availability, deducts input stocks (FIFO by warehouse), and adds the produced output stocks to the target warehouse. Deleting a production order reverses these stock movements.GET /2023-11/admin/production-orders
List all production orders for the company.
- Query parameters:
Request example:
200 OK):
POST /2023-11/admin/production-orders
Create a production order. The system validates that enough stock is available for the requested cycle count, then deducts raw-material stock (FIFO) and produces finished-good stock in the target warehouse.
- Request body:
Request example:
201 Created):
404 Not Found— bill of materials not found422 Unprocessable Entity— insufficient stock for the requested cycle count:500 Internal Server Error— stock movement failed
GET /2023-11/admin/production-orders/reference/{productionOrder}
Retrieve a production order by its reference. Response shape is identical to the ID-based show endpoint.
- Path parameters:
Request example:
200 OK):
GET /2023-11/admin/production-orders/{productionOrder}
Get a single production order by ID.
- Path parameters:
Request example:
200 OK):
404 Not Found— production order not found
PUT /2023-11/admin/production-orders/{productionOrder}
Update a production order.
Note: This endpoint is declared in the route table but the controller method body is currently empty (not yet implemented). It returns an empty 200 OK response.
- Path parameters:
- Request body:
Success response (
200 OK): Empty body — the controller implementation is pending.
DELETE /2023-11/admin/production-orders/{productionOrder}
Delete a production order. Side effect: all associated stock movements are reversed (input stocks are restored, output stocks are decremented). Pass force=true to permanently delete.
- Path parameters:
- Query parameters:
Request example:
200 OK):
404 Not Found— production order not found
Expense Types
Expense types are accounting categories used to classify bills. Each type has a debit and credit account code pair, and must be unique by handle within the company.GET /2023-11/admin/expense-types
List all expense types for the company.
- Query parameters:
Request example:
200 OK):
POST /2023-11/admin/expense-types
Create an expense type. The handle must be unique within the company. credit_code and debit_code must differ.
- Request body:
Request example:
200 OK):
400 Bad Request—credit_codeequalsdebit_code:422 Unprocessable Entity—handlenot unique in company:
PUT /2023-11/admin/expense-types/{expenseType}
Update an expense type. All fields are optional. credit_code and debit_code must still differ if both are provided.
- Path parameters:
- Request body:
Request example:
200 OK):
400 Bad Request—credit_codeequalsdebit_code
DELETE /2023-11/admin/expense-types/{expenseType}
Delete an expense type. All bills that referenced this expense type are reassigned to the default expense type (the one with handle = null, or the first available).
- Path parameters:
Request example:
204 No Content): Empty body.