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 refusal cost (
rtoReserve= its delivery charge,shippingCost) 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. Its platform fee is held until the return window closes. If the wallet is short, the order is refused with 422 insufficient_balance and error.details.topUp says how much to add. Cancelling a prepaid order refunds prepaidAmount to your wallet.
Refusals and returns#
Every refusal and return is settled with one rule:
what we received − the delivery charge (once) → positive: credited to you, negative: charged to youRefused at the door (RTO)
Nothing was collected, so a COD parcel costs you its delivery charge once — Rs 200 with standard shipping, nothing extra for the trip back. This is the rtoCharge in the order.returned event (type: rto). It is taken from the order's reserve. 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 the delivery charge, 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.
