curl --request GET \
--url https://api.farthing.ai/v1/checkouts/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.farthing.ai/v1/checkouts/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.farthing.ai/v1/checkouts/{id}', 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.farthing.ai/v1/checkouts/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.farthing.ai/v1/checkouts/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.farthing.ai/v1/checkouts/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.farthing.ai/v1/checkouts/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "1f2e3d4c-5b6a-4790-8123-abcdef012345",
"status": "awaiting_user_action",
"target": {
"kind": "direct_url",
"url": "https://your-sandbox-store.myshopify.com/products/widget",
"request": "buy this, cheapest delivery"
},
"constraints": {
"maxCost": {
"amount": "60.00",
"currency": "USD"
}
},
"buyerProfileId": "b3a1c0de-2f77-45a0-9c8e-6f4b2a1d9e30",
"metadata": {},
"browser": {
"embedTokenUrl": "/v1/checkouts/1f2e3d4c-5b6a-4790-8123-abcdef012345/embed-token",
"permissions": [
"read"
]
},
"progressItems": [
{
"kind": "intent_started",
"label": "Started checkout",
"data": {},
"at": "2026-07-29T09:14:31.203Z",
"sequence": 1
},
{
"kind": "user_action",
"label": "This product comes in multiple options — pick one to continue.",
"data": {
"key": "variant"
},
"at": "2026-07-29T09:14:45.630Z",
"sequence": 4
}
],
"pendingUserAction": {
"id": "7c1de0a2-9b44-4f0a-b3c1-2a5e8d7f4b60",
"key": "variant",
"message": "This product comes in multiple options — pick one to continue.",
"responseSchema": {
"type": "object",
"additionalProperties": false,
"required": [
"Size"
],
"properties": {
"Size": {
"type": "string",
"title": "Size",
"oneOf": [
{
"const": "M",
"title": "M"
},
{
"const": "L",
"title": "L"
}
]
}
}
},
"expiresAt": "2026-07-29T09:24:45.612Z"
},
"createdAt": "2026-07-29T09:14:31.190Z",
"updatedAt": "2026-07-29T09:14:45.622Z"
}Get a checkout
The whole current state in one object: status, the append-only progressItems timeline, the pendingUserAction if the run is blocked, and the receipt once it has succeeded.
This is the endpoint you poll. Reads are not rate limited; a 3–5 second interval is right for a process that takes minutes.
Requires the checkouts.read scope.
curl --request GET \
--url https://api.farthing.ai/v1/checkouts/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.farthing.ai/v1/checkouts/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.farthing.ai/v1/checkouts/{id}', 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.farthing.ai/v1/checkouts/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.farthing.ai/v1/checkouts/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.farthing.ai/v1/checkouts/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.farthing.ai/v1/checkouts/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "1f2e3d4c-5b6a-4790-8123-abcdef012345",
"status": "awaiting_user_action",
"target": {
"kind": "direct_url",
"url": "https://your-sandbox-store.myshopify.com/products/widget",
"request": "buy this, cheapest delivery"
},
"constraints": {
"maxCost": {
"amount": "60.00",
"currency": "USD"
}
},
"buyerProfileId": "b3a1c0de-2f77-45a0-9c8e-6f4b2a1d9e30",
"metadata": {},
"browser": {
"embedTokenUrl": "/v1/checkouts/1f2e3d4c-5b6a-4790-8123-abcdef012345/embed-token",
"permissions": [
"read"
]
},
"progressItems": [
{
"kind": "intent_started",
"label": "Started checkout",
"data": {},
"at": "2026-07-29T09:14:31.203Z",
"sequence": 1
},
{
"kind": "user_action",
"label": "This product comes in multiple options — pick one to continue.",
"data": {
"key": "variant"
},
"at": "2026-07-29T09:14:45.630Z",
"sequence": 4
}
],
"pendingUserAction": {
"id": "7c1de0a2-9b44-4f0a-b3c1-2a5e8d7f4b60",
"key": "variant",
"message": "This product comes in multiple options — pick one to continue.",
"responseSchema": {
"type": "object",
"additionalProperties": false,
"required": [
"Size"
],
"properties": {
"Size": {
"type": "string",
"title": "Size",
"oneOf": [
{
"const": "M",
"title": "M"
},
{
"const": "L",
"title": "L"
}
]
}
}
},
"expiresAt": "2026-07-29T09:24:45.612Z"
},
"createdAt": "2026-07-29T09:14:31.190Z",
"updatedAt": "2026-07-29T09:14:45.622Z"
}Authorizations
Authorization: Bearer ck_test_… or ck_live_…. There is no other auth scheme — no query-string keys, no request signing, no OAuth.
Path Parameters
The checkout id returned at creation.
Response
The checkout.
The whole state of one run. This is what you poll.
succeeded, failed and cancelled are terminal; nothing leaves them.
queued, running, awaiting_user_action, succeeded, failed, cancelled Show child attributes
Show child attributes
Show child attributes
Show child attributes
Yours. Stored and echoed back untouched; never sent to a merchant, and not searchable.
Append-only, ordered by sequence. Build your UI around this rather than a spinner.
Show child attributes
Show child attributes
Your own id for the end user this purchase is for. Absent when the checkout is not tagged to one. Set explicitly at creation, or stamped from the authenticating key's binding.
"user_a91f"
Absent when no profile was attached, and absent after the referenced profile was deleted.
Present once a browser session exists. Not a URL you can watch at — a pointer to the endpoint that mints one.
Show child attributes
Show child attributes
Present only while the run is blocked. At most one per checkout at a time.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Present only on a succeeded checkout.
Show child attributes
Show child attributes