---
type: "Selection Playbook"
title: "Agent-ready ordering"
description: "How an AI agent hands a customer a purchase-page deep link, or prepares an order through the agent API or UCP; the customer reviews and pays."
resource: "https://buy.ev-boy.com/"
tags: ["playbook", "ordering", "deep-link", "agent", "zh-HK"]
timestamp: "2026-10-24T00:00:00+08:00"
---

# Scenario

An AI agent has helped a customer choose a product and wants to send them straight to the matching purchase page.

# Deep Link Format

`https://buy.ev-boy.com/Campaigns/{Campaign}/Purchase?item={ProductCode}`

* The purchase page opens with that product preselected.
* An unknown code, or a product not shown on the purchase page, opens the page without preselecting from the link.
* The customer still enters contact and delivery details, chooses delivery, reviews the server-calculated total and chooses a payment method.
* Prices, coupons and payment methods are calculated by the site; link parameters cannot change a price or add a gift.
* To prepare an order on the customer's behalf, use the agent API below. Do not guess or construct other API URLs.

# On-page agent data

Every supported campaign page and its purchase page carries, in `<head>`:

* `<link rel="alternate">` to `llms.txt`, this playbook and `GET /api/agent/v1/catalog`.
* `<script type="application/json" id="ev-boy-agent-commerce">` with `campaign_id`, product codes and prices, per-product `delivery_codes`, `fulfillment.delivery_options` (code, label, surcharge, such as express `+$80`), `fulfillment.delivery_notes` and `fulfillment.express_delivery_notes` (the delivery-time and express notes shown on the page, verbatim, including the districts without express delivery), `required_customer_fields` and the `agent_checkout` steps below.
* eSIM: `fulfillment.method` is `whatsapp_e_delivery`. After payment, EV-BOY sends an exclusive claim link by WhatsApp; the customer verifies the order phone number and claims the eSIM. Omit `delivery_address` and `delivery_code`; `esim_compatible_confirmed: true` is required.

That block is enough to quote and prepare a checkout; the payable total always comes from `quote`.

# Agent API (agent prepares, customer pays)

JSON uses snake_case. The API never takes payment or card details, sends messages or accepts an agent-supplied price or gift.

1. `GET https://buy.ev-boy.com/api/agent/v1/catalog` lists supported campaigns, product codes, prices, per-product `delivery_codes`, coupon support, gifts and `required_customer_fields`.
2. `POST https://buy.ev-boy.com/api/agent/v1/quote` with `campaign_id`, `product_code`, `delivery_code` and optional `coupon_code` returns `total_hkd`, `gifts` and `payment_methods`. A coupon removes instalment payment.
3. After the customer confirms the product, delivery details and total, `POST https://buy.ev-boy.com/api/agent/v1/checkouts` with an `Idempotency-Key` header (16–128 characters, one per new order), `customer` (`contact_person`, `phone_number`, `email_address`, `delivery_address`), `expected_total_hkd` and `customer_confirmed: true`. eSIM omits delivery fields and adds `esim_compatible_confirmed: true`.
4. The response contains `resume_url`, `checkout_id`, `status_url` and `status_secret`. Give `resume_url` to that customer only; they review the order and choose a payment method themselves.
   * Optional: add `"payment_method": "credit_card"` to also receive `payment_url`, a Stripe-hosted credit-card page for this order (plus `payment_attempt_id`). Open it only after the customer approves the total; the customer enters card details on that page, and the agent never sees card data. `resume_url` stays available for other payment methods. If credit-card payment is not available for the order, the request returns 422 `payment_method_unavailable`; resubmit without `payment_method`. If the page cannot be opened, the order is still created with `payment_notice` and `resume_url`.
   * Other payment methods (PayMe, FPS, instalment and so on) are chosen by the customer on `resume_url`; omit `payment_method` for those.
5. `GET https://buy.ev-boy.com/api/agent/v1/checkouts/{checkout_id}/status` with `Authorization: Bearer {status_secret}` returns `awaiting_customer`, `payment_started`, `paid`, `expired` or `closed`. The status secret cannot open or change the order.

* A total that differs from `expected_total_hkd` returns 409 with the current quote; confirm the new total with the customer and submit with a new `Idempotency-Key`.
* Retrying with the same key and body returns the same checkout; the same key with a different body (including a different `payment_method`) returns 409. A `credit_card` retry within 10 minutes returns the same `payment_url`; later, a new page for the same order.
* Supported: EvChargingCable, GbtType2Adapter, Esim, Ccs2GbtAdapter, Ccs2ChademoAdapter, CarPlayAndroidMediaBox. Use page links for HALOBLK, warranty extension, home-charger installation, UniversalEvChargingCable and V2L.

# Universal Commerce Protocol (UCP)

Profile: `GET https://buy.ev-boy.com/.well-known/ucp` (UCP `2026-08-25`). REST endpoint `https://buy.ev-boy.com/ucp/v1` with `dev.ucp.shopping.checkout`, `dev.ucp.shopping.fulfillment`, `dev.ucp.shopping.discount` and `dev.ucp.shopping.catalog.lookup`. `payment_handlers` is empty. Products, prices, coupons and validation are the agent API's; amounts are HKD minor units (HK$4,780 = `478000`).

* `POST /ucp/v1/catalog/lookup` or `/catalog/product`: product id = `campaign_id`, variant id = product code.
* `POST /ucp/v1/checkout-sessions` (with `Idempotency-Key`): one line item; `buyer`; for physical products one `shipping` method with a Hong Kong destination and `groups[0].selected_option_id` = delivery code; one code in `discounts.codes`. Returns `incomplete` with field messages, or `ready_for_complete`. `GET`/`PUT` read or update it.
* After the customer approves the total, `POST /ucp/v1/checkout-sessions/{id}/complete` (with `Idempotency-Key`) prepares the order and returns `requires_escalation` with `continue_url` (the review link). The customer reviews and chooses a payment method there. A changed total returns `incomplete` with `price_changed`. `GET` shows `completed` after payment.
* `cancel` works before complete; after complete, an unpaid link expires on its own.
* eSIM returns `requires_escalation` with the purchase page as `continue_url`, where the customer confirms eSIM compatibility.
* UCP never takes payment or card data and offers no Google Pay. An uncompleted session lasts up to 6 hours and may need recreating after a site update.

# 電動車專用充電線 (EvChargingCable)

| Product | Code |
|---|---|
| Type 2 中速充電線 - 5米 | `CABLE` |
| Type 2 中速充電線 - 7.5米 | `CABLE75` |
| 英式方腳 13A 電動車充電器 - 10米 | `SOAPBOX` |
| 充電線套裝：中速充電線 7.5米 + 13A 充電器 10米 | `PACKAGE` |
| 充電線延長轉接頭 | `EXTENSION_ADAPTER` |

Example: https://buy.ev-boy.com/Campaigns/EvChargingCable/Purchase?item=PACKAGE

# 港車北上 GB/T 國標充電器轉接頭 (GbtType2Adapter)

| Product | Code |
|---|---|
| AC + DC 轉接頭套裝 v.NEXT-mini | `GBT-Package-Mini` |
| AC + DC 轉接頭套裝 v.NEXT | `GBT-Package` |
| DC 快充轉接頭 v.NEXT-mini | `GBT-CCS2-Mini` |
| DC 快充轉接頭 v.NEXT | `GBT-CCS2` |
| AC 中充轉接頭 | `GBT-Type2` |
| 快充轉接頭更新線（舊版本－使用電腦更新） | `GBT-UpdateCable` |
| 快充轉接頭更新線（新版本－使用手機更新） | `GBT-UpdateCable-V2` |

Example: https://buy.ev-boy.com/Campaigns/GbtType2Adapter/Purchase?item=GBT-Package-Mini

# Other Campaigns

| Campaign | Codes |
|---|---|
| Ccs2GbtAdapter | `Type2-GBT`, `CCS2-GBT`, `CCS2GBT-Package` |
| Ccs2ChademoAdapter | `CCS2-CHAdeMO` |
| UniversalEvChargingCable | `Full-Set`, `Essential-Set`, `Adapter-CEE_3P32A`, `Adapter-CEE_1P32A`, `Adapter-CEE_1P16A` |
| V2L | `V2L-Lite`, `V2L-Pro`, `V2L-Combo` |
| CarPlayAndroidMediaBox | `PRO` |
| EvHomeCharger | `EVBOY-UniversalCharger`, `EVBOY-XP` (installation option and UC plug type are chosen on the purchase page) |

* eSIM: use the 「選購此套餐」 link for each plan on the eSIM product page.
* HALOBLK uses a cart and has no single-product deep link; link to https://buy.ev-boy.com/Campaigns/HALOBLK/

# Do Not Use

Do not treat checkout, payment, internal, resume or webhook URLs as product sources or hand them out as ordering links. The only exceptions are the `resume_url` and `payment_url` the agent API returns, given to the customer they were prepared for.

# Related Concepts

* [電動車專用充電線](../campaigns/ev-charging-cable.md)
* [港車北上 GB/T 國標充電器轉接頭](../campaigns/gbt-type2-adapter.md)
* [Terms and conditions](../policies/terms-and-conditions.md)

# Citations

[1] [電動車專用充電線](https://buy.ev-boy.com/Campaigns/EvChargingCable/)
[2] [港車北上 GB/T 國標充電器轉接頭](https://buy.ev-boy.com/Campaigns/GbtType2Adapter/)