For developers

The shop API

If you run a shop on kedai.store and want your own software to read it, this is the API for that: print today's orders from a script, push your stock to another site, or pull sales into a spreadsheet. It is version 1, and version 1 only reads — but the same key can also run the shop, which is further down this page.

What a key is

A key is how your software asks kedai.store a question. You make one on the API keys screen, and it looks like this:

ks_live_<12 characters>_<40 characters>

The first part identifies the key and the second part proves it. The secret is shown exactly once, the moment the key is made, and only a fingerprint of it is kept afterwards. If it is lost it cannot be recovered: revoke that key and mint another.

A key belongs to one shop and carries a set of abilities, which are the same permission codes the staff roles use, such as orders.view. It reaches exactly what its abilities allow and can never reach a different shop, and there is no person behind it: it does not carry a login. Reading needs a .view ability and changing something needs a .manage one, so a key scoped for reading cannot write. Ask the shopkeeper for a key with the narrowest set of abilities the script needs.

How to send it

The whole key goes as a bearer token on every request. There is no session, no cookie and no CSRF token: every request stands on its own.

Authorization: Bearer <the whole key>
Accept: application/json

The base of the API is https://kedai.store/api/v1. A first request, with the key in a variable so it stays out of your shell history:

export KEDAI_KEY="<paste the key here>"

curl -s https://kedai.store/api/v1/shop \
  -H "Authorization: Bearer $KEDAI_KEY" \
  -H "Accept: application/json"

• Do not send X-Shop-Id. A key decides its own shop, and a header naming a different one is refused with a 400 rather than quietly answered. Silently reading the wrong shop is worse than a refusal.
• A portal session token will not work here. A key and a session are two different doors, and each is refused at the other.

The endpoints

Every endpoint in this table is a GET, because this is version 1 of the read API and it writes nothing. Writing is a second surface with its own rules: your AI can run the shop, further down this page.

If the key lacks the ability an endpoint needs, the answer is 403 with the code it wanted, which is the same refusal a member of the shop would get. Check the key's abilities before blaming the request.

Lists, and polling for changes

The list endpoints share three query parameters:

• per_page: How many rows per page. Default 20, capped at 100. Asking for more than the cap is answered with the cap rather than refused.
• page: Which page to read, counting from 1.
• updated_since: An ISO 8601 timestamp. Only rows changed at or after it are returned. The comparison is inclusive. Poll with this instead of reading the whole shop.

orders and subscriptions also take a status filter, narrowed to the states each one knows. To keep in step without reading the whole shop every run, store the newest updated_at you have seen and send it back as updated_since.

Money is in sen

Every amount is an integer in sen, in a field whose name ends _minor. That integer is the truth. A formatted string travels beside it for display only, and is never the thing to parse or to sum.

"total_minor": 12345,
"total": "RM 123.45"

12345 is RM123.45. To add up a basket, add the _minor integers and ignore the strings. Some amounts can be null, and null is not zero: a product with no price is answered price_minor: null, which means no price was set rather than a free item.

Errors

Every error has the same shape: a machine code, a sentence message, and, when one field is to blame, a field naming it.

{
  "code": "invalid_parameter",
  "message": "The per page field must be an integer.",
  "field": "per_page"
}

The codes the API can answer with:

• shop_mismatch
• missing_api_key
• invalid_api_key
• revoked_api_key
• expired_api_key
• forbidden
• not_found
• method_not_allowed
• invalid_parameter
• rate_limited

A 401 is never a reason to retry, and it is never the server's fault: check the key is right, that it has not been revoked and that it has not expired. A 404 for a row you expect to exist is most often a row in a different shop, since a key only ever sees its own.

The rate limit

Each key is allowed 60 requests a minute. The allowance is counted per key, so one busy key does not spend another's. When it is used up the answer is 429 with these headers:

• Retry-After: the number of seconds to wait before trying again.
• X-RateLimit-Limit: the ceiling, 60.
• X-RateLimit-Remaining: how many requests are left in this window.

Wait the seconds in Retry-After before sending again. A well behaved script backs off rather than hammering the endpoint.

Your AI can run the shop

Everything above is reading. The same key also runs the shop: it adds and edits products, moves an order through fulfilment, publishes a theme — 87 operations in all. That is what lets a shopkeeper hand the shop to an assistant and ask for the work in a sentence instead of clicking through screens.

Point an AI client at it

Any client that speaks the Model Context Protocol over HTTP can be given the endpoint and the key. The block below is the shape they mostly share, but the field names differ a little between clients; the two things that matter are the URL and the Authorization header.

{
  "mcpServers": {
    "kedai-store": {
      "type": "http",
      "url": "https://kedai.store/api/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}

• A client that only speaks stdio cannot reach an HTTP endpoint on its own and needs a small bridge process in front of it. The URL and the header are still the only two things to give it.
• The type is sometimes called streamable-http, and some clients take the URL as serverUrl. If yours refuses the block, the field name is what to change — not the endpoint.

An AI that would rather make plain HTTP calls needs no protocol at all. Every operation below is also ordinary REST — POST https://kedai.store/api/mcp/products with a bearer key and a JSON body does what the tool does:

curl -s https://kedai.store/api/mcp/products \
  -H "Authorization: Bearer <the key you minted>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "Kopi Takeaway", "price_minor": 1200}'

Clients that want a schema instead of a protocol

ChatGPT and the other assistants that take an OpenAPI document rather than speak a protocol read the same operations from one URL. Point a Custom GPT Action — or any function-calling framework, or a Postman collection — at:

https://kedai.store/api/mcp/openapi.json

It names every operation, the ability each one needs, and the refusals a caller can correct. Some clients cap how many operations one Action may hold, and this surface is larger than that cap — add ?area=products to take one area at a time, and read x-areas in the document for the list to choose from.

The tools an AI gets

These are named, described and callable over the protocol, which is what makes an assistant able to use them without being told how. Each needs the ability beside it.

Every operation, under the ability it needs

This is the list to read while ticking boxes on the key screen. A key holding products.manage gets every line in that group and nothing from the others.

What a key can never do

An AI with a key can run a shop. It cannot become the shopkeeper. These are refused however the key is scoped, because they are the powers the platform decided belong to the person and to no program:

• wallet.topup — Top up the wallet. putting money in is the shopkeeper's own act
• billing.manage — Billing and closing the shop. the card on file, the plan, and closing the shop
• bank.manage — Payment, payout and courier accounts. the shop's own CHIP and courier credentials, and its payout account
• members.transfer — Hand the shop over. handing the shop to somebody else

It cannot reach these parts of the API either, and each of these is a decision rather than an oversight:

• /api/shop/api-keys — A key that can mint keys can widen itself past the codes it holds.
• /api/shop/oauth — Consenting is a person's decision on a screen: a key that could reach it would grant itself a connection.
• /api/lead-campaigns — Sending a campaign mails real people and cannot be undone: it is the owner's act on the screen, not a tool a model may fire.
• /api/members — Identity: who may act for the shop is a person's decision.
• /api/roles — Identity: the roles a key's codes are drawn from.
• /api/auth — The caller's own session, not the shop's work.
• /api/account — The caller's own account, not the shop's work.
• /api/email — The caller's own address, not the shop's work.
• /api/admin — The platform operator's console, which is not a shop at all.
• /api/onboarding — Onboarding runs before a shop exists, and a key belongs to one.

Sending the same write twice

An assistant that loses its connection cannot tell whether the product was created. So a write may carry an Idempotency-Key header: if the same key arrives twice, the second request is answered with the first request's answer rather than doing the work again, and the reply carries Idempotent-Replay: true so the caller can tell a repeat from a fresh write.

A write that was refused frees its key, so a request corrected after a 422 may send the same one again.

What version 1 does not do

• Version 1 of the read API writes nothing. Writing exists, on the agent surface above, which is a different door with its own boundary rather than a later version of this one.
• No webhooks. Poll updated_since instead.
• No OAuth, and no acting for a shop without holding a key.
• No per endpoint control beyond the abilities on the key.
• Nothing on the storefront. This is the shop's own API, not the shopper's.