Guides
Orders & money
How an order moves from your store to your customer's door, and exactly what lands on your wallet at each step.
Order stages#
| status | Meaning | Webhook |
|---|---|---|
AWAITING_FUNDS | Prepaid only: your wallet could not cover it. It waits 72 hours for a top-up and POST /orders/{id}/pay, then is cancelled. | — |
RECEIVED | We have the order and have reserved the stock. | order.received |
CONFIRMED | Ready to pack. | order.confirmed |
PROCESSING | Being packed. From here it can no longer be cancelled. | — |
SHIPPED | With the courier; tracking has the courier and number. | order.shipped |
DELIVERED | Delivered and, for COD, paid by the customer. | order.delivered |
CANCELLED | By you, the customer or us — cancellationReason says why. | order.cancelled |
RETURNED | Refused at the door (type: rto) or returned after delivery (type: return). | order.returned |
You can cancel with POST /orders/{id}/cancel while the order is AWAITING_FUNDS, RECEIVED or CONFIRMED. Later you get 409 order_not_cancellable.
One order, several parcels#
MarkitMall products come from different sellers. When your order mixes products from more than one seller, it ships as one parcel per seller. The response to POST /orders lists them in parcels; each has its own id, status, tracking and money, and its own webhooks (with parcel: { part, of }). Your customer pays each parcel to its courier. Store the parcel ids.
Cash on delivery#
Your customer pays the courier. Nothing is taken from your wallet up front.
codAmount = Σ (resalePrice × quantity) + shippingCharged ← the courier collects this
margin = codAmount − wholesaleTotal − shippingCost (less 10% platform fee)| Example | Amount |
|---|---|
| You sell one item at | Rs 1,500 |
| and charge your customer delivery of | Rs 200 |
| The courier collects (codAmount) | Rs 1,700 |
| Wholesale price | − Rs 1,000 |
| Our shipping (shippingCost) | − Rs 200 |
| Your margin | Rs 450 |
- On delivery the margin becomes pending. It moves to Available 20 days later — our courier pays us the cash about 15 days after delivery, and margins are paid once it is in — and you get
wallet.margin_released. The order'smarginReleaseAthas the exact date. - COD must cover cost: if
codAmountis less than wholesale plus shipping you get422 cod_below_cost. - While a COD order is open we hold its possible return cost (
rtoReserve= forward + return shipping) on your wallet. It is released when the order is delivered or cancelled. Without enough Available balance you get422 insufficient_balance.
Prepaid orders#
Your customer already paid you (card, bank transfer…). Wholesale plus shipping (prepaidAmount) is taken from your wallet when you place the order and nothing is collected at the door. If the wallet is short, the order waits as AWAITING_FUNDS; top up and call POST /orders/{id}/pay. Cancelling a prepaid order refunds prepaidAmount to your wallet.
Refusals and returns#
Every refusal and return is settled with one rule:
what we received − forward shipping − return shipping → positive: credited to you, negative: charged to youRefused at the door (RTO)
Nothing was collected, so a COD parcel costs you forward plus return shipping — Rs 200 + Rs 150 = Rs 350 with standard shipping. This is the rtoCharge in the order.returned event (type: rto). It is taken from Available, then from your deposit. After 2 refusals a customer's phone number is blocked (customer_blocked).
Returned after delivery
Within the 7-day return window, a pending margin is reversed. What the customer paid, less both shipping legs, is credited back to you as returnCredit — refund your customer from it.
Keep refusals low
Confirm orders with your customers, use real phone numbers and full addresses. Your daily order limit grows with delivered orders and shrinks with a high return rate.Daily order limit#
| Tier | Orders per day | Reached after | Return rate must stay under |
|---|---|---|---|
| Tier 1 | 20 | Start | — |
| Tier 2 | 50 | 50 delivered orders | 30% |
| Tier 3 | 150 | 200 delivered orders | 25% |
| Tier 4 | 500 | 1000 delivered orders | 20% |
Over the limit, POST /orders returns 429 daily_cap_reached with your cap in details. The day starts at midnight Pakistan time.
Your wallet#
| Balance | Meaning |
|---|---|
available | Yours: withdraw it or spend it on prepaid orders. |
pending | Margins waiting for their release date (20 days after delivery). |
held | Your deposit (Rs 2,000) plus the rtoReserve of open COD orders. |
GET /wallet returns the balances and GET /wallet/transactions every entry, each linked to its order — a signed change to Available, so the entries add up to your balance.