Sandbox open · Villa Market partners

Build a shop on Villa Market.

Villa's real catalog, branch prices and basket calculator, with orders and payment links. One API over GraphQL, REST and MCP.

Read the guide Open the demo shop →
88k+products mirrored
41online branches
Villa's ownbasket calculator
query {
  products(
    filter: { l1: "Fruits", pricedOnly: true }
    branchCode: "1000"
    first: 2
  ) {
    totalCount
    nodes { cprcode nameEn price { amount currency } }
  }
}
Response · live data
{ "totalCount": 867,
  "nodes": [
    { "cprcode": "65348", "nameEn": "Mango Mahachanok Pack",
      "price": { "amount": 150.0, "currency": "THB" } },
    { "cprcode": "76257", "nameEn": "Papaya",
      "price": { "amount": 90.0, "currency": "THB" } } ] }
How it works

From zero to a paid order in four calls

You own the customer experience. Villa remains the grocer: catalog, branch price, the bill and fulfilment rules come from Villa's own systems.

Get a partner key

Every call carries your key. It maps to your partner id and order source.

X-Partner-Key

Sign shoppers in

Shoppers create an account with email and a six-digit code. You send their id token.

Authorization: Bearer …

Quote with Villa's calculator

Delivery, coupons and discounts are priced exactly as Villa's storefront bills them.

mutation quote

Order and share the link

The order returns a payment link that shows the whole checkout and takes the payment.

orderCreate → paymentLink
Capabilities

Everything a partner shop needs

Each surface is live on this host today. Statuses are honest: sandbox means orders are recorded but not fulfilled and payment links take no money.

Catalog Live

What Villa sells online, by category and search, refreshed from Villa's product table every 15 minutes.

products · categories · GET /v1/products

Branch prices & stock Live

Prices come from each branch's own price feed, not a list price. Stock comes per branch.

product.price · inventory

Branches Live

All 41 online branches with location, plus nearest-branch lookup from coordinates.

branches · fulfilmentResolve

Basket, quote & orders Sandbox

Baskets and orders are scoped to your key and the shopper. Every total is Villa's calculator.

basketAdd · quote · orderCreate · orders

Payment links Sandbox

A signed 24-hour link that opens the whole checkout. The basket is re-priced before payment is accepted.

paymentLinkCreate · /pay/<token>

MCP for AI agents Live

The same operations as tools for assistants and agents, over Streamable HTTP.

POST /mcp/ · 18 tools
Hosts

Where things live

Host / pathWhat it is
https://developers.villamarket.aiThis site, the guide, and the API itself: /graphql, /mcp/, /v1/products, /schema.graphql, /health
https://shop.villamarket.aiDemo shop built only on this API. Payment links open here: /pay/<token>
/docsThe integration guide: auth, checkout, payment links, errors, sandbox rules
Ground rules

Four rules every integration follows

  • The quote is the bill. Never sum line prices in your app. Show grandTotal.
  • No card data here. Orders carry a payment link; card details never touch this API.
  • Shoppers are real sign-ins. The owner of a basket or order is the signed-in shopper, never an id you pass.
  • Sandbox until go-live. Orders are recorded but not fulfilled; payment links record payments without moving money.

See it working first

Create an account, fill a basket and pay through a payment link in the demo shop.

Open the demo shopRead the guide