Custom store API / Overview
Custom store API overview
If you run your own store platform, expose an API that follows this spec and LIA can look up orders, shipments, members and products directly to answer your customers. Lillo calls your API (pull), so your store doesn't need to push anything to Lillo.
Field names match the Cafe24 Admin API (snake_case). If you've built Cafe24 responses before, use the same names. Lillo-only fields are marked “extension.”
What you can do
| Version | What it unlocks | Implementation |
|---|---|---|
| v1.0 | Order and shipment lookup, member lookup, product search and detail | Only order lookup is required |
| v1.1 | Cancellation, return and exchange requests, address changes, order memos, coupon lookup and issuing, categories, catalog sync | All optional |
Writes that move money or change customer data are only called after a team member approves them. Lillo never triggers refunds.
Quick start
- 1
Issue an API key
In the console, go to Settings > Connectors > Custom commerce, save your API base URL (e.g.
https://api.mall.example.com) and issue an API key. Click [Activate] to make it the active key. Keep the key on your store's server only. - 2
Implement the endpoints
At minimum, build
GET /v1/ordersandGET /v1/orders/{order_id}. Tell Lillo what else you support withGET /v1/capabilities, and Lillo uses only those features. - 3
Connect in the console
On the same screen, click [Test connection]. Lillo calls
GET /v1/capabilitiesto verify the connection, and once it passes, your store data is used in conversations right away.
Authentication
Lillo sends your API key as a Bearer token on every request. Return 401 when the key is missing or wrong.
curl "https://api.mall.example.com/v1/capabilities" \
-H "Authorization: Bearer $LILLO_API_KEY" \
-H "X-Lillo-Api-Version: 2026-11-01"AuthorizationstringRequired
Bearer <API key>. Compare keys in constant time (timingSafeEqual, hash_equals)
X-Lillo-Api-VersionstringRequired
Always 2026-11-01
X-Lillo-Request-IdstringOptional
Request trace ID. Sent when available — log it so support can find the request quickly
Idempotency-KeystringConditional
Sent on write (v1.1) requests only. Up to 64 characters
Key management
Never log API keys. Rotate them in the console in two steps: issue, then activate. The previous key keeps working until you activate the new one.
Conventions
| Item | Rule |
|---|---|
| Base URL | The API base URL saved in the console + /v1/... |
| Protocol | HTTPS only. Lillo doesn't follow redirects |
| Response shape | Single object { "data": {...} }, list { "data": [...], "meta": { "next_cursor": ... } } |
| ID | Strings (product_no is "77" too) |
| Timestamps | ISO 8601 with a time zone (2026-11-10T21:14:03+09:00) |
| Amounts | Decimal strings, with one currency per object (KRW if omitted) |
| Booleans | "T" / "F", like Cafe24 |
| Phone number | Lillo sends digits only (01012345678) |
| Timeout | 8 seconds. Aim for a p95 under 1 second |
| Rate limit | We recommend allowing at least 10 requests per second per key. Return 429 when exceeded |
API reference
- GET
/v1/capabilitiesDeclare supported features - GET
/v1/ordersList orders - GET
/v1/orders/{order_id}Get an order - GET
/v1/orders/{order_id}/shipmentsShipment tracking - GET
/v1/customers/{member_id}Get a member - GET
/v1/customers?cellphone=Find a member by phone - GET
/v1/productsSearch products / catalog list - GET
/v1/products/{product_no}Get a product - GET
/v1/categoriesCategoriesv1.1 - POST
/v1/orders/{order_id}/cancellationRequest cancellationv1.1 - POST
/v1/orders/{order_id}/returnReturn requestv1.1 - POST
/v1/orders/{order_id}/exchangeExchange requestv1.1 - PUT
/v1/orders/{order_id}/receiversChange addressv1.1 - POST
/v1/orders/{order_id}/memosOrder memov1.1 - GET
/v1/couponsList couponsv1.1 - GET
/v1/customers/{member_id}/couponsMember's couponsv1.1 - POST
/v1/coupons/{coupon_no}/issuesIssue a couponv1.1
Version
This page covers API version 2026-11-01, spec v1.1. Items marked “coming soon” aren't used by Lillo yet. See the changelog for what's new.