Custom store API / Order writes

Order writes (v1.1)

During a conversation, LIA can file cancellation, return and exchange requests, change the shipping address and leave order memos directly in your store. Lillo only calls what you turn on in capabilities.

Called only after approval

Cancellations, returns, exchanges and address changes are called only after a team member approves them. Nothing is auto-approved, and requests past their deadline are put on hold. Order memos are internal notes, so they're left without approval.

Conventions

Request bodies use { "request": {...} } like Cafe24, and responses use { "data": {...} }. Send Content-Type: application/json.
Every write carries an Idempotency-Key header. If the same key comes again, don't run it again — return the original response as is.
If the body includes member_id or buyer_cellphone, check the order belongs to that owner and return 404 if not.
requested_by in the body is "lillo". Please show it as “Requested via Lillo” in your store admin.
Respond within 8 seconds. If processing takes longer, just accept the request and return 202 with the current status.
Notification texts and emails follow your store's policy. Lillo doesn't message the customer separately; it lets them know in the conversation.

Request cancellation

POST/v1/orders/{order_id}/cancellation

Body (request)

claim_reason_typestringRequired

Cafe24 code — A changed mind, B late delivery, J defective or wrong item, K other. Use A if unsure

requested_bystringRequired

"lillo"

claim_reasonstringOptional

Reason text

itemsobject[]Optional

order_item_code, quantity. Omit for the whole order

member_id / buyer_cellphonestringOptional

For checking the owner. Without it, handle the request with admin rights

ParameterTypeRequiredDescription

claim_reason_typestringRequiredCafe24 code — A changed mind, B late delivery, J defective or wrong item, K other. Use A if unsure

requested_bystringRequired"lillo"

claim_reasonstringOptionalReason text

itemsobject[]Optionalorder_item_code, quantity. Omit for the whole order

member_id / buyer_cellphonestringOptionalFor checking the owner. Without it, handle the request with admin rights

Request

curl -X POST "https://api.mall.example.com/v1/orders/20261110-0001234/cancellation" \
  -H "Authorization: Bearer $LILLO_API_KEY" \
  -H "X-Lillo-Api-Version: 2026-11-01" \
  -H "Idempotency-Key: 6f1c2a9e-4b7d-4f0e-9a51-3d2c8e7b1a04" \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "member_id": "m_1001",
      "claim_reason_type": "A",
      "claim_reason": "Changed mind",
      "items": [{ "order_item_code": "20261110-0001234-01", "quantity": 1 }],
      "requested_by": "lillo"
    }
  }'

Response — 201 Created

{
  "data": {
    "order_id": "20261110-0001234",
    "claim_type": "cancel",
    "claim_code": "C-20261112-0001",
    "items": [
      { "order_item_code": "20261110-0001234-01", "order_status": "C00" }
    ]
  }
}

The item order_status in the response is the status after the request (C00/C10, or C40 if completed right away). If the items have already shipped, return 409 not_allowed_in_state.

Error response — 409

{
  "error": {
    "code": "not_allowed_in_state",
    "message": "Already shipped",
    "order_status": "N30"
  }
}

Return request

POST/v1/orders/{order_id}/return

The body is the same as for cancellations, and you can add the fields below. Item statuses in the response are R00/R10.

statusstringOptional

accepted or processing — same as Cafe24

pickupobjectOptional

Pickup address: name, cellphone, zipcode, address1, address2. Defaults to the order's shipping address

ParameterTypeRequiredDescription

statusstringOptionalaccepted or processing — same as Cafe24

pickupobjectOptionalPickup address: name, cellphone, zipcode, address1, address2. Defaults to the order's shipping address

Exchange request

POST/v1/orders/{order_id}/exchange

The body is the same as for cancellations, plus the new option in exchange_items. Without it, the item is exchanged for the same option (defect exchange). Item statuses in the response are E00/E10; if the option is sold out, return 409 out_of_stock.

Body — exchange_items

"exchange_items": [
  { "order_item_code": "20261110-0001234-01",
    "variant_code": "P000000X000B", "quantity": 1 }
]

Change address

PUT/v1/orders/{order_id}/receivers

zipcodestringRequired

Postal code

address1stringRequired

Base URL

address2stringOptional

Address line 2

namestringOptional

Recipient

cellphonestringOptional

Mobile number (digits only)

shipping_messagestringOptional

Delivery note

member_idstringOptional

For checking the owner

ParameterTypeRequiredDescription

zipcodestringRequiredPostal code

address1stringRequiredBase URL

address2stringOptionalAddress line 2

namestringOptionalRecipient

cellphonestringOptionalMobile number (digits only)

shipping_messagestringOptionalDelivery note

member_idstringOptionalFor checking the owner

Send only the values that change. The response is { "data": { "order_id", "receivers": [...] } }; mask names and contact details.

Request

curl -X PUT "https://api.mall.example.com/v1/orders/20261110-0001234/receivers" \
  -H "Authorization: Bearer $LILLO_API_KEY" \
  -H "X-Lillo-Api-Version: 2026-11-01" \
  -H "Idempotency-Key: 6f1c2a9e-4b7d-4f0e-9a51-3d2c8e7b1a04" \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "member_id": "m_1001",
      "zipcode": "06236",
      "address1": "123 Teheran-ro, Gangnam-gu, Seoul",
      "address2": "5F",
      "shipping_message": "Leave at the door"
    }
  }'

Order memo

POST/v1/orders/{order_id}/memos

memostringRequired

Memo text. Up to 2,000 characters

authorstringRequired

Author (e.g. "LIA")

starred_memostringOptional

"T"/"F"

fixedstringOptional

"T"/"F"

ParameterTypeRequiredDescription

memostringRequiredMemo text. Up to 2,000 characters

authorstringRequiredAuthor (e.g. "LIA")

starred_memostringOptional"T"/"F"

fixedstringOptional"T"/"F"

Memos are visible to store admins only. The response is { "data": { "memo_no", "order_id" } }.

Request

curl -X POST "https://api.mall.example.com/v1/orders/20261110-0001234/memos" \
  -H "Authorization: Bearer $LILLO_API_KEY" \
  -H "X-Lillo-Api-Version: 2026-11-01" \
  -H "Idempotency-Key: 6f1c2a9e-4b7d-4f0e-9a51-3d2c8e7b1a04" \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "memo": "Customer asked for morning delivery on 11/14",
      "starred_memo": "F",
      "fixed": "F",
      "author": "LIA"
    }
  }'

PreviousProducts & catalog NextCoupons