curl -H "X-API-Key: $GOMRY_RETAIL_API_KEY" \
"https://integration.example.com/api/vendor/v1/orders?vendorKey=acme&reference=8b1f3c5e2a9d4f7081c6e2b4a0d9f3e1"
{
"orders": [
{
"vendorOrderId": "ord_551204",
"state": "accepted",
"totalCost": 192.0,
"currency": "USD"
}
]
}
{ "orders": [] }
{
"error": {
"code": "integration_error",
"message": "Order search failed upstream: 503 Service Unavailable"
}
}
Purchasing
Search Orders
Find orders carrying Retail’s reference. How Retail learns what actually happened.
curl -H "X-API-Key: $GOMRY_RETAIL_API_KEY" \
"https://integration.example.com/api/vendor/v1/orders?vendorKey=acme&reference=8b1f3c5e2a9d4f7081c6e2b4a0d9f3e1"
{
"orders": [
{
"vendorOrderId": "ord_551204",
"state": "accepted",
"totalCost": 192.0,
"currency": "USD"
}
]
}
{ "orders": [] }
{
"error": {
"code": "integration_error",
"message": "Order search failed upstream: 503 Service Unavailable"
}
}
Search Orders
Finds every order in your system that carries Retail’sreference. This is how Retail learns the truth about an order, and it is the endpoint that keeps a lost reply from becoming a double purchase.
Retail calls it:
- after a Place order call that failed or timed out, before deciding whether to submit again;
- after a webhook that names the order;
- on an hourly sweep of orders that have not been accepted yet.
Distinguish “searched and found nothing” from “could not search”.
{ "orders": [] } tells Retail no order exists, which allows it to submit again. If your search failed or timed out, return an error (502), never an empty list. Reporting a failed search as empty is how a ticket gets bought twice.Query Parameters
string
required
Your supplier identifier.
string
required
Retail’s reference, as sent on Place order.
Response
array
required
Every order carrying this reference, normally zero or one. Each has the same shape as the Place order response:
vendorOrderId, state, totalCost, currency and optional raw.Return all matches, including cancelled ones. More than one live order for one reference means a possible double purchase, and Retail flags it for a person to review.state from your system’s current record, not from a cache. When you cannot tell, answer unknown: Retail leaves its own record unchanged, where a wrong rejected strands a buyer who has paid and a wrong accepted sells a ticket nobody has.
Search on a field where your system actually stores the reference. Some systems accept a reference on create but return it empty when the order is read back, and only find it through a search filter. Verify on your sandbox that a newly placed order is found here.
curl -H "X-API-Key: $GOMRY_RETAIL_API_KEY" \
"https://integration.example.com/api/vendor/v1/orders?vendorKey=acme&reference=8b1f3c5e2a9d4f7081c6e2b4a0d9f3e1"
{
"orders": [
{
"vendorOrderId": "ord_551204",
"state": "accepted",
"totalCost": 192.0,
"currency": "USD"
}
]
}
{ "orders": [] }
{
"error": {
"code": "integration_error",
"message": "Order search failed upstream: 503 Service Unavailable"
}
}