Creates a new Retailer and the Purchaser (trading relationship) linking it to your supplier. The response contains both records.

This endpoint always creates a new retailer. There is no way to attach the purchaser to a retailer that already exists in Ordermentum.

Duplicate risk. When creating venues from an external system into Ordermentum, you may lack the context needed to tell whether that
venue already exists, so you are at risk of creating a duplicate. The typical flow is the other way around: customers are created in
Ordermentum, synced out to the external system, and then updated from the external system back into Ordermentum.

The payload is flat. Retailer fields (legalName, tradingName, address, …), purchaser/trading fields (priceGroupId, scheduleIds,
paymentDelay, …) and supplierId all sit at the top level of the same object. Unknown keys are accepted and ignored.

Required: supplierId, legalName and tradingName. Everything else is optional.

If you include an address or billingAddress object, then street1, suburb, state and postcode are required within it. Omit the
object entirely and none of them are required.

isActive controls whether the relationship is live. It defaults to false — omitting it creates the purchaser with disabledAt set, i.e.
the venue exists but cannot trade. Send isActive: true for a venue that should be able to order immediately.

Activation. activatedAt is set on the purchaser automatically.

Authorization. The API key must hold customers-full or customers-create on the supplier named in supplierId, otherwise the request
returns 403.

Error responses are coarse. Almost every failure — missing legalName, an unknown supplierId, an invalid address, a database error —
surfaces as 400 {"message": "Error creating venue"} without naming the offending field. Validate the payload against this schema before
sending. Only malformed scheduleIds or users values, and the 403, return a more specific message.