An OTA 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. The endpoints are asynchronous — createOrder and replaceOrder accept the
order, persist it as Submitted, and return immediately. Ticket and coupon issuance, wallet
manifest build, and settling to a terminal state all happen in the background.
If you need a stable, customer-facing identifier for each wallet at the moment you receive a
Submitted response — to render as a QR code in a confirmation email, print on a receipt, or store
in your own system as the customer’s “ticket number” — supply it yourself when you submit the order.
Set wallet.externalReferenceNumbers to an array containing one value per expected wallet on the
line (quantity values for individual tickets, or 1 for group tickets). On submission your values
are stored on the wallet shells and echoed back in the response. When the wallets are later minted,
the same numbers are stamped onto them — so the reference you handed your customer at submit time
is exactly what they will present at admission.
partnerId identifies your integration. It is issued when your
partnership is set up; orders submitted before then, or under a partnership that has been
disabled, are rejected.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. buyFromOrderReference is the
OTA Channel Manager’s own document number, returned in every response for partner-side
reconciliation.items entry resolves to one item in the venue’s catalog. 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. Some packages also yield discount coupons alongside the tickets.walletReferenceNumber,
the individual asset numbers under assets (each entry is either a ticket or a coupon), and
a manifestUrl for rendering the wallet. The partner is responsible for delivering the wallet
(or its manifestUrl) to the customer.replaceOrder is rejected outside Draft and Error. deleteOrder is rejected while the order
is Submitted, Scheduled, or Processing; wait for the order to settle to a terminal status and
retry.
Submitted / Scheduled / Processing are the in-flight states. From a partner’s point of
view they are equivalent — “the order is still being worked on.” Subscribe to
ota_cm_order_processed for completion notifications, or poll getOrder.Draft is the resting state for orders that completed issuance without a paymentReference.
Tickets and coupons have been minted but are not valid until the order is confirmed. Send
paymentReference via confirmOrder to release them to Issued.Issued is the normal terminal state once tickets and coupons 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 (which destroys any partial wallets
and re-issues), or to delete the order outright.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.
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.