Orders

A channel manager order represents a single purchase made by an external sales channel. The order header carries the partner and customer context; one or more item lines describe what is being issued. Ticket issuance, wallet creation, and manifest generation all run synchronously inside the API call, so the response to createOrder and replaceOrder already carries the issued state.

Key concepts

• Partner identity — partnerId is assigned to each partner that may submit orders. The partner must exist in the Channel Manager Partner Setup and have Active = true; inactive partners are rejected at creation time.
• Order reference — sellToOrderReference is the partner’s own order number. The pair (partnerId, sellToOrderReference) is unique per order; this lets partners look up an order by their own reference and protects against duplicate submission.
• Items — each items entry resolves to one Business Central item. The line’s quantity, visitDate, and visitTime apply to all wallets that the line issues. A package item additionally expands into one wallet per package, with component-level scheduling provided via wallet.componentSchedule.
• Wallets and assets — issued tickets live inside a wallet, which is the unit of issuance (one wallet per recipient). The response carries the wallet’s walletReferenceNumber, the individual ticket numbers under assets, and a manifestUrl that renders the wallet shell. The partner is responsible for delivering the wallet (or its manifestUrl) to the customer.

Status lifecycle

replaceOrder is rejected outside Draft and Error. deleteOrder is rejected while the order is Processing (only relevant in the rare case where an issuance worker has stalled and the order has not yet settled).

Status semantics

• Draft is the resting state for orders awaiting payment. Send paymentReference via confirmOrder to release them for issuance.
• Issued is the normal terminal state once tickets have been minted and the manifest built.
• Error orders expose the failure reason in statusMessage. The recommended remediation is to fix the offending item or schedule and call replaceOrder; any partially issued wallets are destroyed and re-issued.
• Processing is a transient internal state committed while the issuance worker runs. It is never the status of an API response in normal operation; you may observe it via getOrder only if the worker has stalled.

Replacing versus deleting

PUT /channelManager/{orderId} replaces the contents of an order — header mutables, items, wallets — but not its identity. To cancel an issued order, call DELETE; the row is retained with status = Cancelled for audit, and the wallets are destroyed. Deleting a Draft or Error order removes the order row entirely.

Idempotency notes

• createOrder is idempotent on (partnerId, sellToOrderReference) only in the sense that a second submission is rejected with 400 Bad Request. There is no automatic merge — to retry after an error, use replaceOrder.
• confirmOrder on an already-Issued order is a no-op and returns the order unchanged.