Purchase Order API The Purchase Order API allows you to create purchase orders and retrieve a paginated list of all purchase orders for a store. Purchase orders track orders from suppliers before they are fulfilled.
All endpoints require authentication via Bearer token in the Authorization header. Users must have access to the store via userStoreRelation.
Base URL 📦 1. Create Purchase Order Endpoint Description Creates a new purchase order with its associated items. This endpoint accepts a multipart/form-data request with a JSON string under the key jsonData.
Key Value AuthorizationBearer <JWT_TOKEN>Content-Typemultipart/form-data
The request is restricted to users linked to the store via userStoreRelation. The store ID should be derived from the authenticated user’s store relations.
Body Parameters
The jsonData field must contain a JSON string in this format:
{ "supplierId" : "uuid" , "purchaseDate" : "2024-01-15" , "doc_status" : "DRAFT" , "purchaseOrderItems" : [ { "itemName" : "Variant ID or Name" , "quantity" : 10 , "price" : 25.5 , "priceTotal" : 255 }, { "itemName" : "Another Variant" , "quantity" : 5 , "price" : 15.0 , "priceTotal" : 75 } ] }
Field Type Required Description supplierIdstring (UUID)✅ The supplier’s unique ID purchaseDatestring (Date)✅ The date of the purchase order (format: YYYY-MM-DD) doc_status"DRAFT" | "PUBLISHED" | "CANCELED"✅ The current status of the purchase order purchaseOrderItemsarray✅ List of purchase order items purchaseOrderItems[].itemNamestring✅ The variant name or ID purchaseOrderItems[].quantitynumber✅ Quantity ordered purchaseOrderItems[].pricenumber✅ Price per unit purchaseOrderItems[].priceTotalnumber⚙️ (Optional) Calculated client-side total
Example Requests cURL
TypeScript
JavaScript
Python
Flutter
curl -X POST https://jethings-backend.fly.dev/purchase-order \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: multipart/form-data" \ -F 'jsonData={"supplierId":"uuid","purchaseDate":"2024-01-15","doc_status":"DRAFT","purchaseOrderItems":[{"itemName":"Variant ID or Name","quantity":10,"price":25.5,"priceTotal":255},{"itemName":"Another Variant","quantity":5,"price":15.0,"priceTotal":75}]}'
Success Response (200) { "success" : true , "purchaseOrder" : { "id" : "uuid" , "supplierId" : "uuid" , "storeId" : "uuid" , "createdAt" : "2024-01-15T10:00:00.000Z" , "updatedAt" : "2024-01-15T10:00:00.000Z" , "postingTime" : "2024-01-15T00:00:00.000Z" , "requiredBy" : "2024-01-15T00:00:00.000Z" , "updateStock" : true , "doc_status" : "DRAFT" }, "purchaseOrderItems" : [ { "id" : "uuid" , "purchaseOrderItem" : "uuid" , "itemVariant" : "Variant ID or Name" , "qty" : "10" , "price" : "25.5" } ] } Error Responses 403 Forbidden { "statusCode" : 403 , "message" : "You do not have access to this store" } 400 Bad Request { "statusCode" : 400 , "message" : "Validation error description" } Notes
The request is restricted to users linked to the store via userStoreRelation.
Automatically sets timestamps and initializes updateStock = true.
postingTime and requiredBy are both derived from purchaseDate.
📋 2. Get All Purchase Orders Endpoint Description Returns a paginated list of all purchase orders for a specific store. This endpoint supports filtering, searching, sorting, and pagination.
Key Value AuthorizationBearer <JWT_TOKEN>
Query Parameters
Parameter Type Default Description searchstring– Search by supplier name supplierNamestring– Filter by supplier name pagenumber1Current page number limitnumber10Number of results per page sortBystringcreatedAtSort field (createdAt, updatedAt, or supplierName) sortOrder"asc" | "desc""desc"Sorting order
Example Requests cURL
TypeScript
JavaScript
Python
Flutter
curl -X GET "https://jethings-backend.fly.dev/purchase-order?page=1&limit=10&sortBy=createdAt&sortOrder=desc" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Success Response (200) { "data" : [ { "invoiceId" : "uuid" , "supplierName" : "ACME Supplies" , "createdAt" : "2024-01-15T10:00:00.000Z" , "updatedAt" : "2024-01-15T11:00:00.000Z" , "amountPaid" : 0 , "paymentStatus" : "PAID" , "stockUpdate" : true } ], "pagination" : { "page" : 1 , "limit" : 10 , "total" : 25 , "totalPages" : 3 , "hasNext" : true , "hasPrev" : false } } Error Responses 403 Forbidden { "statusCode" : 403 , "message" : "You do not have access to this store" } 400 Bad Request { "statusCode" : 400 , "message" : "Invalid query parameters" } Notes
Requires store-level permission (validated by userStoreRelation).
Joins with the supplier table to retrieve supplier names.
Sorting, searching, and pagination are all supported.
This endpoint is ideal for displaying purchase order lists in dashboards.
Status Values The doc_status field in purchase orders can have the following values:
Status Description DRAFTPurchase order is in draft status PUBLISHEDPurchase order has been published/sent CANCELEDPurchase order has been canceled
Common Error Codes
Status Code Description Possible Causes 400Bad Request Invalid request data, missing required fields 401Unauthorized Missing or invalid authentication token 403Forbidden User does not have access to the store 404Not Found Supplier not found or invalid ID 500Internal Server Error Server error during processing
Business Logic Purchase Order Creation Flow
User creates a purchase order with supplier, date, status, and items
Purchase order is created with updateStock = true by default
postingTime and requiredBy are automatically set from purchaseDatePurchase order items are linked to the purchase order
User must have access to the store via userStoreRelation
Purchase Order Retrieval Flow
System validates user has access to the store
Retrieves purchase orders with supplier information (via join)
Applies filters, search, and sorting
Returns paginated results with metadata
