{"openapi":"3.1.0","info":{"title":"MarkitMall Dropship API","version":"1.0.0","description":"Sell MarkitMall products on your own store. Browse the dropship catalog, import products, send us your customers' orders, and follow them to delivery — we pack and ship without MarkitMall branding.\n\n**Authentication** — `Authorization: Bearer <keyId>:<secret>`. Create keys in the dropshipping dashboard → Integrations. Test keys (`mk_test_…`) use the sandbox: everything is validated but nothing ships and no money moves; use `POST /orders/{id}/simulate` to walk a sandbox order through its life.\n\n**Conventions** — JSON; amounts are integer PKR; dates are ISO 8601 UTC. Lists use cursor pagination (`?limit=50&cursor=…` → `{ data, nextCursor }`). `POST /orders` requires an `Idempotency-Key` header: the same key returns the first result. Breaking changes only ever arrive in `/v2`.\n\n**Limits and API plans** — limits are per account (all your keys together) and set by your API plan (`x-markitmall-terms.apiPlans`): requests a minute (over it: `429 rate_limited` with `Retry-After`) and requests a day, UTC (over it: `429 daily_quota_exceeded` until midnight UTC). Every response carries `X-Quota-Limit`, `X-Quota-Remaining` and `X-Quota-Reset` (Unix seconds). Placing, cancelling and paying for orders, `POST /shipping/quote` and `GET /me` are never refused for the daily quota. The free plan covers a normal store — the WooCommerce plugin and the Shopify app use a few hundred requests a day. Bigger plans are bought from your wallet in the dashboard (Dropshipping → API plan).\n\n**Do not call the API on every page view.** Import products into your own store and keep them current from webhooks (`product.updated`, `product.stock_changed`); use `GET /inventory` to check stock before checkout. Catalog responses are cached for about a minute on our side, so calling more often only spends your quota.\n\n**Money** — COD orders: our courier collects `codAmount` (your selling price + the shipping you charged). **Platform fee**: MarkitMall takes `platformFee` — `x-markitmall-terms.marginFeePercent` (10% by default) of your margin (what your customer paid − `wholesaleTotal` − `shippingCost`), never of a loss. It is charged only on a parcel that was delivered and kept: never on a cancelled, refused or returned one. After delivery your margin (`codAmount − wholesaleTotal − shippingCost − platformFee.amount`) is credited 20 days after delivery, once the courier has paid us the cash (`marginReleaseAt` says when; `x-markitmall-terms.payoutHoldDays` has the current number). A refused parcel is charged forward + return shipping. Each open COD order holds that possible charge (`rtoReserve`) on your wallet. Prepaid orders: your customer paid you, so wholesale + shipping is taken from your wallet when the order is placed (or the order waits as `AWAITING_FUNDS`), and the platform fee (the same share of your margin) 20 days after delivery (`expectedMargin` is then minus the fee).\n\n**Errors** — `{ \"error\": { \"code\", \"message\", \"details\" } }`. Branch on `code`:\n\n| HTTP | code | meaning |\n| --- | --- | --- |\n| 400 | validation_error | A field is missing or invalid; `details` names it |\n| 400 | idempotency_key_required | POST /orders without Idempotency-Key |\n| 401 | invalid_key | Key unknown, revoked, or wrong secret |\n| 403 | reseller_suspended / reseller_not_active | Account not active |\n| 403 | ip_not_allowed | Key has an IP allowlist and this IP is not on it |\n| 404 | variant_not_found / variant_not_mapped / not_found | Unknown id, not dropship-enabled, or not imported |\n| 409 | duplicate_order | `externalOrderId` already used |\n| 409 | idempotency_key_reused / idempotency_in_progress | Key reused with another body / first request still running |\n| 409 | order_not_cancellable / order_not_payable | Already packed / not awaiting funds |\n| 422 | price_below_minimum | `resalePrice` under `minResalePrice` |\n| 422 | cod_below_cost | COD amount does not cover wholesale + shipping |\n| 422 | out_of_stock | Not enough stock |\n| 422 | insufficient_balance / deposit_required | Wallet cannot cover the RTO reserve, prepaid cost or deposit |\n| 422 | customer_blocked | Phone blocked after repeated refusals |\n| 429 | rate_limited | Over your plan's requests a minute — wait `Retry-After` seconds |\n| 429 | daily_quota_exceeded | Your plan's requests for the day are used up (orders still go through) — resumes at midnight UTC, or buy a bigger plan |\n| 429 | daily_cap_reached | Your tier's daily order cap |"},"servers":[{"url":"https://backend.markitmall.com/dropship/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"Account"},{"name":"Catalog"},{"name":"Imports"},{"name":"Orders"},{"name":"Shipping"},{"name":"Wallet"},{"name":"Webhooks"}],"paths":{"/me":{"get":{"tags":["Account"],"summary":"Who this key belongs to (test connection)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"$ref":"#/components/responses/E401"}}}},"/catalog/products":{"get":{"tags":["Catalog"],"summary":"Browse dropship products","parameters":[{"name":"search","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"},"description":"Category id (main or sub)"},{"name":"minPrice","in":"query","schema":{"type":"integer"},"description":"Wholesale price, PKR"},{"name":"maxPrice","in":"query","schema":{"type":"integer"}},{"name":"inStock","in":"query","schema":{"type":"boolean"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`nextCursor` from the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/E401"},"429":{"$ref":"#/components/responses/E429"}}}},"/catalog/products/{id}":{"get":{"tags":["Catalog"],"summary":"One product with variants, prices and stock","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"}}}},"/catalog/categories":{"get":{"tags":["Catalog"],"summary":"Category tree (only categories with dropship products)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}}}},"401":{"$ref":"#/components/responses/E401"}}}},"/imports":{"post":{"tags":["Imports"],"summary":"Mark products as imported and map your variant ids to ours","description":"Send one product, or `{ products: [...] }` (up to 50). Re-importing updates the mapping. Map variants so orders can use your own `externalVariantId`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ImportRequest"},{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/ImportRequest"},"maxItems":50}}}]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Import"}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"}}},"get":{"tags":["Imports"],"summary":"Your imported products and their sync status","parameters":[{"name":"status","in":"query","schema":{"enum":["ok","failed","removed"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`nextCursor` from the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Import"}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/E401"}}}},"/imports/{id}":{"delete":{"tags":["Imports"],"summary":"Stop syncing a product","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"}}}},"/imports/{id}/sync-result":{"post":{"tags":["Imports"],"summary":"Report whether applying our last change to your store worked","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"enum":["ok","failed"]},"error":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"}}}},"/inventory":{"get":{"tags":["Catalog"],"summary":"Stock and price for up to 100 variants","parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated variant ids"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InventoryItem"}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"}}}},"/shipping/quote":{"post":{"tags":["Shipping"],"summary":"Shipping cost for a city and items, before you place the order","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingQuoteRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingQuote"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"}}}},"/orders":{"post":{"tags":["Orders"],"summary":"Create an order","description":"Items from different MarkitMall stores ship as separate parcels; the response lists them under `parcels` and the top-level amounts are the totals.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Your order id works well"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}}},"responses":{"201":{"description":"Created (or replayed — see the Idempotent-Replayed header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderResponse"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}},"get":{"tags":["Orders"],"summary":"List orders","parameters":[{"name":"status","in":"query","schema":{"type":"string"},"description":"One or more stages, comma-separated"},{"name":"externalOrderId","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`nextCursor` from the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/E401"}}}},"/orders/{id}":{"get":{"tags":["Orders"],"summary":"Order (parcel) detail with status history and tracking","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"}}}},"/orders/{id}/tracking":{"get":{"tags":["Orders"],"summary":"Customer-safe tracking: stage, courier, tracking number and a dated timeline","description":"Built for your own \"Track my order\" page. White-label: no supplier store, no wholesale prices and no MarkitMall link — show it to your customer as is.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tracking"}}}},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"}}}},"/orders/{id}/cancel":{"post":{"tags":["Orders"],"summary":"Cancel before it is packed","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":300}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"}}}},"/orders/{id}/pay":{"post":{"tags":["Orders"],"summary":"Pay an AWAITING_FUNDS order from your wallet","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"}}}},"/orders/{id}/simulate":{"post":{"tags":["Orders"],"summary":"Sandbox only: move a test order to a stage and receive its webhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"enum":["CONFIRMED","PROCESSING","SHIPPED","DELIVERED","CANCELLED","RETURNED"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"}}}},"/wallet":{"get":{"tags":["Wallet"],"summary":"Available, pending and held balances","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Wallet"}}}},"401":{"$ref":"#/components/responses/E401"}}}},"/wallet/transactions":{"get":{"tags":["Wallet"],"summary":"Ledger entries, newest first, each linked to its order","parameters":[{"name":"type","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`nextCursor` from the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LedgerEntry"}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/E401"}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"Your webhook URL and events","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookConfig"}}}},"401":{"$ref":"#/components/responses/E401"}}},"put":{"tags":["Webhooks"],"summary":"Set your webhook URL and events","description":"A signing secret is generated the first time a URL is set (or with `rotateSecret: true`) and returned once as `secret`. You may supply your own (32+ characters) instead.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":["string","null"],"format":"uri"},"events":{"type":"array","items":{"type":"string"},"description":"Empty = all events"},"secret":{"type":"string","minLength":32},"rotateSecret":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookConfig"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"422":{"$ref":"#/components/responses/E422"}}}},"/webhooks/test":{"post":{"tags":["Webhooks"],"summary":"Send a sample order.shipped event","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"},"422":{"$ref":"#/components/responses/E422"}}}},"/integration/disconnect":{"post":{"tags":["Account"],"summary":"Disconnect this store (app or plugin uninstalled)","description":"Revokes every key of this integration — including the one making the call — and stops its webhooks. Orders already placed are still delivered and settled.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/E401"}}}},"/webhooks/deliveries":{"get":{"tags":["Webhooks"],"summary":"Delivery log","parameters":[{"name":"status","in":"query","schema":{"enum":["pending","delivered","failed"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`nextCursor` from the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object"}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/E401"}}}}},"webhooks":{"order.received":{"post":{"summary":"order.received","description":"The order reached MarkitMall (and, for a prepaid order, was paid).\n\nVerify `X-MarkitMall-Signature: sha256=<hex>` — the HMAC-SHA256 of the raw body under your webhook secret — and de-duplicate on `X-MarkitMall-Event-Id`. Answer 2xx within 10 s; failures are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h.","parameters":[{"name":"X-MarkitMall-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Timestamp","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","mode","createdAt","data"],"properties":{"id":{"type":"string"},"event":{"const":"order.received"},"mode":{"enum":["live","test"]},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/OrderEvent"}}}}}},"responses":{"200":{"description":"Received"}}}},"order.confirmed":{"post":{"summary":"order.confirmed","description":"The customer confirmed by call/WhatsApp, or no confirmation was needed.\n\nVerify `X-MarkitMall-Signature: sha256=<hex>` — the HMAC-SHA256 of the raw body under your webhook secret — and de-duplicate on `X-MarkitMall-Event-Id`. Answer 2xx within 10 s; failures are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h.","parameters":[{"name":"X-MarkitMall-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Timestamp","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","mode","createdAt","data"],"properties":{"id":{"type":"string"},"event":{"const":"order.confirmed"},"mode":{"enum":["live","test"]},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/OrderEvent"}}}}}},"responses":{"200":{"description":"Received"}}}},"order.cancelled":{"post":{"summary":"order.cancelled","description":"Cancelled by you, the customer or us; `cancellationReason` says why.\n\nVerify `X-MarkitMall-Signature: sha256=<hex>` — the HMAC-SHA256 of the raw body under your webhook secret — and de-duplicate on `X-MarkitMall-Event-Id`. Answer 2xx within 10 s; failures are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h.","parameters":[{"name":"X-MarkitMall-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Timestamp","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","mode","createdAt","data"],"properties":{"id":{"type":"string"},"event":{"const":"order.cancelled"},"mode":{"enum":["live","test"]},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/OrderEvent"}}}}}},"responses":{"200":{"description":"Received"}}}},"order.shipped":{"post":{"summary":"order.shipped","description":"Handed to the courier; `tracking` holds the courier and number.\n\nVerify `X-MarkitMall-Signature: sha256=<hex>` — the HMAC-SHA256 of the raw body under your webhook secret — and de-duplicate on `X-MarkitMall-Event-Id`. Answer 2xx within 10 s; failures are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h.","parameters":[{"name":"X-MarkitMall-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Timestamp","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","mode","createdAt","data"],"properties":{"id":{"type":"string"},"event":{"const":"order.shipped"},"mode":{"enum":["live","test"]},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/OrderEvent"}}}}}},"responses":{"200":{"description":"Received"}}}},"order.delivered":{"post":{"summary":"order.delivered","description":"Delivered; includes `margin` and `marginReleaseAt`.\n\nVerify `X-MarkitMall-Signature: sha256=<hex>` — the HMAC-SHA256 of the raw body under your webhook secret — and de-duplicate on `X-MarkitMall-Event-Id`. Answer 2xx within 10 s; failures are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h.","parameters":[{"name":"X-MarkitMall-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Timestamp","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","mode","createdAt","data"],"properties":{"id":{"type":"string"},"event":{"const":"order.delivered"},"mode":{"enum":["live","test"]},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/OrderEvent"}}}}}},"responses":{"200":{"description":"Received"}}}},"order.returned":{"post":{"summary":"order.returned","description":"`type: rto` (refused at the door) or `type: return` (after delivery), with `charge` / `credit`.\n\nVerify `X-MarkitMall-Signature: sha256=<hex>` — the HMAC-SHA256 of the raw body under your webhook secret — and de-duplicate on `X-MarkitMall-Event-Id`. Answer 2xx within 10 s; failures are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h.","parameters":[{"name":"X-MarkitMall-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Timestamp","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","mode","createdAt","data"],"properties":{"id":{"type":"string"},"event":{"const":"order.returned"},"mode":{"enum":["live","test"]},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/OrderEvent"}}}}}},"responses":{"200":{"description":"Received"}}}},"product.updated":{"post":{"summary":"product.updated","description":"Price, title, images or variants changed — update your listing.\n\nVerify `X-MarkitMall-Signature: sha256=<hex>` — the HMAC-SHA256 of the raw body under your webhook secret — and de-duplicate on `X-MarkitMall-Event-Id`. Answer 2xx within 10 s; failures are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h.","parameters":[{"name":"X-MarkitMall-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Timestamp","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","mode","createdAt","data"],"properties":{"id":{"type":"string"},"event":{"const":"product.updated"},"mode":{"enum":["live","test"]},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/ProductEvent"}}}}}},"responses":{"200":{"description":"Received"}}}},"product.stock_changed":{"post":{"summary":"product.stock_changed","description":"Stock changed, including to zero — hide or show the listing.\n\nVerify `X-MarkitMall-Signature: sha256=<hex>` — the HMAC-SHA256 of the raw body under your webhook secret — and de-duplicate on `X-MarkitMall-Event-Id`. Answer 2xx within 10 s; failures are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h.","parameters":[{"name":"X-MarkitMall-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Timestamp","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","mode","createdAt","data"],"properties":{"id":{"type":"string"},"event":{"const":"product.stock_changed"},"mode":{"enum":["live","test"]},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/ProductEvent"}}}}}},"responses":{"200":{"description":"Received"}}}},"product.removed":{"post":{"summary":"product.removed","description":"No longer available for dropshipping — unpublish it.\n\nVerify `X-MarkitMall-Signature: sha256=<hex>` — the HMAC-SHA256 of the raw body under your webhook secret — and de-duplicate on `X-MarkitMall-Event-Id`. Answer 2xx within 10 s; failures are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h.","parameters":[{"name":"X-MarkitMall-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Timestamp","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","mode","createdAt","data"],"properties":{"id":{"type":"string"},"event":{"const":"product.removed"},"mode":{"enum":["live","test"]},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/ProductEvent"}}}}}},"responses":{"200":{"description":"Received"}}}},"wallet.margin_released":{"post":{"summary":"wallet.margin_released","description":"A margin moved to Available; `amount` is what was credited.\n\nVerify `X-MarkitMall-Signature: sha256=<hex>` — the HMAC-SHA256 of the raw body under your webhook secret — and de-duplicate on `X-MarkitMall-Event-Id`. Answer 2xx within 10 s; failures are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h.","parameters":[{"name":"X-MarkitMall-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-MarkitMall-Timestamp","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","event","mode","createdAt","data"],"properties":{"id":{"type":"string"},"event":{"const":"wallet.margin_released"},"mode":{"enum":["live","test"]},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/OrderEvent"}}}}}},"responses":{"200":{"description":"Received"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"<keyId>:<secret>"}},"responses":{"E400":{"description":"Error (HTTP 400)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E401":{"description":"Error (HTTP 401)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E403":{"description":"Error (HTTP 403)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E404":{"description":"Error (HTTP 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E409":{"description":"Error (HTTP 409)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E422":{"description":"Error (HTTP 422)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E429":{"description":"Error (HTTP 429)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}},"Me":{"type":"object","properties":{"reseller":{"type":"object","properties":{"id":{"type":"string"},"brandName":{"type":"string"},"status":{"type":"string"}}},"mode":{"enum":["live","test"]},"keyId":{"type":"string"},"integration":{"type":"object"}}},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"children":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}}}}}},"Variant":{"type":"object","properties":{"id":{"type":"string","description":"Use this as `variantId` in orders. For a product without options it equals the product id (`isDefault: true`)."},"isDefault":{"type":"boolean"},"sku":{"type":["string","null"]},"color":{"type":["string","null"]},"size":{"type":["string","null"]},"title":{"type":"string"},"image":{"type":["string","null"]},"wholesalePrice":{"type":"integer"},"suggestedPrice":{"type":"integer"},"minResalePrice":{"type":"integer"},"stock":{"type":"integer"}}},"Product":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","description":"HTML"},"images":{"type":"array","items":{"type":"string","format":"uri"},"description":"Copy them to your store — do not hotlink."},"brand":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"category":{"type":["object","null"]},"storeId":{"type":"string","description":"Products of different stores ship as separate parcels"},"weightKg":{"type":["number","null"]},"wholesalePrice":{"type":"integer","description":"Lowest across variants"},"suggestedPrice":{"type":"integer"},"compareAtPrice":{"type":["integer","null"]},"minResalePrice":{"type":"integer"},"inStock":{"type":"boolean"},"stock":{"type":"integer"},"shipping":{"type":"object","description":"What MarkitMall charges to deliver this product. `estimate` is one unit shipped on its own; a parcel is charged by its total weight (`x-markitmall-terms.shippingRates`), plus any city surcharge (`x-markitmall-terms.citySurcharges`), and items from different stores ship as separate parcels. `POST /shipping/quote` prices a whole cart.","properties":{"required":{"type":"boolean","description":"False when the store offers free delivery on it — we charge you none"},"weightKg":{"type":["number","null"],"description":"Null when unknown — the default shipping cost applies"},"estimate":{"type":"integer","description":"PKR, one unit, no city surcharge","example":150}}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"updatedAt":{"type":"string","format":"date-time"}}},"InventoryItem":{"type":"object","properties":{"variantId":{"type":"string"},"productId":{"type":["string","null"]},"available":{"type":"boolean","description":"false = unknown or no longer dropshippable — hide it"},"stock":{"type":"integer"},"wholesalePrice":{"type":["integer","null"]},"minResalePrice":{"type":["integer","null"]}}},"ImportRequest":{"type":"object","required":["productId"],"properties":{"productId":{"type":"string"},"externalProductId":{"type":"string"},"customTitle":{"type":"string"},"resalePrice":{"type":"integer"},"variants":{"type":"array","items":{"type":"object","required":["variantId","externalVariantId"],"properties":{"variantId":{"type":"string"},"externalVariantId":{"type":"string"},"externalSku":{"type":"string"}}}}}},"Import":{"type":"object","properties":{"id":{"type":"string"},"productId":{"type":"string"},"externalProductId":{"type":["string","null"]},"syncStatus":{"enum":["ok","failed","removed"]},"available":{"type":"boolean"},"variants":{"type":"array","items":{"type":"object"}}}},"ShippingQuoteRequest":{"type":"object","required":["city","items"],"properties":{"city":{"type":"string"},"items":{"type":"array","items":{"type":"object","required":["quantity"],"properties":{"variantId":{"type":"string"},"externalVariantId":{"type":"string"},"quantity":{"type":"integer","minimum":1}}}}}},"ShippingQuote":{"type":"object","properties":{"city":{"type":"string"},"shippingCost":{"type":"integer"},"returnShippingCost":{"type":"integer"},"rtoReserve":{"type":"integer","description":"Held on your wallet while a COD order is open"},"platformFeePercent":{"type":"number","description":"Platform fee, in percent of `platformFeeBasis`","example":10},"platformFeeBasis":{"type":"string","enum":["margin","sale"],"description":"margin (default): of your margin — what your customer pays − wholesale − shipping; sale: of your selling price for the items"},"parcels":{"type":"array","items":{"type":"object"}}}},"CreateOrderRequest":{"type":"object","required":["externalOrderId","paymentMode","customer","items"],"properties":{"externalOrderId":{"type":"string","maxLength":100,"description":"Your order id; unique per account"},"externalOrderName":{"type":"string","examples":["#1042"]},"paymentMode":{"enum":["COD","PREPAID"],"description":"How YOUR customer paid. COD: our courier collects. PREPAID: you pay us from your wallet."},"customer":{"type":"object","required":["name","phone","address","city"],"properties":{"name":{"type":"string"},"phone":{"type":"string","examples":["03001234567"]},"address":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"},"postalCode":{"type":"string"}}},"items":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["quantity","resalePrice"],"properties":{"variantId":{"type":"string","description":"Our variant id (or product id for products without options)"},"externalVariantId":{"type":"string","description":"Your variant id, mapped through POST /imports"},"externalLineId":{"type":"string"},"sku":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":100},"resalePrice":{"type":"integer","description":"Per unit, what your customer pays"}}}},"shippingCharged":{"type":"integer","default":0,"description":"Delivery charge you showed your customer"},"senderName":{"type":"string","description":"Printed as the parcel's sender; defaults to your brand"},"notes":{"type":"string","maxLength":500}},"examples":[{"externalOrderId":"1042","paymentMode":"COD","customer":{"name":"Ali Raza","phone":"03001234567","address":"House 12, Street 4, DHA Phase 5","city":"Lahore","province":"Punjab"},"items":[{"variantId":"66f0c2a1b2c3d4e5f6a7b8c9","quantity":1,"resalePrice":1500}],"shippingCharged":200,"senderName":"Ali Gadgets","notes":"Call before delivery"}]},"CreateOrderResponse":{"type":"object","properties":{"id":{"type":"string"},"externalOrderId":{"type":"string"},"orderNumber":{"type":["string","null"]},"status":{"type":"string"},"paymentMode":{"enum":["COD","PREPAID"]},"mode":{"enum":["live","test"]},"codAmount":{"type":"integer"},"prepaidAmount":{"type":"integer"},"wholesaleTotal":{"type":"integer"},"shippingCost":{"type":"integer"},"platformFee":{"type":"object","description":"Platform fee on this parcel: `percent` of your margin (`basis: margin`, the default) or, on orders placed under a sale fee, of resaleTotal (`basis: sale`); `amount` is what is taken. Taken when the margin is released; not charged if the parcel is cancelled, refused or returned.","properties":{"basis":{"type":"string","enum":["margin","sale"]},"percent":{"type":"number","example":10},"amount":{"type":"integer"}}},"expectedMargin":{"type":"integer","description":"COD: credited after delivery, the fee already taken off. Prepaid: minus the platform fee (debited then)."},"rtoReserve":{"type":"integer"},"fundsDeadline":{"type":["string","null"],"format":"date-time"},"parcels":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}},"OrderStatus":{"enum":["AWAITING_FUNDS","RECEIVED","CONFIRMED","PROCESSING","SHIPPED","DELIVERED","CANCELLED","RETURNED"]},"OrderEvent":{"type":"object","properties":{"id":{"type":"string"},"externalOrderId":{"type":"string"},"externalOrderName":{"type":["string","null"]},"parcel":{"type":"object","properties":{"part":{"type":"integer"},"of":{"type":"integer"}}},"orderNumber":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/OrderStatus"},"paymentMode":{"enum":["COD","PREPAID"]},"codAmount":{"type":"integer"},"wholesaleTotal":{"type":"integer"},"shippingCost":{"type":"integer"},"margin":{"type":"integer"},"marginStatus":{"enum":["NONE","PENDING","RELEASED","REVERSED"]},"marginReleaseAt":{"type":["string","null"],"format":"date-time"},"rtoCharge":{"type":"integer"},"returnCredit":{"type":"integer"},"items":{"type":"array","items":{"type":"object"}},"tracking":{"type":["object","null"],"properties":{"number":{"type":"string"},"courier":{"type":"string"},"url":{"type":["string","null"]}}},"cancellationReason":{"type":["string","null"]}}},"Order":{"allOf":[{"$ref":"#/components/schemas/OrderEvent"},{"type":"object","properties":{"mode":{"enum":["live","test"]},"confirmation":{"enum":["PENDING","CONFIRMED","FAILED","NOT_REQUIRED"]},"prepaidAmount":{"type":"integer"},"resaleTotal":{"type":"integer"},"shippingCharged":{"type":"integer"},"platformFee":{"type":"object","description":"Platform fee on this parcel: `percent` of your margin (`basis: margin`, the default) or, on orders placed under a sale fee, of resaleTotal (`basis: sale`); `amount` is what is taken. Taken when the margin is released; not charged if the parcel is cancelled, refused or returned.","properties":{"basis":{"type":"string","enum":["margin","sale"]},"percent":{"type":"number","example":10},"amount":{"type":"integer"}}},"expectedMargin":{"type":"integer","description":"COD: credited after delivery, the fee already taken off. Prepaid: minus the platform fee."},"rtoReserve":{"type":"integer"},"customer":{"type":"object"},"fundsDeadline":{"type":["string","null"],"format":"date-time"},"history":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"at":{"type":"string","format":"date-time"},"note":{"type":["string","null"]}}}},"createdAt":{"type":"string","format":"date-time"}}}]},"ProductEvent":{"type":"object","properties":{"productId":{"type":"string"},"importId":{"type":"string"},"externalProductId":{"type":["string","null"]},"product":{"oneOf":[{"$ref":"#/components/schemas/Product"},{"type":"null"}]},"changes":{"type":"array","items":{"type":"string"}}}},"Tracking":{"type":"object","properties":{"id":{"type":"string"},"externalOrderId":{"type":"string"},"orderNumber":{"type":"string"},"parcel":{"type":"object","properties":{"part":{"type":"integer"},"of":{"type":"integer"}}},"status":{"enum":["AWAITING_FUNDS","RECEIVED","CONFIRMED","PROCESSING","SHIPPED","DELIVERED","CANCELLED","RETURNED"]},"statusLabel":{"type":"string","example":"On the way"},"paymentMode":{"enum":["COD","PREPAID"]},"amountToCollect":{"type":"integer","description":"Cash the courier collects; 0 for prepaid"},"sender":{"type":"string","description":"The name printed on the parcel"},"tracking":{"type":["object","null"],"properties":{"number":{"type":"string"},"courier":{"type":"string"}}},"shippedAt":{"type":["string","null"],"format":"date-time"},"deliveredAt":{"type":["string","null"],"format":"date-time"},"cancelledReason":{"type":["string","null"]},"steps":{"type":"array","description":"Received → Confirmed → Being packed → On the way → Delivered, plus Cancelled/Returned when it ended there","items":{"type":"object","properties":{"status":{"type":"string"},"label":{"type":"string"},"done":{"type":"boolean"},"at":{"type":["string","null"],"format":"date-time"}}}},"history":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"label":{"type":"string"},"at":{"type":"string","format":"date-time"}}}},"updatedAt":{"type":"string","format":"date-time"}}},"Wallet":{"type":"object","properties":{"available":{"type":"integer"},"pending":{"type":"integer","description":"Margins waiting for their release date (20 days after delivery)"},"pendingOrders":{"type":"integer"},"held":{"type":"integer","description":"Deposit + RTO reserves"},"heldDeposit":{"type":"integer"},"heldReserve":{"type":"integer"},"depositRequired":{"type":"integer"},"withdrawalsPending":{"type":"integer"},"currency":{"const":"PKR"}}},"LedgerEntry":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"integer","description":"Signed change to Available"},"type":{"type":"string"},"status":{"type":"string"},"description":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"order":{"type":["object","null"]}}},"WebhookConfig":{"type":"object","properties":{"integrationId":{"type":"string"},"url":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"}},"hasSecret":{"type":"boolean"},"secret":{"type":"string","description":"Only when just generated"}}}}},"x-markitmall-terms":{"returnWindowDays":7,"payoutHoldDays":20,"returnShippingCost":150,"defaultShippingCost":200,"shippingRates":{"bands":[{"upToKg":0.5,"cost":150},{"upToKg":1,"cost":200},{"upToKg":2,"cost":250},{"upToKg":5,"cost":350},{"upToKg":10,"cost":500}],"perKgAbove":30},"citySurcharges":{},"apiPlans":[{"id":"free","name":"Free","dailyRequests":5000,"perMinute":120,"price":0},{"id":"starter","name":"Starter","dailyRequests":25000,"perMinute":300,"price":1500},{"id":"growth","name":"Growth","dailyRequests":100000,"perMinute":600,"price":4500},{"id":"scale","name":"Scale","dailyRequests":300000,"perMinute":1200,"price":12000}],"depositAmount":2000,"marginFeePercent":10,"saleFeePercent":0,"allowPrepaid":true,"awaitingFundsHours":72,"confirmationRequired":false,"confirmationMaxAttempts":2,"blacklistRefusals":2,"tiers":[{"tier":1,"dailyCap":20,"minDelivered":0,"maxRtoRate":1},{"tier":2,"dailyCap":50,"minDelivered":50,"maxRtoRate":0.3},{"tier":3,"dailyCap":150,"minDelivered":200,"maxRtoRate":0.25},{"tier":4,"dailyCap":500,"minDelivered":1000,"maxRtoRate":0.2}]}}