API reference

Orders

The order lifecycle a channel or logistics partner works with: place orders, read and filter them, record payments and refunds, and pull invoices. Orders are identified by a human-readable referenceNumber and scoped to a storeId. Keep your own id in clientId. To track an order in transit, see Fulfillment & Delivery.

Base URLhttps://zopping.com

Orders

Create an order with a cart of items, read orders with rich filters, and update status. Each cart line uses id (product/item id) and q (quantity). The response referenceNumber is the id you use everywhere else.

Fields

Field	Type	Description
`id`	integerread-only
`referenceNumber`	stringread-only	Human-readable order id.
`organizationId`	stringrequired
`storeId`	integerrequired
`customerId`	integer	Or send a nested `customer` object.
`cart`	object[]required	Line items: `{ id, q, mrp, offerPrice, clientId }`.
`address`	string \| object	Delivery address or its id.
`payment`	string	Payment mode at placement.
`couponCode`	string
`preferredSlotId`	integer	Chosen delivery slot.
`status`	stringread-only	PENDING, CONFIRMED, …
`paymentStatus`	stringread-only
`amount`	stringread-only	Order total.
`clientId`	stringkey	Your external order id.

GET/api/order-service/order

List orders

Filter by store, customer, status, payment status, client id and date range. Paginated with `offset`/`limit`.

Parameters

Parameter	Type	Description
`organizationId`required	string· query
`storeId`	integer· query
`status`	string· query	e.g. PENDING, CONFIRMED, DELIVERED.
`customerId`	integer· query
`referenceNumber`	string· query
`clientId`	string· query	Your order id.
`limit`	integer· query
`offset`	integer· query

Request

curl "https://zopping.com/api/order-service/order?organizationId=<org-id>&storeId=<store-id>&status=CONFIRMED" \
  -H "Authorization: Bearer $ZOPPING_TOKEN"

Response

{
  "order": [
    {
      "id": 55012,
      "referenceNumber": "ORD-55012",
      "status": "CONFIRMED",
      "paymentStatus": "PENDING",
      "amount": "512.00",
      "storeId": "<store-id>",
      "customerId": 7781
    }
  ],
  "count": 1,
  "offset": 0,
  "limit": 50
}

POST/api/order-service/order

Create an order

Request body

{
  "organizationId": "<org-id>",
  "storeId": "<store-id>",
  "customerId": 7781,
  "cart": [
    {
      "id": "88120",
      "q": "2",
      "mrp": 28,
      "offerPrice": 26
    }
  ],
  "address": "12 MG Road, Bengaluru 560001",
  "payment": "ONLINE",
  "preferredSlotId": 31,
  "clientId": "EXT-ORDER-9001"
}

Response

{
  "order": {
    "id": 55012,
    "referenceNumber": "ORD-55012",
    "status": "PENDING",
    "amount": "52.00"
  }
}

GET/api/order-service/order/{id}

Get an order

Parameters

Parameter	Type	Description
`id`required	integer· path
`organizationId`required	string· query

PUT/api/order-service/order/{id}

Update an order

Update status and other mutable fields.

Parameters

Parameter	Type	Description
`id`required	integer· path

Order payments

Record a payment against an order. Modes include CASH, ONLINE, WALLET, GIFTCARD. Online payments return a redirectUrl / accessKey to hand off to the gateway.

Fields

Field	Type	Description
`orderReferenceNumber`	stringrequired
`organizationId`	stringrequired
`mode`	stringrequired	CASH · ONLINE · WALLET · GIFTCARD.
`amount`	stringrequired
`status`	enumread-only	PENDING · COMPLETED · FAILED.
`gatewayTransactionId`	stringread-only

POST/api/order-service/order/{id}/payment

Record a payment

Parameters

Parameter	Type	Description
`id`required	integer· path	Order id.

Request body

{
  "organizationId": "<org-id>",
  "orderReferenceNumber": "ORD-55012",
  "mode": "CASH",
  "amount": "52.00"
}

GET/api/order-service/order-payment

List payments

Parameters

Parameter	Type	Description
`organizationId`required	string· query
`orderReferenceNumber`	string· query

Refunds

Issue a refund against an order. Methods include ONLINE, CASH, WALLET, GIFTCARD.

Fields

Field	Type	Description
`orderId`	integerrequired
`method`	stringrequired
`amount`	stringrequired
`status`	enumread-only	STARTED · COMPLETED · FAILED.
`refundReference`	stringread-only

POST/api/order-service/order-refund

Create a refund

Request body

{
  "organizationId": "<org-id>",
  "orderId": 55012,
  "method": "ONLINE",
  "amount": "26.00"
}

GET/api/order-service/order-refund

List refunds

Parameters

Parameter	Type	Description
`organizationId`required	string· query
`orderReferenceNumber`	string· query

Invoices

Fetch the generated invoice (PDF URL/HTML) for an order.

GET/api/order-service/invoice/{referenceNumber}

Get invoice

Parameters

Parameter	Type	Description
`referenceNumber`required	string· path
`returnPdf`	boolean· query	Return the invoice PDF link as `pdfLink`.
`returnHtml`	boolean· query	Return the rendered invoice HTML as `view`.

Request

curl "https://zopping.com/api/order-service/invoice/ORD-55012?returnPdf=true&returnHtml=true" \
  -H "Authorization: Bearer $ZOPPING_TOKEN"

Response

{
  "invoice": {
    "pdfLink": "https://storage.googleapis.com/zopping-media/1/invoices/ORD-55012.pdf",
    "view": "<html>...</html>"
  }
}

Payment verification

After a gateway redirect, confirm a payment with verify-payment, or query the latest payment state for an order with payment-enquiry.

POST/api/order-service/verify-payment

Verify a payment

Request body

{
  "organizationId": "<org-id>",
  "transactionId": "TXN123",
  "transactionAmount": "52.00",
  "udf1": "ORD-55012",
  "transactionStatus": "SUCCESS"
}

POST/api/order-service/payment-enquiry

Enquire payment status

Request body

{
  "organizationId": "<org-id>",
  "referenceNumber": "ORD-55012"
}