List Purchase Orders (batchwise)
POST /api/external/v1/po/getOrdersBatchwise
Returns Purchase Orders in fixed pages of 200, using batch as a 0-indexed page number
(batch=0 → rows 1-200, batch=1 → rows 201-400, etc.). Combine with filters to narrow results.
Request body (GetAllPurchaseOrdersBatchwiseRequest)
| Field | Type | Required | Description |
|---|---|---|---|
batch | integer | No (default 0) | 0-indexed page number, 200 rows per page |
filters | object | Yes (can be {}) | See table below |
filters object (PoFilters)
| Field | Type | Description |
|---|---|---|
status | string[] | Filter by PO status label (readable_status — see Purchase Order Filters) |
is_acknowledged | boolean | false = only POs you haven't acknowledged yet; true = only acknowledged ones |
is_updated_since_acknowledged | boolean | true = only POs that changed after you acknowledged them |
so_generated | boolean | Only POs with/without a Sales Order reference (reference_number) written back |
user_warehouse | string[] | Filter by assigned warehouse ID |
received_start_date | datetime | PO received-date range start |
received_end_date | datetime | PO received-date range end |
expiry_start_date | datetime | PO expiry-date range start |
expiry_end_date | datetime | PO expiry-date range end |
appointment_start_date | datetime | Appointment-date range start |
appointment_end_date | datetime | Appointment-date range end |
is_processed_by_warehouse | boolean | Only POs marked processed/unprocessed by the warehouse |
is_expired | boolean | Only expired/non-expired POs |
has_invoice | boolean | Only POs with/without an invoice generated |
remark_type | string[] | Filter by remark type tags |
channel | string[] | Filter by sales channel |
batch | string[] | Filter by batch number (client-defined grouping, not the pagination batch above) |
search_string | string | Free-text search value |
search_type | string | Which field search_string searches, e.g. po_number, batch_number |
Date ranges only apply when both the start and end of the pair are set. Results are ordered by
received_date, newest first.
Request Example
{
"batch": 0,
"filters": {
"status": ["NEW"],
"received_start_date": "2026-08-01T00:00:00Z",
"received_end_date": "2026-08-11T23:59:59Z"
}
}
Response 200 OK
data.purchase_orders is an array of Purchase Order objects. This is a complete response for
one PO: every PO always carries all of these keys, with null where there is no value. The
types of each field are in Purchase Order Object Reference. An
empty array (not null) is returned when nothing matches.
{
"success": true,
"status_code": 200,
"message": "Successfully fetched purchase orders batchwise",
"data": {
"purchase_orders": [
{
"user_id": "9f2b1e10-3c1d-4b7a-9a52-1f6c2d8e4a10",
"po_id": "b6b2a3e1-0c61-4fd2-9a07-3bf2035888f1",
"reference_number": null,
"po_number": "PO-2026-00123",
"shipping_label_url": null,
"customer_warehouse_name": "Acme Retail Gurgaon FC",
"customer_warehouse_id": "3d8db3ab-4edf-4320-a568-55eef18a0e28",
"fc_code": "154",
"customer_name": "Acme Retail Pvt Ltd",
"customer_address": "Plot 12, Industrial Area, Gurugram",
"customer_city": "Gurgaon",
"customer_state": "Haryana",
"customer_pincode": "122103",
"customer_email": null,
"customer_phone": null,
"customer_gstin": "06AAACA1234A1Z5",
"customer_pan": "AAACA1234A",
"customer_billing_name": "Acme Retail Pvt Ltd",
"customer_billing_address": "Plot 12, Industrial Area, Gurugram",
"customer_billing_city": "Gurgaon",
"customer_billing_state": "Haryana",
"customer_billing_pincode": "122103",
"customer_billing_email": null,
"customer_billing_phone": null,
"customer_billing_gstin": "06AAACA1234A1Z5",
"customer_billing_pan": "AAACA1234A",
"vendor_name": "Your Company Pvt Ltd",
"vendor_address": "Godown 3, MIDC, Bhiwandi",
"vendor_city": "Thane",
"vendor_state": "Maharashtra",
"vendor_pincode": "421302",
"vendor_email": null,
"vendor_phone": null,
"vendor_gstin": "27AAACY1234B1ZX",
"vendor_pan": "AAACY1234B",
"sku_details": [
{
"id": "801a32ab-8d06-4754-93e4-d48c864de56e",
"code": "SKU-001",
"hsn": "39241090",
"name": "Water Bottle 1L",
"description": "Water Bottle 1L, Assorted",
"channel_code": "100245",
"quantity": 96,
"cost_price": 102.57,
"price": 121.03,
"mrp": 260,
"tax_amount": 18.46,
"taxable_amount": 102.57,
"cgst": 0,
"cgst_percentage": 0,
"sgst": 0,
"sgst_percentage": 0,
"igst": 18.46,
"igst_percentage": 18,
"cess": 0,
"cess_percentage": 0,
"price_difference": 0,
"mrp_difference": 0,
"cgst_difference": 0,
"sgst_difference": 0,
"igst_difference": 0,
"cess_difference": 0,
"type": null,
"category": null,
"subcategory": null,
"channel": "swiggy_instamart",
"is_active": true,
"ean": "",
"original_ean": "",
"original_quantity": null,
"delivered_quantity": null,
"fill_rate_percentage": null,
"gmv_loss": null,
"dn_quantity": null,
"dn_reason": null,
"inventory": null,
"remarks": null,
"length": 0,
"breadth": 0,
"height": 0,
"weight": 0
}
],
"quantity": 96,
"tax_amount": 1772.16,
"total_amount": 9846.72,
"taxable_amount": 9846.72,
"mrp_amount": 24960,
"applicable_tax": [
"igst",
"cess"
],
"received_date": "2026-10-01T05:11:52.265968Z",
"release_date": "2026-10-01T00:00:00Z",
"expires_at": "2026-10-30T00:00:00Z",
"so_date": null,
"transaction_type": null,
"assigned_warehouse_id": null,
"sap_whs_code": null,
"is_assigned": false,
"is_fulfilled": false,
"is_processed_by_warehouse": false,
"status": "NEW",
"readable_status": "NEW",
"channel": "swiggy_instamart",
"batch_number": null,
"invoice_number": null,
"invoice_date": null,
"ewaybill_number": null,
"note": null,
"created_at": "2026-10-01T05:11:52.290064Z",
"appointment_scheduled_at": null,
"is_appointment_confirmed": false,
"is_grn_received": false,
"po_processed_by_warehouse_at": null,
"warehouse_name": null,
"warehouse_manager_name": null,
"warehouse_email": null,
"warehouse_phone": null,
"warehouse_address_line_1": null,
"warehouse_address_line_2": null,
"warehouse_city": null,
"warehouse_pincode": null,
"warehouse_state": null,
"warehouse_country": null,
"warehouse_is_enabled": null,
"uploaded_documents": null,
"master_waybill": null,
"child_waybills": null,
"asn_number": null,
"invoice_data": null,
"invoice_id": null,
"swiggy_idempotency_id": null,
"custom_data": null,
"remarks": [],
"has_draft_order": false,
"sync_hash": "2558036659a711c6f7a5e475067d3d82",
"acknowledged_at": null,
"is_updated_since_acknowledged": false
}
]
}
}
For the full field list, exact data type of every field, and which field is the primary key
(po_id vs. po_number), see Purchase Order Object Reference.
To pull only new POs, and to detect POs that changed after you fetched them, see Acknowledge Purchase Orders and its recommended sync flow.