Skip to main content

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#

RECEIVED→CONFIRMED→PROCESSING→SHIPPED→DELIVERED
statusMeaningWebhook
AWAITING_FUNDSPrepaid only: your wallet could not cover it. It waits 72 hours for a top-up and POST /orders/{id}/pay, then is cancelled.—
RECEIVEDWe have the order and have reserved the stock.order.received
CONFIRMEDReady to pack.order.confirmed
PROCESSINGBeing packed. From here it can no longer be cancelled.—
SHIPPEDWith the courier; tracking has the courier and number.order.shipped
DELIVEREDDelivered and, for COD, paid by the customer.order.delivered
CANCELLEDBy you, the customer or us — cancellationReason says why.order.cancelled
RETURNEDRefused 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.

What you earn
codAmount = Σ (resalePrice × quantity) + shippingCharged      ← the courier collects this
margin    = codAmount − wholesaleTotal − shippingCost   (less 10% platform fee)
ExampleAmount
You sell one item atRs 1,500
and charge your customer delivery ofRs 200
The courier collects (codAmount)Rs 1,700
Wholesale price− Rs 1,000
Our shipping (shippingCost)− Rs 200
Your marginRs 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's marginReleaseAt has the exact date.
  • COD must cover cost: if codAmount is less than wholesale plus shipping you get 422 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 get 422 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 you

Refused 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#

TierOrders per dayReached afterReturn rate must stay under
Tier 120Start—
Tier 25050 delivered orders30%
Tier 3150200 delivered orders25%
Tier 45001000 delivered orders20%

Over the limit, POST /orders returns 429 daily_cap_reached with your cap in details. The day starts at midnight Pakistan time.

Your wallet#

BalanceMeaning
availableYours: withdraw it or spend it on prepaid orders.
pendingMargins waiting for their release date (20 days after delivery).
heldYour 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.