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

/purchase-order

📦 1. Create Purchase Order

Endpoint

POST /purchase-order

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.

Required Headers

Key	Value
`Authorization`	`Bearer <JWT_TOKEN>`
`Content-Type`	`multipart/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
`supplierId`	`string` (UUID)	✅	The supplier’s unique ID
`purchaseDate`	`string` (Date)	✅	The date of the purchase order (format: `YYYY-MM-DD`)
`doc_status`	`"DRAFT" \| "PUBLISHED" \| "CANCELED"`	✅	The current status of the purchase order
`purchaseOrderItems`	`array`	✅	List of purchase order items
`purchaseOrderItems[].itemName`	`string`	✅	The variant name or ID
`purchaseOrderItems[].quantity`	`number`	✅	Quantity ordered
`purchaseOrderItems[].price`	`number`	✅	Price per unit
`purchaseOrderItems[].priceTotal`	`number`	⚙️	(Optional) Calculated client-side total

Example Requests

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}]}'

const formData = new FormData();

const 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
    }
  ]
};

formData.append('jsonData', JSON.stringify(jsonData));

const response = await fetch('https://jethings-backend.fly.dev/purchase-order', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`
  },
  body: formData
});

const result = await response.json();

const formData = new FormData();

const 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
    }
  ]
};

formData.append('jsonData', JSON.stringify(jsonData));

fetch('https://jethings-backend.fly.dev/purchase-order', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`
  },
  body: formData
})
  .then(response => response.json())
  .then(data => console.log(data));

import requests
import json

url = "https://jethings-backend.fly.dev/purchase-order"

json_data = {
    "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
        }
    ]
}

response = requests.post(
    url,
    headers={
        'Authorization': f'Bearer {access_token}'
    },
    data={'jsonData': json.dumps(json_data)}
)

print(response.json())

import 'dart:convert';
import 'package:http/http.dart' as http;

final url = Uri.parse('https://jethings-backend.fly.dev/purchase-order');

final 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
    }
  ]
};

final request = http.MultipartRequest('POST', url);
request.headers['Authorization'] = 'Bearer $accessToken';
request.fields['jsonData'] = jsonEncode(jsonData);

final response = await request.send();
final responseData = await response.stream.bytesToString();
print(jsonDecode(responseData));

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

GET /purchase-order

Description

Returns a paginated list of all purchase orders for a specific store. This endpoint supports filtering, searching, sorting, and pagination.

Required Headers

Key	Value
`Authorization`	`Bearer <JWT_TOKEN>`

Query Parameters

Parameter	Type	Default	Description
`search`	`string`	–	Search by supplier name
`supplierName`	`string`	–	Filter by supplier name
`page`	`number`	`1`	Current page number
`limit`	`number`	`10`	Number of results per page
`sortBy`	`string`	`createdAt`	Sort field (`createdAt`, `updatedAt`, or `supplierName`)
`sortOrder`	`"asc" \| "desc"`	`"desc"`	Sorting order

Example Requests

curl -X GET "https://jethings-backend.fly.dev/purchase-order?page=1&limit=10&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch(
  'https://jethings-backend.fly.dev/purchase-order?page=1&limit=10&sortBy=createdAt&sortOrder=desc',
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();

fetch('https://jethings-backend.fly.dev/purchase-order?page=1&limit=10&sortBy=createdAt&sortOrder=desc', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

import requests

url = "https://jethings-backend.fly.dev/purchase-order"
params = {
    "page": 1,
    "limit": 10,
    "sortBy": "createdAt",
    "sortOrder": "desc"
}

response = requests.get(
    url,
    headers={
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json'
    },
    params=params
)

print(response.json())

import 'package:http/http.dart' as http;
import 'dart:convert';

final url = Uri.parse('https://jethings-backend.fly.dev/purchase-order')
    .replace(queryParameters: {
  'page': '1',
  'limit': '10',
  'sortBy': 'createdAt',
  'sortOrder': 'desc'
});

final response = await http.get(
  url,
  headers: {
    'Authorization': 'Bearer $accessToken',
    'Content-Type': 'application/json'
  },
);

final data = jsonDecode(response.body);
print(data);

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
`DRAFT`	Purchase order is in draft status
`PUBLISHED`	Purchase order has been published/sent
`CANCELED`	Purchase order has been canceled

Common Error Codes

Status Code	Description	Possible Causes
`400`	Bad Request	Invalid request data, missing required fields
`401`	Unauthorized	Missing or invalid authentication token
`403`	Forbidden	User does not have access to the store
`404`	Not Found	Supplier not found or invalid ID
`500`	Internal 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 purchaseDate
Purchase 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

Purchase Invoice API - Create and manage purchase invoices
Stores API - Manage stores and store access

​Purchase Order API

​Base URL

​📦 1. Create Purchase Order

​Endpoint

​Description

​Required Headers

​Body Parameters

​Example Requests

​Success Response (200)

​Error Responses

​403 Forbidden

​400 Bad Request

​Notes

​📋 2. Get All Purchase Orders

​Endpoint

​Description

​Required Headers

​Query Parameters

​Example Requests

​Success Response (200)

​Error Responses

​403 Forbidden

​400 Bad Request

​Notes

​Status Values

​Common Error Codes

​Business Logic

​Purchase Order Creation Flow

​Purchase Order Retrieval Flow

​Related APIs

Purchase Order API

Base URL

📦 1. Create Purchase Order

Endpoint

Description

Required Headers

Body Parameters

Example Requests

Success Response (200)

Error Responses

403 Forbidden

400 Bad Request

Notes

📋 2. Get All Purchase Orders

Endpoint

Description

Required Headers

Query Parameters

Example Requests

Success Response (200)

Error Responses

403 Forbidden

400 Bad Request

Notes

Status Values

Common Error Codes

Business Logic

Purchase Order Creation Flow

Purchase Order Retrieval Flow

Related APIs