MarkitMallDevelopers API keys

API reference

Orders

Send your customers' orders and follow them to delivery.

get/ordersList orderspost/ordersCreate an orderget/orders/{id}Order (parcel) detail with status history and trackingget/orders/{id}/trackingCustomer-safe tracking: stage, courier, tracking number and a dated timelinepost/orders/{id}/cancelCancel before it is packedpost/orders/{id}/payPay an AWAITING_FUNDS order from your walletpost/orders/{id}/simulateSandbox only: move a test order to a stage and receive its webhook

List orders

get/orders

Parameters

status
query · string

One or more stages, comma-separated

externalOrderId
query · string
from
query · string
to
query · string
limit
query · integer

Default 50

cursor
query · string

nextCursor from the previous page

Example request

curl "https://backend.markitmall.com/dropship/v1/orders" \
  -H "Authorization: Bearer mk_test_XXXX:sk_test_XXXX"

Response 200

datarequired
Order[]
—
nextCursorrequired
string | null
—
Example response
JSON
{
  "data": [
    {
      "id": "66f0c2a1b2c3d4e5f6a7b8c9",
      "externalOrderId": "66f0c2a1b2c3d4e5f6a7b8c9",
      "externalOrderName": "string",
      "parcel": {
        "part": 0,
        "of": 0
      },
      "orderNumber": "string",
      "status": "AWAITING_FUNDS",
      "paymentMode": "COD",
      "codAmount": 1500,
      "wholesaleTotal": 0,
      "shippingCost": 1500,
      "margin": 0,
      "marginStatus": "NONE",
      "marginReleaseAt": "2026-10-06T10:00:00.000Z",
      "rtoCharge": 0,
      "returnCredit": 0,
      "items": [
        {}
      ],
      "tracking": {
        "number": "string",
        "courier": "string",
        "url": "https://example.com/markitmall/webhook"
      },
      "cancellationReason": "string",
      "mode": "live",
      "confirmation": "PENDING",
      "prepaidAmount": 1500,
      "resaleTotal": 0,
      "shippingCharged": 0,
      "platformFee": {
        "basis": "margin",
        "percent": 0,
        "amount": 1500
      },
      "expectedMargin": 0,
      "rtoReserve": 0,
      "customer": {},
      "fundsDeadline": "2026-10-06T10:00:00.000Z",
      "history": [
        {
          "status": "string",
          "at": "2026-10-06T10:00:00.000Z",
          "note": "string"
        }
      ],
      "createdAt": "2026-10-06T10:00:00.000Z"
    }
  ],
  "nextCursor": "string"
}

Errors: 401 — the body is always { error: { code, message, details } }.

Create an order

post/orders

Items from different MarkitMall stores ship as separate parcels; the response lists them under parcels and the top-level amounts are the totals.

Parameters

Idempotency-Keyrequired
header · string

Your order id works well

Request body

CreateOrderRequest

externalOrderIdrequired
string · max 100 chars

Your order id; unique per account

externalOrderName
string
—
paymentModerequired
enum

How YOUR customer paid. COD: our courier collects. PREPAID: you pay us from your wallet.

CODPREPAID

customerrequired
object
—
customer.namerequired
string
—
customer.phonerequired
string
—
customer.addressrequired
string
—
customer.cityrequired
string
—
customer.province
string
—
customer.postalCode
string
—
itemsrequired
object[] · min 1 items · max 50 items
—
items[].variantId
string

Our variant id (or product id for products without options)

items[].externalVariantId
string

Your variant id, mapped through POST /imports

items[].externalLineId
string
—
items[].sku
string
—
items[].quantityrequired
integer · ≥ 1 · ≤ 100
—
items[].resalePricerequired
integer

Per unit, what your customer pays

shippingCharged
integer · default 0

Delivery charge you showed your customer

senderName
string

Printed as the parcel's sender; defaults to your brand

notes
string · max 500 chars
—

Example request

curl -X POST "https://backend.markitmall.com/dropship/v1/orders" \
  -H "Authorization: Bearer mk_test_XXXX:sk_test_XXXX" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
  "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"
}'

Response 201 — Created (or replayed — see the Idempotent-Replayed header)

CreateOrderResponse

id
string
—
externalOrderId
string
—
orderNumber
string | null
—
status
string
—
paymentMode
enum
—

CODPREPAID

mode
enum
—

livetest

codAmount
integer
—
prepaidAmount
integer
—
wholesaleTotal
integer
—
shippingCost
integer
—
platformFee
object

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.

platformFee.basis
enum
—

marginsale

platformFee.percent
number
—
platformFee.amount
integer
—
expectedMargin
integer

COD: credited after delivery, the fee already taken off. Prepaid: minus the platform fee (debited then).

rtoReserve
integer
—
fundsDeadline
string | null · date-time
—
parcels
Order[]
—
Example response
JSON
{
  "id": "66f0c2a1b2c3d4e5f6a7b8c9",
  "externalOrderId": "66f0c2a1b2c3d4e5f6a7b8c9",
  "orderNumber": "string",
  "status": "string",
  "paymentMode": "COD",
  "mode": "live",
  "codAmount": 1500,
  "prepaidAmount": 1500,
  "wholesaleTotal": 0,
  "shippingCost": 1500,
  "platformFee": {
    "basis": "margin",
    "percent": 0,
    "amount": 1500
  },
  "expectedMargin": 0,
  "rtoReserve": 0,
  "fundsDeadline": "2026-10-06T10:00:00.000Z",
  "parcels": [
    {
      "id": "66f0c2a1b2c3d4e5f6a7b8c9",
      "externalOrderId": "66f0c2a1b2c3d4e5f6a7b8c9",
      "externalOrderName": "string",
      "parcel": {
        "part": 0,
        "of": 0
      },
      "orderNumber": "string",
      "status": "AWAITING_FUNDS",
      "paymentMode": "COD",
      "codAmount": 1500,
      "wholesaleTotal": 0,
      "shippingCost": 1500,
      "margin": 0,
      "marginStatus": "NONE",
      "marginReleaseAt": "2026-10-06T10:00:00.000Z",
      "rtoCharge": 0,
      "returnCredit": 0,
      "items": [
        {}
      ],
      "tracking": {
        "number": "string",
        "courier": "string",
        "url": "https://example.com/markitmall/webhook"
      },
      "cancellationReason": "string",
      "mode": "live",
      "confirmation": "PENDING",
      "prepaidAmount": 1500,
      "resaleTotal": 0,
      "shippingCharged": 0,
      "platformFee": {
        "basis": "margin",
        "percent": 0,
        "amount": 1500
      },
      "expectedMargin": 0,
      "rtoReserve": 0,
      "customer": {},
      "fundsDeadline": "2026-10-06T10:00:00.000Z",
      "history": [
        {
          "status": "string",
          "at": "2026-10-06T10:00:00.000Z",
          "note": "string"
        }
      ],
      "createdAt": "2026-10-06T10:00:00.000Z"
    }
  ]
}

Errors: 400, 401, 403, 404, 409, 422, 429 — the body is always { error: { code, message, details } }.

Order (parcel) detail with status history and tracking

get/orders/{id}

Parameters

idrequired
path · string

Example request

curl "https://backend.markitmall.com/dropship/v1/orders/{id}" \
  -H "Authorization: Bearer mk_test_XXXX:sk_test_XXXX"

Response 200

Order

id
string
—
externalOrderId
string
—
externalOrderName
string | null
—
parcel
object
—
parcel.part
integer
—
parcel.of
integer
—
orderNumber
string | null
—
status
OrderStatus
—
paymentMode
enum
—

CODPREPAID

codAmount
integer
—
wholesaleTotal
integer
—
shippingCost
integer
—
margin
integer
—
marginStatus
enum
—

NONEPENDINGRELEASEDREVERSED

marginReleaseAt
string | null · date-time
—
rtoCharge
integer
—
returnCredit
integer
—
items
object[]
—
tracking
object | null
—
tracking.number
string
—
tracking.courier
string
—
tracking.url
string | null
—
cancellationReason
string | null
—
mode
enum
—

livetest

confirmation
enum
—

PENDINGCONFIRMEDFAILEDNOT_REQUIRED

prepaidAmount
integer
—
resaleTotal
integer
—
shippingCharged
integer
—
platformFee
object

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.

platformFee.basis
enum
—

marginsale

platformFee.percent
number
—
platformFee.amount
integer
—
expectedMargin
integer

COD: credited after delivery, the fee already taken off. Prepaid: minus the platform fee.

rtoReserve
integer
—
customer
object
—
fundsDeadline
string | null · date-time
—
history
object[]
—
history[].status
string
—
history[].at
string · date-time
—
history[].note
string | null
—
createdAt
string · date-time
—
Example response
JSON
{
  "id": "66f0c2a1b2c3d4e5f6a7b8c9",
  "externalOrderId": "66f0c2a1b2c3d4e5f6a7b8c9",
  "externalOrderName": "string",
  "parcel": {
    "part": 0,
    "of": 0
  },
  "orderNumber": "string",
  "status": "AWAITING_FUNDS",
  "paymentMode": "COD",
  "codAmount": 1500,
  "wholesaleTotal": 0,
  "shippingCost": 1500,
  "margin": 0,
  "marginStatus": "NONE",
  "marginReleaseAt": "2026-10-06T10:00:00.000Z",
  "rtoCharge": 0,
  "returnCredit": 0,
  "items": [
    {}
  ],
  "tracking": {
    "number": "string",
    "courier": "string",
    "url": "https://example.com/markitmall/webhook"
  },
  "cancellationReason": "string",
  "mode": "live",
  "confirmation": "PENDING",
  "prepaidAmount": 1500,
  "resaleTotal": 0,
  "shippingCharged": 0,
  "platformFee": {
    "basis": "margin",
    "percent": 0,
    "amount": 1500
  },
  "expectedMargin": 0,
  "rtoReserve": 0,
  "customer": {},
  "fundsDeadline": "2026-10-06T10:00:00.000Z",
  "history": [
    {
      "status": "string",
      "at": "2026-10-06T10:00:00.000Z",
      "note": "string"
    }
  ],
  "createdAt": "2026-10-06T10:00:00.000Z"
}

Errors: 401, 404 — the body is always { error: { code, message, details } }.

Customer-safe tracking: stage, courier, tracking number and a dated timeline

get/orders/{id}/tracking

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

idrequired
path · string

Example request

curl "https://backend.markitmall.com/dropship/v1/orders/{id}/tracking" \
  -H "Authorization: Bearer mk_test_XXXX:sk_test_XXXX"

Response 200

Tracking

id
string
—
externalOrderId
string
—
orderNumber
string
—
parcel
object
—
parcel.part
integer
—
parcel.of
integer
—
status
enum
—

AWAITING_FUNDSRECEIVEDCONFIRMEDPROCESSINGSHIPPEDDELIVEREDCANCELLEDRETURNED

statusLabel
string
—
paymentMode
enum
—

CODPREPAID

amountToCollect
integer

Cash the courier collects; 0 for prepaid

sender
string

The name printed on the parcel

tracking
object | null
—
tracking.number
string
—
tracking.courier
string
—
shippedAt
string | null · date-time
—
deliveredAt
string | null · date-time
—
cancelledReason
string | null
—
steps
object[]

Received → Confirmed → Being packed → On the way → Delivered, plus Cancelled/Returned when it ended there

steps[].status
string
—
steps[].label
string
—
steps[].done
boolean
—
steps[].at
string | null · date-time
—
history
object[]
—
history[].status
string
—
history[].label
string
—
history[].at
string · date-time
—
updatedAt
string · date-time
—
Example response
JSON
{
  "id": "66f0c2a1b2c3d4e5f6a7b8c9",
  "externalOrderId": "66f0c2a1b2c3d4e5f6a7b8c9",
  "orderNumber": "string",
  "parcel": {
    "part": 0,
    "of": 0
  },
  "status": "AWAITING_FUNDS",
  "statusLabel": "string",
  "paymentMode": "COD",
  "amountToCollect": 1500,
  "sender": "string",
  "tracking": {
    "number": "string",
    "courier": "string"
  },
  "shippedAt": "2026-10-06T10:00:00.000Z",
  "deliveredAt": "2026-10-06T10:00:00.000Z",
  "cancelledReason": "string",
  "steps": [
    {
      "status": "string",
      "label": "string",
      "done": true,
      "at": "2026-10-06T10:00:00.000Z"
    }
  ],
  "history": [
    {
      "status": "string",
      "label": "string",
      "at": "2026-10-06T10:00:00.000Z"
    }
  ],
  "updatedAt": "2026-10-06T10:00:00.000Z"
}

Errors: 401, 404 — the body is always { error: { code, message, details } }.

Cancel before it is packed

post/orders/{id}/cancel

Parameters

idrequired
path · string

Request body (optional)

reason
string · max 300 chars
—

Example request

curl -X POST "https://backend.markitmall.com/dropship/v1/orders/{id}/cancel" \
  -H "Authorization: Bearer mk_test_XXXX:sk_test_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Customer changed their mind"
}'

Response 200

Order

id
string
—
externalOrderId
string
—
externalOrderName
string | null
—
parcel
object
—
parcel.part
integer
—
parcel.of
integer
—
orderNumber
string | null
—
status
OrderStatus
—
paymentMode
enum
—

CODPREPAID

codAmount
integer
—
wholesaleTotal
integer
—
shippingCost
integer
—
margin
integer
—
marginStatus
enum
—

NONEPENDINGRELEASEDREVERSED

marginReleaseAt
string | null · date-time
—
rtoCharge
integer
—
returnCredit
integer
—
items
object[]
—
tracking
object | null
—
tracking.number
string
—
tracking.courier
string
—
tracking.url
string | null
—
cancellationReason
string | null
—
mode
enum
—

livetest

confirmation
enum
—

PENDINGCONFIRMEDFAILEDNOT_REQUIRED

prepaidAmount
integer
—
resaleTotal
integer
—
shippingCharged
integer
—
platformFee
object

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.

platformFee.basis
enum
—

marginsale

platformFee.percent
number
—
platformFee.amount
integer
—
expectedMargin
integer

COD: credited after delivery, the fee already taken off. Prepaid: minus the platform fee.

rtoReserve
integer
—
customer
object
—
fundsDeadline
string | null · date-time
—
history
object[]
—
history[].status
string
—
history[].at
string · date-time
—
history[].note
string | null
—
createdAt
string · date-time
—
Example response
JSON
{
  "id": "66f0c2a1b2c3d4e5f6a7b8c9",
  "externalOrderId": "66f0c2a1b2c3d4e5f6a7b8c9",
  "externalOrderName": "string",
  "parcel": {
    "part": 0,
    "of": 0
  },
  "orderNumber": "string",
  "status": "AWAITING_FUNDS",
  "paymentMode": "COD",
  "codAmount": 1500,
  "wholesaleTotal": 0,
  "shippingCost": 1500,
  "margin": 0,
  "marginStatus": "NONE",
  "marginReleaseAt": "2026-10-06T10:00:00.000Z",
  "rtoCharge": 0,
  "returnCredit": 0,
  "items": [
    {}
  ],
  "tracking": {
    "number": "string",
    "courier": "string",
    "url": "https://example.com/markitmall/webhook"
  },
  "cancellationReason": "string",
  "mode": "live",
  "confirmation": "PENDING",
  "prepaidAmount": 1500,
  "resaleTotal": 0,
  "shippingCharged": 0,
  "platformFee": {
    "basis": "margin",
    "percent": 0,
    "amount": 1500
  },
  "expectedMargin": 0,
  "rtoReserve": 0,
  "customer": {},
  "fundsDeadline": "2026-10-06T10:00:00.000Z",
  "history": [
    {
      "status": "string",
      "at": "2026-10-06T10:00:00.000Z",
      "note": "string"
    }
  ],
  "createdAt": "2026-10-06T10:00:00.000Z"
}

Errors: 401, 404, 409 — the body is always { error: { code, message, details } }.

Pay an AWAITING_FUNDS order from your wallet

post/orders/{id}/pay

Parameters

idrequired
path · string

Example request

curl -X POST "https://backend.markitmall.com/dropship/v1/orders/{id}/pay" \
  -H "Authorization: Bearer mk_test_XXXX:sk_test_XXXX"

Response 200

Order

id
string
—
externalOrderId
string
—
externalOrderName
string | null
—
parcel
object
—
parcel.part
integer
—
parcel.of
integer
—
orderNumber
string | null
—
status
OrderStatus
—
paymentMode
enum
—

CODPREPAID

codAmount
integer
—
wholesaleTotal
integer
—
shippingCost
integer
—
margin
integer
—
marginStatus
enum
—

NONEPENDINGRELEASEDREVERSED

marginReleaseAt
string | null · date-time
—
rtoCharge
integer
—
returnCredit
integer
—
items
object[]
—
tracking
object | null
—
tracking.number
string
—
tracking.courier
string
—
tracking.url
string | null
—
cancellationReason
string | null
—
mode
enum
—

livetest

confirmation
enum
—

PENDINGCONFIRMEDFAILEDNOT_REQUIRED

prepaidAmount
integer
—
resaleTotal
integer
—
shippingCharged
integer
—
platformFee
object

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.

platformFee.basis
enum
—

marginsale

platformFee.percent
number
—
platformFee.amount
integer
—
expectedMargin
integer

COD: credited after delivery, the fee already taken off. Prepaid: minus the platform fee.

rtoReserve
integer
—
customer
object
—
fundsDeadline
string | null · date-time
—
history
object[]
—
history[].status
string
—
history[].at
string · date-time
—
history[].note
string | null
—
createdAt
string · date-time
—
Example response
JSON
{
  "id": "66f0c2a1b2c3d4e5f6a7b8c9",
  "externalOrderId": "66f0c2a1b2c3d4e5f6a7b8c9",
  "externalOrderName": "string",
  "parcel": {
    "part": 0,
    "of": 0
  },
  "orderNumber": "string",
  "status": "AWAITING_FUNDS",
  "paymentMode": "COD",
  "codAmount": 1500,
  "wholesaleTotal": 0,
  "shippingCost": 1500,
  "margin": 0,
  "marginStatus": "NONE",
  "marginReleaseAt": "2026-10-06T10:00:00.000Z",
  "rtoCharge": 0,
  "returnCredit": 0,
  "items": [
    {}
  ],
  "tracking": {
    "number": "string",
    "courier": "string",
    "url": "https://example.com/markitmall/webhook"
  },
  "cancellationReason": "string",
  "mode": "live",
  "confirmation": "PENDING",
  "prepaidAmount": 1500,
  "resaleTotal": 0,
  "shippingCharged": 0,
  "platformFee": {
    "basis": "margin",
    "percent": 0,
    "amount": 1500
  },
  "expectedMargin": 0,
  "rtoReserve": 0,
  "customer": {},
  "fundsDeadline": "2026-10-06T10:00:00.000Z",
  "history": [
    {
      "status": "string",
      "at": "2026-10-06T10:00:00.000Z",
      "note": "string"
    }
  ],
  "createdAt": "2026-10-06T10:00:00.000Z"
}

Errors: 401, 404, 409, 422 — the body is always { error: { code, message, details } }.

Sandbox only: move a test order to a stage and receive its webhook

post/orders/{id}/simulate

Parameters

idrequired
path · string

Request body

statusrequired
enum
—

CONFIRMEDPROCESSINGSHIPPEDDELIVEREDCANCELLEDRETURNED

Example request

curl -X POST "https://backend.markitmall.com/dropship/v1/orders/{id}/simulate" \
  -H "Authorization: Bearer mk_test_XXXX:sk_test_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "CONFIRMED"
}'

Response 200

Order

id
string
—
externalOrderId
string
—
externalOrderName
string | null
—
parcel
object
—
parcel.part
integer
—
parcel.of
integer
—
orderNumber
string | null
—
status
OrderStatus
—
paymentMode
enum
—

CODPREPAID

codAmount
integer
—
wholesaleTotal
integer
—
shippingCost
integer
—
margin
integer
—
marginStatus
enum
—

NONEPENDINGRELEASEDREVERSED

marginReleaseAt
string | null · date-time
—
rtoCharge
integer
—
returnCredit
integer
—
items
object[]
—
tracking
object | null
—
tracking.number
string
—
tracking.courier
string
—
tracking.url
string | null
—
cancellationReason
string | null
—
mode
enum
—

livetest

confirmation
enum
—

PENDINGCONFIRMEDFAILEDNOT_REQUIRED

prepaidAmount
integer
—
resaleTotal
integer
—
shippingCharged
integer
—
platformFee
object

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.

platformFee.basis
enum
—

marginsale

platformFee.percent
number
—
platformFee.amount
integer
—
expectedMargin
integer

COD: credited after delivery, the fee already taken off. Prepaid: minus the platform fee.

rtoReserve
integer
—
customer
object
—
fundsDeadline
string | null · date-time
—
history
object[]
—
history[].status
string
—
history[].at
string · date-time
—
history[].note
string | null
—
createdAt
string · date-time
—
Example response
JSON
{
  "id": "66f0c2a1b2c3d4e5f6a7b8c9",
  "externalOrderId": "66f0c2a1b2c3d4e5f6a7b8c9",
  "externalOrderName": "string",
  "parcel": {
    "part": 0,
    "of": 0
  },
  "orderNumber": "string",
  "status": "AWAITING_FUNDS",
  "paymentMode": "COD",
  "codAmount": 1500,
  "wholesaleTotal": 0,
  "shippingCost": 1500,
  "margin": 0,
  "marginStatus": "NONE",
  "marginReleaseAt": "2026-10-06T10:00:00.000Z",
  "rtoCharge": 0,
  "returnCredit": 0,
  "items": [
    {}
  ],
  "tracking": {
    "number": "string",
    "courier": "string",
    "url": "https://example.com/markitmall/webhook"
  },
  "cancellationReason": "string",
  "mode": "live",
  "confirmation": "PENDING",
  "prepaidAmount": 1500,
  "resaleTotal": 0,
  "shippingCharged": 0,
  "platformFee": {
    "basis": "margin",
    "percent": 0,
    "amount": 1500
  },
  "expectedMargin": 0,
  "rtoReserve": 0,
  "customer": {},
  "fundsDeadline": "2026-10-06T10:00:00.000Z",
  "history": [
    {
      "status": "string",
      "at": "2026-10-06T10:00:00.000Z",
      "note": "string"
    }
  ],
  "createdAt": "2026-10-06T10:00:00.000Z"
}

Errors: 401, 404, 422 — the body is always { error: { code, message, details } }.