quick_buy
ActiveTool of Kifly — Agentic Commerce & Payments
Requires `cart:write` scope. Create a cart, add items, and set the shipping address in ONE call — the fast path when you already know the seller, the exact variant(s), and the buyer's address (e.g. a reorder, or a buyer who has decided). Prefer this over the create_cart → add_to_cart → set_shipping_address sequence to save round trips; those granular tools stay available for exploratory, multi-step carts. **You must call `search_products` first** so Kifly knows each variant's seller (quick_buy returns 422 `VARIANT_SNAPSHOT_MISSING` otherwise). One cart = one seller: every item must belong to the same seller (409 `CART_SELLER_MISMATCH` otherwise) — for a network token, pass that seller's `seller_handle`. Returns `{ cart_id, items_added, seller, delivery }`. `delivery` is exactly what set_shipping_address returns: when `delivery_eligible: true` it carries `cart_total_with_delivery_cents` (quote it before sending the buyer to pay); when `false` it carries `reason` + `delivery_coverage` and NO address is saved, so you can call quick_buy again (or set_shipping_address) with a covered address on info you already have. **quick_buy never charges — it stops at the cart. The buyer still pays via `checkout`**, which returns the payment link they open themselves. On a 5xx/'temporarily unavailable' error, retry once with the same arguments.
Parameters schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"items",
"shipping_address"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"variant_id",
"quantity"
],
"properties": {
"quantity": {
"type": "integer",
"minimum": 1,
"description": "Quantity to add"
},
"variant_id": {
"type": "string",
"minLength": 1,
"description": "Product variant ID from search_products results"
},
"measure_amount": {
"type": "number",
"description": "Sold-by-measure amount (e.g. 0.4 oz) for variants priced by measure; omit for fixed-price variants",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"maxItems": 50,
"minItems": 1,
"description": "Line items to add — all must belong to the same seller"
},
"seller_handle": {
"type": "string",
"pattern": "^[a-z0-9-]+$",
"maxLength": 40,
"minLength": 3,
"description": "Seller handle from search_products. REQUIRED for network tokens; omit for seller-scoped tokens (their own seller is implicit)."
},
"shipping_address": {
"type": "object",
"required": [
"name",
"line1",
"city",
"region",
"postal_code"
],
"properties": {
"city": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"name": {
"type": "string",
"maxLength": 150,
"minLength": 1,
"description": "Buyer's full name"
},
"line1": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Street address line 1"
},
"line2": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
],
"description": "Street address line 2 (apt, suite)"
},
"phone": {
"anyOf": [
{
"type": "string",
"maxLength": 30
},
{
"type": "null"
}
],
"description": "Optional contact phone for delivery"
},
"region": {
"type": "string",
"maxLength": 50,
"minLength": 1,
"description": "US state code (e.g. 'CA', 'NE') — matched against seller's delivery_coverage.states"
},
"country": {
"type": "string",
"default": "US",
"maxLength": 2,
"minLength": 2,
"description": "ISO 3166-1 alpha-2 country code"
},
"postal_code": {
"type": "string",
"maxLength": 20,
"minLength": 3,
"description": "Postal/ZIP code"
}
},
"description": "Structured shipping address collected conversationally from the buyer",
"additionalProperties": false
},
"external_customer_ref": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "Embedded-commerce pass-through: the seller's own opaque customer id for a cart from their embed widget. Omit unless you are the embed flow."
}
},
"additionalProperties": false
}Parent server
Kifly — Agentic Commerce & Payments
1/7 registries