Orders, seller fulfillment, and returns
An order is the commercial record. It can have several shipments or parcels, each with its own status and label. Use an order's fulfillmentModel and the live shipment rows before offering a seller action; marketplace-fulfilled orders do not have seller shipping labels.
Choose the right workflow
| What you are doing | Starting point | What completes the work |
|---|---|---|
| Monitoring all orders, including marketplace fulfillment | Order directory | Follow the order and its shipment states; do not offer seller shipping actions for marketplace fulfillment. |
| Packing and handing over seller orders | Filter the order directory with fulfillmentModel=Seller | Check each pack result, print available shipment labels, and file a pickup list when the channel has a departure. |
| Handling a customer return | Return queue | Accept a waiting return where the channel requires a seller decision, then follow its settled lines. |
| Recovering money on a settled return | Compensation list | File the eligible line and record the channel's verdict. |
The order, shipment, return, and compensation line have different IDs. Keep them separately. A return may refer to a channel order that Nasam has not synced, and a single order may have multiple shipments or return lines.
Find the work
GET /orders returns orders and pagination, defaulting to page 1 and limit 10. Narrow with brandIds, startDate/endDate, excludedSaleChannelIds, comma-separated shipment statuses, fulfillmentModel, search, or isOverdue, which takes only orders placed in the last 60 days with a shipment past its ship-by. statuses is a multi-select OR filter; the older single status remains accepted. Mahally and Mazeed orders arrive through Salla and Zid: excluding the store's channel still keeps the orders the marketplace placed through it until the marketplace's own channel id is excluded too. Status counts summarize the date and brand scope, while order detail reads a particular order.
curl --get 'https://api.nasam.co/mm-api/v1/orders' \
--data-urlencode 'brandIds=20' \
--data-urlencode 'fulfillmentModel=Seller' \
--data-urlencode 'statuses=Created,Packed' \
-H "Authorization: Bearer $NASAM_API_KEY"
The directory provides shipments with parcel IDs, tracking, dates, and canPrintShippingLabel. It includes a fulfillment block only when the seller-fulfillment filter is active and the channel is operated for fulfillment. That block can contain a departure ID, shipping account, requestedShipmentCount, confirmedShipmentCount, and canComposeShipments. The top-level departures group is likewise present only for fulfillmentModel=Seller; there is no separate departure-list read.
Read orderItems and shipments from the same order before acting. An order keeps every line it was placed with: a line's quantity is the units the order holds now, and its tally says how many were ordered, cancelled and returned, so a line whose every unit left reads quantity: 0. Plan parcels and cancels from lines with quantity above 0. The order's own tally sums units and value the same way, and hasWithdrawals says whether any unit left it while it was live. Shipment state, not just the order summary, determines whether a label can be printed or a shipment is still waiting to leave. A fulfillment block can be absent on a seller-filtered order when Nasam does not operate that channel's fulfillment; absence does not mean a zero count. Shared marketplace accounts can group several brands into one shipping run, so use the returned shipping account and departure rather than constructing a group from the order's brand alone.
Pack, declare parcels, and print
- Choose a seller order and check its shipments. Read the order after selecting it from the seller-filtered directory. Check
canComposeShipmentsandconfirmedShipmentCountif the order needs more than one parcel. A marketplace-fulfilled order has no seller label, even when its commercial record appears in the directory. - Compose parcels before packing, if needed. Declare a shipment plan for an eligible order with at least two units and one live
Createdshipment. Sendshipments, with each shipment'slinesidentifyingorderItemIdandquantity; the array length is the requested parcel count. Allocate the order's units exactly. The operation may returnCreated,Requested, orAlreadyComposed, with requested and confirmed counts. Re-read the order afterRequestedorAlreadyComposed; never infer that a second declaration is needed from the first response alone. A channel timeout leaves the result unknown, so wait for a fresh order read before considering another request. This is an irreversible channel action. - Pack the confirmed shipments. Pack
orderIdsin batches of 1–200. Every submitted ID receives an outcome inorders; a per-order refusal stays inside a successful HTTP response. Inspect every outcome and re-read affected orders before printing. Unpack uses the same batch shape, but some channels cannot retract a packed mark, and a shipped parcel cannot be unpacked. Treat unpack as a new decision, not an automatic rollback. - Print labels that exist. Read a shipment label by shipment ID when
canPrintShippingLabelis true. The JSON response is either{url}or{content,format}; some labels use printer formats such as ZPL. A missing or inaccessible label returns 404. To collect a departure group's labels, create a label document withbrandId,saleChannelId(the departure'ssaleChannel.id), and pre-handoverstatuses. Compare included orders withdepartureGroupSize; parcels without labels can be omitted, and a group with no printable label is rejected. - File the pickup list when a departure is present. Use
departureIdfrom the seller-filtered order read in file pickup list. Filing sends shipments to the channel and cannot be undone. Inspectoutcome,shipments,notShipped, andfailureReasoneven on HTTP success: aRefusedlist can still have sent parcels. Work from the returned result and a fresh directory read before another filing. Read a filed list for a reprint; this read does not file again. Print theshipmentswithisWithdrawn: false—shipmentCountof them — because a parcel cancelled after filing stays on the list as withdrawn. List filed pickup lists to find one by its number or by the day it was filed; each shipment in the order directory also names itspickupList.
Seller fulfillment on noon
Not every step exists on every channel, so act on the fields the order read returns rather than on the channel's name. On noon:
- Parcel plan. Not available:
canComposeShipmentsis false, and an order ships as one shipment. - Pack. Packing a shipment gets it a noon waybill number, returned as the shipment's
trackingNumber. Unpack takes the mark back until the shipment is filed. - Label. noon issues no label file, so
canPrintShippingLabelis false and the label reads return 404. The label is the waybill number fromtrackingNumber, printed as a QR code with the number beneath it; noon's driver scans it at pickup. - Pickup list. Filing hands the packed shipments to noon and marks them shipped.
- Cancel. One reason, out of stock. Only whole order lines can be cancelled; a line's
quantityis ignored. A filed shipment can still be cancelled, and it stays on its pickup list as withdrawn.
Nasam also files each departure's pickup list itself at 09:45 Riyadh time, Saturday to Thursday, ahead of noon's 10:00 pickup cutoff. Shipments packed later the same day join the list already filed. If you file a list yourself while Nasam is filing the same departure, the call is refused; read the directory again and file only what is still pending.
Parcel-plan example
Use the actual orderItems[].id and quantities from the order detail. For an order with two distinct one-unit items, the request shape is:
{
"shipments": [
{"lines": [{"orderItemId": 501, "quantity": 1}]},
{"lines": [{"orderItemId": 502, "quantity": 1}]}
]
}
Those IDs illustrate the shape; replace them with the order's own line IDs. Do not declare a plan after a shipment is packed or while a prior shipment request is outstanding.
Cancel before handover
For cancellation, first read channel reasons with brandId and saleChannelId (the order's saleChannel.id). Send the returned code as reasonCode to cancel an order. Omit items to cancel the whole order; provide {sku,quantity} items for a partial cancellation supported by the channel.
Check the shipment state before presenting this action. Once an order has left the warehouse, cancellation is generally no longer a seller action; on noon, a shipment that is filed but not yet collected can still be cancelled. A channel can reject the reason or the cancellation itself; an HTTP failure should be shown as such, followed by a fresh order read. Do not silently retry a cancellation whose channel result is uncertain.
Returns and compensation
List returns with status=waiting, arriving, done, or all; the default is waiting. waiting is seller work, while arriving is a parcel the channel announced without a decision to make, or a settled return whose parcel has not been received. Filters also include brand/channel IDs, search (order number, tracking number, or SKU), and an opened-date range. The result has returns, pagination, status counts, and waitingAmountSar. The default page size is 50 and the maximum is 100.
Accept returns with 1–50 returnIds. The response reports an outcome per return, including failures; inspect all rows before retrying any ID. A return can exist without a synced order, so use its externalReturnId, orderIdInSaleChannel, and line details rather than assuming a Nasam order ID is present.
The queue separates work from tracking: waiting is an open seller decision, arriving is an announced parcel with no seller decision or a settled return whose parcel has not been received, and done is settled or withdrawn with its parcel received (or with nothing to receive). Open a waiting return's lines, reason, customer note, and amount before accepting it. After the batch call, move forward only for IDs with a successful outcome; a successful HTTP response does not mean all returns were accepted. Re-read the queue to see the latest channel state.
A return, and each of its lines, whose dispute is with the channel reads Open, the same as one still waiting for an answer, because the contract's statuses are closed. A line the seller won reads Withdrawn.
A return's reasonCategory of NotAsDescribed means the buyer says the product didn't match its listing. It counts as a defect, like Defective, and points at the listing's content rather than the product.
The compensation list is a line-level ledger of money owed for settled returns, with eligible, filed, adjudicated, expired, or all state filters. Mark a line filed, undo a filing, or record the channel verdict with verdict and optional awardedSar. Work from the line id, not the return ID.
Marketplace inbound webhooks are a different ingress surface and are not MM-API read/write operations.
Compensation line lifecycle
An eligible compensation belongs to a settled return line, not to the order or return as a whole. filed records that the claim was submitted, adjudicated records the channel decision, and expired is no longer a live filing opportunity. Use mark filed only after the claim is actually filed with the channel. Use undo filing when that record needs correction, and record verdict with Accepted or Rejected; awardedSar records a differing award when provided. Re-read the line after each change so an integration does not mistake its own filing record for money already awarded.