Confirm a checkout intent
The shopper’s approval. Send the confirmation_token with the shopper’s credential, or — for a guest —
with contact (email and name).
The basket is re-priced first. If anything the shopper pays has changed — a line price, the discount,
shipping, tax or the total — the response is 409 quote_changed with the new quote in error.details,
and nothing is placed; show the shopper the new figures and create a new intent. When the intent holds no
stock and an item is no longer available in the quantity quoted, the response is 409 out_of_stock;
nothing is placed or charged and the intent stays pending. Otherwise the order is
placed with payment pending, using the held stock, and the response carries what
POST /v1/payments/initialize needs to take payment, plus the store’s payment methods.
The token is single use: a second confirmation returns 409 intent_not_pending. A wrong token returns
403 invalid_confirmation_token and discloses nothing about the intent.
Guest confirmations ask for a code. Unless the merchant has turned the setting off, a confirmation with
no shopper credential and an intent that was not prepared for a signed-in shopper is completed only with a
six-digit code emailed to contact.email. The first call sends the code and answers
409 person_proof_required (the address it went to is masked in error.details.sent_to; the code is valid
for 15 minutes); send the same request again with the code as person_proof. A wrong code returns
403 invalid_person_proof (five tries per code, then 429 too_many_attempts); at most five codes are sent
per intent (429 too_many_codes). A different contact.email than the code went to starts a new code.
Confirming with the shopper’s credential never asks for a code.
With a marketplace operator key contact.email and contact.name are always required, and a
shopper credential (x-auth-token or x-external-auth), when sent, is recorded on the purchase. The
guest code applies to a marketplace key as well: a confirmation with no shopper credential answers
409 person_proof_required and is completed with the emailed code, unless the marketplace operator has
turned the guest check off (it is on by default and is the operator’s setting, not the caller’s). The
basket is re-priced through the marketplace checkout; a change returns 409 quote_changed, and a seller
that has run out returns 409 items_unavailable. Otherwise one marketplace order is placed across the
sellers, each seller’s stock is held for the payment window, and the response carries order_group and
a single payment whose client_secret the storefront confirms with the payment provider’s own card form.
Once paid, every seller receives their own order, marked as placed through a shopping assistant.
curl --request POST \
--url https://api.tybritelabs.com/v1/agent/checkout-intents/{id}/confirm \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"confirmation_token": "Vq3yJ9mXo1bT0c8r2Hk5uW7eZ4sA6dLfN1pG8iQ3xYk",
"contact": {
"email": "john.doe@example.com",
"name": "John Doe"
}
}
'import requests
url = "https://api.tybritelabs.com/v1/agent/checkout-intents/{id}/confirm"
payload = {
"confirmation_token": "Vq3yJ9mXo1bT0c8r2Hk5uW7eZ4sA6dLfN1pG8iQ3xYk",
"contact": {
"email": "john.doe@example.com",
"name": "John Doe"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
confirmation_token: 'Vq3yJ9mXo1bT0c8r2Hk5uW7eZ4sA6dLfN1pG8iQ3xYk',
contact: {email: 'john.doe@example.com', name: 'John Doe'}
})
};
fetch('https://api.tybritelabs.com/v1/agent/checkout-intents/{id}/confirm', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tybritelabs.com/v1/agent/checkout-intents/{id}/confirm",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'confirmation_token' => 'Vq3yJ9mXo1bT0c8r2Hk5uW7eZ4sA6dLfN1pG8iQ3xYk',
'contact' => [
'email' => 'john.doe@example.com',
'name' => 'John Doe'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tybritelabs.com/v1/agent/checkout-intents/{id}/confirm"
payload := strings.NewReader("{\n \"confirmation_token\": \"Vq3yJ9mXo1bT0c8r2Hk5uW7eZ4sA6dLfN1pG8iQ3xYk\",\n \"contact\": {\n \"email\": \"john.doe@example.com\",\n \"name\": \"John Doe\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/agent/checkout-intents/{id}/confirm")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"confirmation_token\": \"Vq3yJ9mXo1bT0c8r2Hk5uW7eZ4sA6dLfN1pG8iQ3xYk\",\n \"contact\": {\n \"email\": \"john.doe@example.com\",\n \"name\": \"John Doe\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tybritelabs.com/v1/agent/checkout-intents/{id}/confirm")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"confirmation_token\": \"Vq3yJ9mXo1bT0c8r2Hk5uW7eZ4sA6dLfN1pG8iQ3xYk\",\n \"contact\": {\n \"email\": \"john.doe@example.com\",\n \"name\": \"John Doe\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"intent": {
"id": "a3a10e58-c5e2-406d-b054-0b8d782e9300",
"status": "confirmed",
"confirmation_mode": "token",
"expires_at": "2026-10-01T11:02:09.366+00:00",
"order_id": "e9b398b5-40d9-476d-bae6-efc401861190",
"customer_id": null,
"total": 63,
"currency": "EUR",
"items": [
{
"quantity": 1,
"variant_id": "fbe89cdf-90a3-4050-a43b-e4c42302484a"
}
],
"quote": {
"tax": {
"amount": 8.69,
"source": "fallback",
"status": "quoted",
"prices_include_tax": true
},
"lines": [
{
"sku": "FEED-HOODIE-GRY-M",
"name": "Galactic Zip Hoodie",
"stock": 25,
"quantity": 1,
"available": true,
"line_total": 48,
"list_price": 48,
"product_id": "289533e8-f5b6-4d4f-bb23-2127875feb70",
"unit_price": 48,
"variant_id": "fbe89cdf-90a3-4050-a43b-e4c42302484a",
"variant_name": "Grey / M",
"category_name": "Wearables",
"unavailable_reason": null
}
],
"currency": "EUR",
"discount": {
"amount": 0,
"promotion": null
},
"shipping": {
"amount": 15,
"status": "quoted",
"is_free": false,
"description": "USA",
"free_threshold": 100
},
"subtotal": 48,
"grand_total": 63,
"total_is_final": true,
"shipping_address": {
"city": "New York",
"name": "John Doe",
"line1": "350 Fifth Avenue",
"state": "NY",
"country": "US",
"postal_code": "10118"
},
"unavailable_count": 0
},
"created_at": "2026-10-01T10:32:09.391151+00:00",
"confirmed_at": "2026-10-01T10:32:12.476+00:00",
"cancelled_at": null
},
"order": {
"id": "e9b398b5-40d9-476d-bae6-efc401861190",
"order_number": "ORD-1790850732602",
"total_amount": 63,
"currency": "EUR",
"payment_status": "pending",
"order_status": "pending"
},
"payment": {
"next_step": "POST /v1/payments/initialize",
"initialize_body": {
"order_id": "e9b398b5-40d9-476d-bae6-efc401861190",
"amount": 63,
"currency": "EUR",
"email": "john.doe@example.com"
},
"methods": [
{
"provider": "cash",
"display_name": "Cash on Delivery",
"type": "manual",
"environment": "production",
"is_configured": true
},
{
"provider": "stripe",
"display_name": "Stripe",
"type": "redirect",
"environment": "test",
"is_configured": true
},
{
"provider": "paypal",
"display_name": "PayPal",
"type": "popup",
"environment": "sandbox",
"is_configured": true
},
{
"provider": "paystack",
"display_name": "Paystack",
"type": "popup",
"environment": "test",
"is_configured": true
}
]
}
},
"evidence": [
{
"source": "pricing",
"operation": "GET /v1/prices/products/{id}",
"id": "fbe89cdf-90a3-4050-a43b-e4c42302484a",
"field": "resolved_price"
},
{
"source": "promotions",
"operation": "POST /v1/promotions/calculate-best",
"field": "discount"
},
{
"source": "shipping",
"operation": "shipping quote",
"field": "fee"
},
{
"source": "tax",
"operation": "POST /v1/tax/preview",
"field": "tax_amount"
},
{
"source": "orders",
"operation": "order create",
"id": "e9b398b5-40d9-476d-bae6-efc401861190",
"field": "total_amount"
},
{
"source": "payments",
"operation": "GET /v1/payments/methods",
"field": "methods"
}
],
"computed_at": "2026-10-01T10:32:13.845Z",
"currency": "EUR",
"environment": "sandbox"
}Authorizations
API Key Authentication
Use your API key in the Authorization header:
Authorization: Bearer tybrite_sk_live_YOUR_KEY
Key Types:
Secret Keys (Server-Side Only):
- Format:
tybrite_sk_live_*(production) ortybrite_sk_test_*(sandbox) - Full read/write access to all endpoints
- ⚠️ NEVER expose in client-side code or public repositories
- Required for: every write a shopper does not make for themselves, authentication, payment verification, AI recommendations
Publishable Keys (Client-Safe):
- Format:
tybrite_pk_live_*(production) ortybrite_pk_test_*(sandbox) - Catalogue reads, plus the actions a shopper takes for themselves
- ✅ Safe for client-side JavaScript, mobile apps, and public code
- Allowed for: browsing products, search, CMS content, pricing queries, cart and wishlist, reviews, storefront events, and the Agent API's quotes, cart drafts and checkout intents
Endpoint-Specific Requirements:
- Authentication endpoints (
/v1/auth/*): state-changingPOSTcalls require a secret key, for store and marketplace keys alike;GET /v1/auth/meaccepts either key - Payment verification (
POST /v1/payments/verify): Secret key required - AI Recommendations (
POST /v1/recommendations): Secret key required - Semantic Search (
POST /v1/search): Both key types allowed (read-only operation) - Shopper actions (cart, wishlist, reviews, storefront events, Agent API quotes, cart drafts and checkout intents): Both key types allowed
- All other write operations: Secret key required
- All read operations: Both key types allowed
Using a publishable key for restricted operations returns 403 Forbidden.
Limited publishable keys:
A publishable key can be limited to the products that carry one tag (for example starter:jewellery), created from
the store's Developers page. The limit applies to the key, never to the shopper: shopper sign-up and sign-in stay store-wide.
- Reads return only the slice: products (with their facets, filters, search, brands and specifications), categories and
subcategories that hold in-slice products, collections, promotions, posts and lookbooks that carry the tag, reviews of
in-slice products, prices, discovery lists and the store information summary, with every count computed on the slice.
A product outside the slice answers
404, as if it did not exist. - A write that names a product or variant outside the slice (adding to the cart or wishlist, reserving stock, an order line,
a review, a promotion calculation, a storefront event) answers
403with the error codeout_of_scope, and nothing is written or reserved. An order is refused as a whole. - A route that carries no slice behaviour is not available to the key: it answers
403withendpoint_not_allowed. - Orders placed through such a key record the tag on the order's attribution as
key_scope. - Secret keys and connected-app keys cannot be limited.
- Responses are cached per key limit: a limited key never receives a response cached for the whole store, and the reverse.
Headers
Body
Response
The order, placed with payment pending
curl --request POST \
--url https://api.tybritelabs.com/v1/agent/checkout-intents/{id}/confirm \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"confirmation_token": "Vq3yJ9mXo1bT0c8r2Hk5uW7eZ4sA6dLfN1pG8iQ3xYk",
"contact": {
"email": "john.doe@example.com",
"name": "John Doe"
}
}
'import requests
url = "https://api.tybritelabs.com/v1/agent/checkout-intents/{id}/confirm"
payload = {
"confirmation_token": "Vq3yJ9mXo1bT0c8r2Hk5uW7eZ4sA6dLfN1pG8iQ3xYk",
"contact": {
"email": "john.doe@example.com",
"name": "John Doe"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
confirmation_token: 'Vq3yJ9mXo1bT0c8r2Hk5uW7eZ4sA6dLfN1pG8iQ3xYk',
contact: {email: 'john.doe@example.com', name: 'John Doe'}
})
};
fetch('https://api.tybritelabs.com/v1/agent/checkout-intents/{id}/confirm', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tybritelabs.com/v1/agent/checkout-intents/{id}/confirm",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'confirmation_token' => 'Vq3yJ9mXo1bT0c8r2Hk5uW7eZ4sA6dLfN1pG8iQ3xYk',
'contact' => [
'email' => 'john.doe@example.com',
'name' => 'John Doe'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tybritelabs.com/v1/agent/checkout-intents/{id}/confirm"
payload := strings.NewReader("{\n \"confirmation_token\": \"Vq3yJ9mXo1bT0c8r2Hk5uW7eZ4sA6dLfN1pG8iQ3xYk\",\n \"contact\": {\n \"email\": \"john.doe@example.com\",\n \"name\": \"John Doe\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/agent/checkout-intents/{id}/confirm")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"confirmation_token\": \"Vq3yJ9mXo1bT0c8r2Hk5uW7eZ4sA6dLfN1pG8iQ3xYk\",\n \"contact\": {\n \"email\": \"john.doe@example.com\",\n \"name\": \"John Doe\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tybritelabs.com/v1/agent/checkout-intents/{id}/confirm")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"confirmation_token\": \"Vq3yJ9mXo1bT0c8r2Hk5uW7eZ4sA6dLfN1pG8iQ3xYk\",\n \"contact\": {\n \"email\": \"john.doe@example.com\",\n \"name\": \"John Doe\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"intent": {
"id": "a3a10e58-c5e2-406d-b054-0b8d782e9300",
"status": "confirmed",
"confirmation_mode": "token",
"expires_at": "2026-10-01T11:02:09.366+00:00",
"order_id": "e9b398b5-40d9-476d-bae6-efc401861190",
"customer_id": null,
"total": 63,
"currency": "EUR",
"items": [
{
"quantity": 1,
"variant_id": "fbe89cdf-90a3-4050-a43b-e4c42302484a"
}
],
"quote": {
"tax": {
"amount": 8.69,
"source": "fallback",
"status": "quoted",
"prices_include_tax": true
},
"lines": [
{
"sku": "FEED-HOODIE-GRY-M",
"name": "Galactic Zip Hoodie",
"stock": 25,
"quantity": 1,
"available": true,
"line_total": 48,
"list_price": 48,
"product_id": "289533e8-f5b6-4d4f-bb23-2127875feb70",
"unit_price": 48,
"variant_id": "fbe89cdf-90a3-4050-a43b-e4c42302484a",
"variant_name": "Grey / M",
"category_name": "Wearables",
"unavailable_reason": null
}
],
"currency": "EUR",
"discount": {
"amount": 0,
"promotion": null
},
"shipping": {
"amount": 15,
"status": "quoted",
"is_free": false,
"description": "USA",
"free_threshold": 100
},
"subtotal": 48,
"grand_total": 63,
"total_is_final": true,
"shipping_address": {
"city": "New York",
"name": "John Doe",
"line1": "350 Fifth Avenue",
"state": "NY",
"country": "US",
"postal_code": "10118"
},
"unavailable_count": 0
},
"created_at": "2026-10-01T10:32:09.391151+00:00",
"confirmed_at": "2026-10-01T10:32:12.476+00:00",
"cancelled_at": null
},
"order": {
"id": "e9b398b5-40d9-476d-bae6-efc401861190",
"order_number": "ORD-1790850732602",
"total_amount": 63,
"currency": "EUR",
"payment_status": "pending",
"order_status": "pending"
},
"payment": {
"next_step": "POST /v1/payments/initialize",
"initialize_body": {
"order_id": "e9b398b5-40d9-476d-bae6-efc401861190",
"amount": 63,
"currency": "EUR",
"email": "john.doe@example.com"
},
"methods": [
{
"provider": "cash",
"display_name": "Cash on Delivery",
"type": "manual",
"environment": "production",
"is_configured": true
},
{
"provider": "stripe",
"display_name": "Stripe",
"type": "redirect",
"environment": "test",
"is_configured": true
},
{
"provider": "paypal",
"display_name": "PayPal",
"type": "popup",
"environment": "sandbox",
"is_configured": true
},
{
"provider": "paystack",
"display_name": "Paystack",
"type": "popup",
"environment": "test",
"is_configured": true
}
]
}
},
"evidence": [
{
"source": "pricing",
"operation": "GET /v1/prices/products/{id}",
"id": "fbe89cdf-90a3-4050-a43b-e4c42302484a",
"field": "resolved_price"
},
{
"source": "promotions",
"operation": "POST /v1/promotions/calculate-best",
"field": "discount"
},
{
"source": "shipping",
"operation": "shipping quote",
"field": "fee"
},
{
"source": "tax",
"operation": "POST /v1/tax/preview",
"field": "tax_amount"
},
{
"source": "orders",
"operation": "order create",
"id": "e9b398b5-40d9-476d-bae6-efc401861190",
"field": "total_amount"
},
{
"source": "payments",
"operation": "GET /v1/payments/methods",
"field": "methods"
}
],
"computed_at": "2026-10-01T10:32:13.845Z",
"currency": "EUR",
"environment": "sandbox"
}
