{"openapi":"3.1.0","info":{"title":"HelpVox assisted orders","version":"2026-09-11","summary":"Start a conversation in which a customer places an order, and check what came of it.","description":"place_order starts a HelpVox assisted-order conversation. It does NOT create an order. The customer opens conversation_url, the assistant collects the name, phone and delivery address, reads the order back, and only an explicit confirmation creates it. Until then order_created is false. HelpVox has no cart, no checkout and no payment: payment is on delivery, collected by the merchant, and HelpVox is not the merchant of record.\n\nThis document describes a HelpVox-specific service declared in the merchant's UCP profile under \"ai.helpvox.assisted_order\". It is not part of the UCP shopping service and does not add operations to it. HelpVox implements no create_cart, update_cart, create_checkout, complete_checkout or payment handlers, and declares none.\n\nTwo clocks, and they are not the same one. session_ttl_seconds (720) is how long the customer has to open the signed conversation_url and start talking; it runs from the moment the session is created and opening the page does not extend it. conversation_ttl_seconds (7200) starts when the customer actually starts the conversation, and from then on it is the only one that applies: a live conversation is never cut off because the handoff link aged. Read them from handoff_expires_at and conversation_expires_at, which is why the response carries both instead of one ambiguous expires_at. conversation_expires_at is null until the conversation starts — there is no conversation yet to expire.","contact":{"name":"HelpVox","url":"https://www.helpvox.ai"}},"servers":[{"url":"https://www.helpvox.ai/api/ucp/{storefront}","description":"The service endpoint published in the storefront's UCP profile.","variables":{"storefront":{"default":"storefront_0000000000000000000","description":"The storefront id from /.well-known/ucp on the merchant's domain."}}}],"paths":{"/assisted-orders":{"post":{"operationId":"place_order","summary":"Start an assisted-order conversation (does not create an order)","description":"place_order starts a HelpVox assisted-order conversation. It does NOT create an order. The customer opens conversation_url, the assistant collects the name, phone and delivery address, reads the order back, and only an explicit confirmation creates it. Until then order_created is false. HelpVox has no cart, no checkout and no payment: payment is on delivery, collected by the merchant, and HelpVox is not the merchant of record.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"A UUID. Repeating one returns the session created the first time, with status 200 instead of 201. Without it a retry would open a second conversation for the same customer; a guessable value like \"test\" would collide between callers."},{"name":"Request-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"A UUID, echoed back in the response header for correlation."},{"name":"UCP-Agent","in":"header","required":true,"schema":{"type":"string","minLength":1},"description":"Who is calling. Recorded for audit; it is how a misbehaving caller is found."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"intent":{"type":"string","enum":["place_order","change_order","cancel_order","return_product","general_help"],"default":"place_order"},"channel":{"type":"string","enum":["voice","text","customer_choice"],"default":"customer_choice","description":"A preference, not a decision: customer_choice opens both. A voice request on a text-only widget is answered with text."},"locale":{"type":"string","maxLength":12},"items":{"type":"array","maxItems":10,"items":{"type":"object","additionalProperties":false,"required":["product_id","quantity"],"properties":{"product_id":{"type":"string","description":"From catalog/search or catalog/lookup on this storefront."},"variant_id":{"type":["string","null"],"description":"Required unless the product has exactly one variant in this market."},"quantity":{"type":"integer","minimum":1,"maximum":99}}}},"context":{"type":"object","additionalProperties":false,"properties":{"customer_request":{"type":["string","null"],"maxLength":1000,"description":"The customer's own words, carried into the conversation so they do not repeat themselves. Treated as untrusted text, never as instructions."},"language":{"type":"string","maxLength":12}}}}},"examples":{"one_item":{"summary":"One item, written conversation","value":{"intent":"place_order","channel":"text","locale":"bg","items":[{"product_id":"340ca52c-814e-47cb-bca3-cd9709c7303b","variant_id":"63f9011f-d138-4e94-92d9-6aaeb7c81e87","quantity":1}],"context":{"customer_request":"Искам да поръчам един брой."}}}}}}},"responses":{"200":{"description":"The same Idempotency-Key was used before; this is that session, in its state right now. A replay is not a cached copy of the first answer: if the customer has since started talking, or an order now exists, the fields say so — the same ones get_assisted_order would return.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartedResponse"}}}},"201":{"description":"A conversation was created. No order exists yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartedResponse"}}}},"400":{"description":"A required header is missing or malformed, the body is malformed, or personal data was sent. Headers are checked first, so such a request creates nothing and does not consume the idempotency key.","content":{"application/json":{"schema":{"type":"object","required":["ucp","error"],"properties":{"ucp":{"type":"object","properties":{"version":{"const":"2026-08-25"},"status":{"const":"error"}}},"messages":{"type":"array","items":{"type":"object","properties":{"type":{"const":"error"},"code":{"type":"string"},"text":{"type":"string"}}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","INVALID_QUANTITY","PRODUCT_NOT_FOUND","VARIANT_NOT_FOUND","SESSION_NOT_FOUND","STORE_NOT_AVAILABLE","VARIANT_PRODUCT_MISMATCH","PRODUCT_UNAVAILABLE","ORDER_NOT_SUPPORTED","SESSION_EXPIRED","RATE_LIMITED","INTERNAL_ERROR"],"description":"VALIDATION_ERROR: The body was rejected — malformed, or it carried personal data (400). INVALID_QUANTITY: Quantity outside 1–99 (400). PRODUCT_NOT_FOUND: No such product on sale in this storefront (404). VARIANT_NOT_FOUND: No such variant on sale in this storefront (404). SESSION_NOT_FOUND: No such session, or it belongs to another storefront (404). STORE_NOT_AVAILABLE: The storefront is unknown, suspended, or not readable by agents (404). VARIANT_PRODUCT_MISMATCH: The variant exists but belongs to a different product (409). PRODUCT_UNAVAILABLE: Out of stock, or not enough of it (409). ORDER_NOT_SUPPORTED: This storefront sells nothing in that market (409). SESSION_EXPIRED: The handoff link has expired; start a new one (410). RATE_LIMITED: Too many requests (429). INTERNAL_ERROR: Something failed on our side (500)."},"message":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":["object","null"]}}},"assisted_order":{"type":"null"}}}}}},"404":{"description":"Unknown storefront, product or variant.","content":{"application/json":{"schema":{"type":"object","required":["ucp","error"],"properties":{"ucp":{"type":"object","properties":{"version":{"const":"2026-08-25"},"status":{"const":"error"}}},"messages":{"type":"array","items":{"type":"object","properties":{"type":{"const":"error"},"code":{"type":"string"},"text":{"type":"string"}}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","INVALID_QUANTITY","PRODUCT_NOT_FOUND","VARIANT_NOT_FOUND","SESSION_NOT_FOUND","STORE_NOT_AVAILABLE","VARIANT_PRODUCT_MISMATCH","PRODUCT_UNAVAILABLE","ORDER_NOT_SUPPORTED","SESSION_EXPIRED","RATE_LIMITED","INTERNAL_ERROR"],"description":"VALIDATION_ERROR: The body was rejected — malformed, or it carried personal data (400). INVALID_QUANTITY: Quantity outside 1–99 (400). PRODUCT_NOT_FOUND: No such product on sale in this storefront (404). VARIANT_NOT_FOUND: No such variant on sale in this storefront (404). SESSION_NOT_FOUND: No such session, or it belongs to another storefront (404). STORE_NOT_AVAILABLE: The storefront is unknown, suspended, or not readable by agents (404). VARIANT_PRODUCT_MISMATCH: The variant exists but belongs to a different product (409). PRODUCT_UNAVAILABLE: Out of stock, or not enough of it (409). ORDER_NOT_SUPPORTED: This storefront sells nothing in that market (409). SESSION_EXPIRED: The handoff link has expired; start a new one (410). RATE_LIMITED: Too many requests (429). INTERNAL_ERROR: Something failed on our side (500)."},"message":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":["object","null"]}}},"assisted_order":{"type":"null"}}}}}},"409":{"description":"Variant/product mismatch, unavailable item, or nothing on sale.","content":{"application/json":{"schema":{"type":"object","required":["ucp","error"],"properties":{"ucp":{"type":"object","properties":{"version":{"const":"2026-08-25"},"status":{"const":"error"}}},"messages":{"type":"array","items":{"type":"object","properties":{"type":{"const":"error"},"code":{"type":"string"},"text":{"type":"string"}}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","INVALID_QUANTITY","PRODUCT_NOT_FOUND","VARIANT_NOT_FOUND","SESSION_NOT_FOUND","STORE_NOT_AVAILABLE","VARIANT_PRODUCT_MISMATCH","PRODUCT_UNAVAILABLE","ORDER_NOT_SUPPORTED","SESSION_EXPIRED","RATE_LIMITED","INTERNAL_ERROR"],"description":"VALIDATION_ERROR: The body was rejected — malformed, or it carried personal data (400). INVALID_QUANTITY: Quantity outside 1–99 (400). PRODUCT_NOT_FOUND: No such product on sale in this storefront (404). VARIANT_NOT_FOUND: No such variant on sale in this storefront (404). SESSION_NOT_FOUND: No such session, or it belongs to another storefront (404). STORE_NOT_AVAILABLE: The storefront is unknown, suspended, or not readable by agents (404). VARIANT_PRODUCT_MISMATCH: The variant exists but belongs to a different product (409). PRODUCT_UNAVAILABLE: Out of stock, or not enough of it (409). ORDER_NOT_SUPPORTED: This storefront sells nothing in that market (409). SESSION_EXPIRED: The handoff link has expired; start a new one (410). RATE_LIMITED: Too many requests (429). INTERNAL_ERROR: Something failed on our side (500)."},"message":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":["object","null"]}}},"assisted_order":{"type":"null"}}}}}},"410":{"description":"Replay of a key whose session has expired. The link is dead, so it is not handed back; start again with a new key.","content":{"application/json":{"schema":{"type":"object","required":["ucp","error"],"properties":{"ucp":{"type":"object","properties":{"version":{"const":"2026-08-25"},"status":{"const":"error"}}},"messages":{"type":"array","items":{"type":"object","properties":{"type":{"const":"error"},"code":{"type":"string"},"text":{"type":"string"}}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","INVALID_QUANTITY","PRODUCT_NOT_FOUND","VARIANT_NOT_FOUND","SESSION_NOT_FOUND","STORE_NOT_AVAILABLE","VARIANT_PRODUCT_MISMATCH","PRODUCT_UNAVAILABLE","ORDER_NOT_SUPPORTED","SESSION_EXPIRED","RATE_LIMITED","INTERNAL_ERROR"],"description":"VALIDATION_ERROR: The body was rejected — malformed, or it carried personal data (400). INVALID_QUANTITY: Quantity outside 1–99 (400). PRODUCT_NOT_FOUND: No such product on sale in this storefront (404). VARIANT_NOT_FOUND: No such variant on sale in this storefront (404). SESSION_NOT_FOUND: No such session, or it belongs to another storefront (404). STORE_NOT_AVAILABLE: The storefront is unknown, suspended, or not readable by agents (404). VARIANT_PRODUCT_MISMATCH: The variant exists but belongs to a different product (409). PRODUCT_UNAVAILABLE: Out of stock, or not enough of it (409). ORDER_NOT_SUPPORTED: This storefront sells nothing in that market (409). SESSION_EXPIRED: The handoff link has expired; start a new one (410). RATE_LIMITED: Too many requests (429). INTERNAL_ERROR: Something failed on our side (500)."},"message":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":["object","null"]}}},"assisted_order":{"type":"null"}}}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"type":"object","required":["ucp","error"],"properties":{"ucp":{"type":"object","properties":{"version":{"const":"2026-08-25"},"status":{"const":"error"}}},"messages":{"type":"array","items":{"type":"object","properties":{"type":{"const":"error"},"code":{"type":"string"},"text":{"type":"string"}}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","INVALID_QUANTITY","PRODUCT_NOT_FOUND","VARIANT_NOT_FOUND","SESSION_NOT_FOUND","STORE_NOT_AVAILABLE","VARIANT_PRODUCT_MISMATCH","PRODUCT_UNAVAILABLE","ORDER_NOT_SUPPORTED","SESSION_EXPIRED","RATE_LIMITED","INTERNAL_ERROR"],"description":"VALIDATION_ERROR: The body was rejected — malformed, or it carried personal data (400). INVALID_QUANTITY: Quantity outside 1–99 (400). PRODUCT_NOT_FOUND: No such product on sale in this storefront (404). VARIANT_NOT_FOUND: No such variant on sale in this storefront (404). SESSION_NOT_FOUND: No such session, or it belongs to another storefront (404). STORE_NOT_AVAILABLE: The storefront is unknown, suspended, or not readable by agents (404). VARIANT_PRODUCT_MISMATCH: The variant exists but belongs to a different product (409). PRODUCT_UNAVAILABLE: Out of stock, or not enough of it (409). ORDER_NOT_SUPPORTED: This storefront sells nothing in that market (409). SESSION_EXPIRED: The handoff link has expired; start a new one (410). RATE_LIMITED: Too many requests (429). INTERNAL_ERROR: Something failed on our side (500)."},"message":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":["object","null"]}}},"assisted_order":{"type":"null"}}}}}}}},"options":{"operationId":"place_order_preflight","summary":"CORS preflight","responses":{"204":{"description":"Allowed methods and headers."}}}},"/assisted-orders/{session_id}":{"get":{"operationId":"get_assisted_order","summary":"The authoritative state of an assisted-order conversation","description":"Whether an order exists is read from the order records at the moment of asking, not from a remembered claim. order_created is true only with a real order, and order_id is then the number the customer heard in the conversation.","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","pattern":"^hv_[0-9a-f]{32}$"}},{"name":"Request-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"A UUID, echoed back for correlation."},{"name":"UCP-Agent","in":"header","required":true,"schema":{"type":"string","minLength":1},"description":"Who is calling; recorded for audit."}],"responses":{"200":{"description":"Current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"400":{"description":"Request-Id or UCP-Agent is missing or malformed.","content":{"application/json":{"schema":{"type":"object","required":["ucp","error"],"properties":{"ucp":{"type":"object","properties":{"version":{"const":"2026-08-25"},"status":{"const":"error"}}},"messages":{"type":"array","items":{"type":"object","properties":{"type":{"const":"error"},"code":{"type":"string"},"text":{"type":"string"}}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","INVALID_QUANTITY","PRODUCT_NOT_FOUND","VARIANT_NOT_FOUND","SESSION_NOT_FOUND","STORE_NOT_AVAILABLE","VARIANT_PRODUCT_MISMATCH","PRODUCT_UNAVAILABLE","ORDER_NOT_SUPPORTED","SESSION_EXPIRED","RATE_LIMITED","INTERNAL_ERROR"],"description":"VALIDATION_ERROR: The body was rejected — malformed, or it carried personal data (400). INVALID_QUANTITY: Quantity outside 1–99 (400). PRODUCT_NOT_FOUND: No such product on sale in this storefront (404). VARIANT_NOT_FOUND: No such variant on sale in this storefront (404). SESSION_NOT_FOUND: No such session, or it belongs to another storefront (404). STORE_NOT_AVAILABLE: The storefront is unknown, suspended, or not readable by agents (404). VARIANT_PRODUCT_MISMATCH: The variant exists but belongs to a different product (409). PRODUCT_UNAVAILABLE: Out of stock, or not enough of it (409). ORDER_NOT_SUPPORTED: This storefront sells nothing in that market (409). SESSION_EXPIRED: The handoff link has expired; start a new one (410). RATE_LIMITED: Too many requests (429). INTERNAL_ERROR: Something failed on our side (500)."},"message":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":["object","null"]}}},"assisted_order":{"type":"null"}}}}}},"404":{"description":"No such session in this storefront.","content":{"application/json":{"schema":{"type":"object","required":["ucp","error"],"properties":{"ucp":{"type":"object","properties":{"version":{"const":"2026-08-25"},"status":{"const":"error"}}},"messages":{"type":"array","items":{"type":"object","properties":{"type":{"const":"error"},"code":{"type":"string"},"text":{"type":"string"}}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","INVALID_QUANTITY","PRODUCT_NOT_FOUND","VARIANT_NOT_FOUND","SESSION_NOT_FOUND","STORE_NOT_AVAILABLE","VARIANT_PRODUCT_MISMATCH","PRODUCT_UNAVAILABLE","ORDER_NOT_SUPPORTED","SESSION_EXPIRED","RATE_LIMITED","INTERNAL_ERROR"],"description":"VALIDATION_ERROR: The body was rejected — malformed, or it carried personal data (400). INVALID_QUANTITY: Quantity outside 1–99 (400). PRODUCT_NOT_FOUND: No such product on sale in this storefront (404). VARIANT_NOT_FOUND: No such variant on sale in this storefront (404). SESSION_NOT_FOUND: No such session, or it belongs to another storefront (404). STORE_NOT_AVAILABLE: The storefront is unknown, suspended, or not readable by agents (404). VARIANT_PRODUCT_MISMATCH: The variant exists but belongs to a different product (409). PRODUCT_UNAVAILABLE: Out of stock, or not enough of it (409). ORDER_NOT_SUPPORTED: This storefront sells nothing in that market (409). SESSION_EXPIRED: The handoff link has expired; start a new one (410). RATE_LIMITED: Too many requests (429). INTERNAL_ERROR: Something failed on our side (500)."},"message":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":["object","null"]}}},"assisted_order":{"type":"null"}}}}}},"410":{"description":"The session expired without an order — either the link was never opened within session_ttl_seconds, or the conversation itself outlived conversation_ttl_seconds. The error details carry both handoff_expires_at and conversation_expires_at so you can tell which.","content":{"application/json":{"schema":{"type":"object","required":["ucp","error"],"properties":{"ucp":{"type":"object","properties":{"version":{"const":"2026-08-25"},"status":{"const":"error"}}},"messages":{"type":"array","items":{"type":"object","properties":{"type":{"const":"error"},"code":{"type":"string"},"text":{"type":"string"}}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","INVALID_QUANTITY","PRODUCT_NOT_FOUND","VARIANT_NOT_FOUND","SESSION_NOT_FOUND","STORE_NOT_AVAILABLE","VARIANT_PRODUCT_MISMATCH","PRODUCT_UNAVAILABLE","ORDER_NOT_SUPPORTED","SESSION_EXPIRED","RATE_LIMITED","INTERNAL_ERROR"],"description":"VALIDATION_ERROR: The body was rejected — malformed, or it carried personal data (400). INVALID_QUANTITY: Quantity outside 1–99 (400). PRODUCT_NOT_FOUND: No such product on sale in this storefront (404). VARIANT_NOT_FOUND: No such variant on sale in this storefront (404). SESSION_NOT_FOUND: No such session, or it belongs to another storefront (404). STORE_NOT_AVAILABLE: The storefront is unknown, suspended, or not readable by agents (404). VARIANT_PRODUCT_MISMATCH: The variant exists but belongs to a different product (409). PRODUCT_UNAVAILABLE: Out of stock, or not enough of it (409). ORDER_NOT_SUPPORTED: This storefront sells nothing in that market (409). SESSION_EXPIRED: The handoff link has expired; start a new one (410). RATE_LIMITED: Too many requests (429). INTERNAL_ERROR: Something failed on our side (500)."},"message":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":["object","null"]}}},"assisted_order":{"type":"null"}}}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"type":"object","required":["ucp","error"],"properties":{"ucp":{"type":"object","properties":{"version":{"const":"2026-08-25"},"status":{"const":"error"}}},"messages":{"type":"array","items":{"type":"object","properties":{"type":{"const":"error"},"code":{"type":"string"},"text":{"type":"string"}}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","INVALID_QUANTITY","PRODUCT_NOT_FOUND","VARIANT_NOT_FOUND","SESSION_NOT_FOUND","STORE_NOT_AVAILABLE","VARIANT_PRODUCT_MISMATCH","PRODUCT_UNAVAILABLE","ORDER_NOT_SUPPORTED","SESSION_EXPIRED","RATE_LIMITED","INTERNAL_ERROR"],"description":"VALIDATION_ERROR: The body was rejected — malformed, or it carried personal data (400). INVALID_QUANTITY: Quantity outside 1–99 (400). PRODUCT_NOT_FOUND: No such product on sale in this storefront (404). VARIANT_NOT_FOUND: No such variant on sale in this storefront (404). SESSION_NOT_FOUND: No such session, or it belongs to another storefront (404). STORE_NOT_AVAILABLE: The storefront is unknown, suspended, or not readable by agents (404). VARIANT_PRODUCT_MISMATCH: The variant exists but belongs to a different product (409). PRODUCT_UNAVAILABLE: Out of stock, or not enough of it (409). ORDER_NOT_SUPPORTED: This storefront sells nothing in that market (409). SESSION_EXPIRED: The handoff link has expired; start a new one (410). RATE_LIMITED: Too many requests (429). INTERNAL_ERROR: Something failed on our side (500)."},"message":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":["object","null"]}}},"assisted_order":{"type":"null"}}}}}}}},"options":{"operationId":"get_assisted_order_preflight","summary":"CORS preflight","responses":{"204":{"description":"Allowed methods and headers."}}}}},"components":{"schemas":{"AssistedOrder":{"type":"object","required":["session_id","status","order_created","handoff_expires_at"],"properties":{"session_id":{"type":"string","pattern":"^hv_[0-9a-f]{32}$"},"status":{"type":"string","enum":["requires_interaction","conversation_started","collecting_customer_data","awaiting_confirmation","processing","completed","cancelled","expired","failed"]},"intent":{"type":"string"},"channel":{"type":"string","enum":["voice","text","customer_choice"]},"items_transferred":{"type":"integer"},"order_created":{"type":"boolean","description":"False until a real order record exists."},"order_id":{"type":["string","null"],"description":"The merchant-facing order number. Never generated."},"confirmed_at":{"type":["string","null"],"format":"date-time"},"next_action":{"type":["string","null"]},"handoff_expires_at":{"type":"string","format":"date-time","description":"When the signed conversation_url stops working. Until the customer starts talking, this is also when the session expires. Opening the page does not extend it. After the conversation has started it no longer governs anything: an expired link does not end a conversation in progress."},"conversation_expires_at":{"type":["string","null"],"format":"date-time","description":"When the conversation itself expires, counted from the moment the customer actually started it. Null while status is requires_interaction: there is no conversation yet. Once set, this is the only deadline that applies."}}},"StartedResponse":{"type":"object","required":["ucp","assisted_order"],"description":"The session's current state — the same fields get_assisted_order returns — plus the addresses that only starting has to hand out.","properties":{"ucp":{"type":"object","properties":{"version":{"const":"2026-08-25"},"status":{"const":"success"}}},"assisted_order":{"allOf":[{"$ref":"#/components/schemas/AssistedOrder"}],"type":"object","properties":{"conversation_url":{"type":"string","format":"uri","description":"Give this to the customer. It carries a short-lived signed token and no personal data. It opens the HelpVox assistant with the items already in it."},"entry_url":{"type":["string","null"],"description":"The merchant's own site, when known."},"status_url":{"type":"string","format":"uri"},"payment":{"type":"object","properties":{"collected_by":{"const":"merchant_on_delivery"},"processed_by_helpvox":{"const":false}}}}}}},"StatusResponse":{"type":"object","required":["ucp","assisted_order"],"properties":{"ucp":{"type":"object","properties":{"version":{"const":"2026-08-25"},"status":{"const":"success"}}},"assisted_order":{"$ref":"#/components/schemas/AssistedOrder"}}},"Error":{"type":"object","required":["ucp","error"],"properties":{"ucp":{"type":"object","properties":{"version":{"const":"2026-08-25"},"status":{"const":"error"}}},"messages":{"type":"array","items":{"type":"object","properties":{"type":{"const":"error"},"code":{"type":"string"},"text":{"type":"string"}}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","INVALID_QUANTITY","PRODUCT_NOT_FOUND","VARIANT_NOT_FOUND","SESSION_NOT_FOUND","STORE_NOT_AVAILABLE","VARIANT_PRODUCT_MISMATCH","PRODUCT_UNAVAILABLE","ORDER_NOT_SUPPORTED","SESSION_EXPIRED","RATE_LIMITED","INTERNAL_ERROR"],"description":"VALIDATION_ERROR: The body was rejected — malformed, or it carried personal data (400). INVALID_QUANTITY: Quantity outside 1–99 (400). PRODUCT_NOT_FOUND: No such product on sale in this storefront (404). VARIANT_NOT_FOUND: No such variant on sale in this storefront (404). SESSION_NOT_FOUND: No such session, or it belongs to another storefront (404). STORE_NOT_AVAILABLE: The storefront is unknown, suspended, or not readable by agents (404). VARIANT_PRODUCT_MISMATCH: The variant exists but belongs to a different product (409). PRODUCT_UNAVAILABLE: Out of stock, or not enough of it (409). ORDER_NOT_SUPPORTED: This storefront sells nothing in that market (409). SESSION_EXPIRED: The handoff link has expired; start a new one (410). RATE_LIMITED: Too many requests (429). INTERNAL_ERROR: Something failed on our side (500)."},"message":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":["object","null"]}}},"assisted_order":{"type":"null"}}}}}}