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 /v1/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. statuses is a multi-select OR filter; the older single status remains accepted. Status counts summarize the date and brand scope, while order detail reads a particular order.

curl --get 'https://backend.nasam.co/v1/orders' \
  --data-urlencode 'brandIds=20' \
  --data-urlencode 'fulfillmentModel=Seller' \
  --data-urlencode 'statuses=Created,Packed' \
  -H 'key: YOUR_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. 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

1. Choose a seller order and check its shipments. Read the order after selecting it from the seller-filtered directory. Check canComposeShipments and confirmedShipmentCount if the order needs more than one parcel. A marketplace-fulfilled order has no seller label, even when its commercial record appears in the directory.
2. Compose parcels before packing, if needed. Declare a shipment plan for an eligible order with at least two units and one live Created shipment. Send shipments, with each shipment's lines identifying orderItemId and quantity; the array length is the requested parcel count. Allocate the order's units exactly. The operation may return Created, Requested, or AlreadyComposed, with requested and confirmed counts. Re-read the order after Requested or AlreadyComposed; 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.
3. Pack the confirmed shipments. Pack orderIds in batches of 1–200. Every submitted ID receives an outcome in orders; 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.
4. Print labels that exist. Read a shipment label by shipment ID when canPrintShippingLabel is 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 with brandId, saleChannelId, and pre-handover statuses. Compare included orders with departureGroupSize; parcels without labels can be omitted, and a group with no printable label is rejected.
5. File the pickup list when a departure is present. Use departureId from the seller-filtered order read in file pickup list. Filing sends shipments to the channel and cannot be undone. Inspect outcome, shipments, notShipped, and failureReason even on HTTP success: a Refused list 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.

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. 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 no longer a seller action. 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. 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, and done is settled or withdrawn. 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.

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.

Order import is a separate write with its own required brand, channel, and file fields. 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.