FOR DEVELOPERS & SHOPPING AGENTS

One catalogue.
Many independent offers.

Build discovery around canonical product identities, GTINs and explicit merchant offers. Search publicly, compare fulfilment, quote a single merchant basket and hand control to the buyer when required.

Marketplace OpenAPI Explore the search API

60Canonical products

4Merchant profiles

158Merchant offers

70Catalogue searches

Marketplace database totals. Demonstration stock may be included; demo transactions never count as completed sales. View estate analytics →

01 / DISCOVER

Search products, then compare offers.

Search results represent product identities. Each merchant’s offer has separate price, stock, fulfilment and eligibility. Public discovery endpoints require no sign-in.

GET /wp-json/ursy/v1/search?q=Rioja&style=red&max_price=30
GET /wp-json/ursy/v1/products/{id}/offers
GET /wp-json/ursy/v1/merchants
GET /wp-json/ursy/v1/gtin/{gtin}

Search supports q, style, country, region, grape, vintage, merchant, min_price, max_price, page and limit. Search prices use pounds; transaction money uses integer pence.

02 / FIND THE RIGHT MERCHANT

Location and fulfilment are explicit.

GET /wp-json/ursy/v1/search?postcode=SW1A%201AA&radius_km=25&fulfilment=collection&sort=nearest
GET /wp-json/ursy/v1/search?merchant=1&style=red
GET /wp-json/ursy/v1/search?fulfilment=national

Use a valid UK postcode for location-aware results. Fulfilment values include national, local and collection. Check the chosen offer’s eligibility and obtain a fresh quote before checkout.

03 / ONE MERCHANT PER ORDER

Quote first. Checkout with consent.

POST /wp-json/ursy/v1/quote
Content-Type: application/json

{
  "items": [{"offer_id": 1, "quantity": 2}],
  "postcode": "SW1A 1AA",
  "fulfilment": "delivery"
}

The quote identifies the merchant, items, merchandise, delivery, total, expiry and whether buyer action is required. A quote is not a reservation or payment confirmation.

POST /wp-json/ursy/v1/checkout
Idempotency-Key: a-unique-key-for-this-checkout

{
  "quote_id": "quote-id-from-response",
  "age_confirmed": true
}

Checkout requires an authenticated account and the required age declaration. The merchant’s connected account receives its direct Stripe charge. Demo inventory is blocked from payment.

04 / ACCOUNT & SECURITY

Public discovery. Controlled writes.

Browser writes use the current WordPress session and an X-WP-Nonce token. Estate sign-in is provided through URSY.ID. Private merchant records enforce server-side ownership.

Use the published OpenAPI specification for the currently supported machine authentication paths. Public endpoints are rate limited; clients should handle 429 responses and back off. Do not treat an agent token as proof of legal age.

Your integration credentials.

Send the key as Authorization: Bearer YOUR_KEY. Key creation and revocation require your browser session. API keys never replace the required human steps for alcohol checkout.

05 / FAILURE IS PART OF THE CONTRACT

Handle changing stock and eligibility.

State	Client action
`mixed_merchant_cart`	Create a separate order for each merchant.
`offer_out_of_stock` / `offer_stale`	Refresh the offer and offer another merchant.
`restricted_goods_user_action_required`	Return control to the buyer for age and consent steps.
`destination_not_serviceable`	Change the destination or fulfilment method.
`quote_expired` / `price_changed`	Request a new quote and reconfirm the total.
`demo_inventory`	Explain that the demonstration offer cannot be purchased.
`stripe_not_ready`	Merchant payments need configuration before checkout.

Always display the server’s error message and preserve buyer control. Alcohol orders require suitable age-checked fulfilment; unattended delivery is not a checkout option.

06 / CAPABILITIES, HONESTLY

Integration status.

REST discovery: Available
GTIN enrichment: URSY.food integration
OpenAPI: Marketplace specification
ACP / UCP / MCP: No protocol certification or autonomous alcohol checkout is claimed.
Real payments: Gated by merchant readiness and platform configuration.

Changelog · 13 September 2026

Initial marketplace: canonical wine catalogue, demo merchant offers, GTIN discovery, merchant workspace and single-merchant quote flow.

Estate platform health & analytics