Agent
Start a Subscribe & Save subscription
Prepares the first order of a Subscribe & Save subscription as a hosted checkout and returns the link the shopper opens. The items are priced for the address with the offer’s first-delivery discount, and the stock is held for 30 minutes, as for any checkout intent.
The shopper confirms the order on the store’s own checkout page, never through the API. The page shows
the terms in subscribe_save.terms: the items, the price per delivery with the discount, the interval,
that it renews until cancelled, how to cancel, the minimum number of deliveries and the dates of the
first charge and the next delivery. The shopper ticks an unticked consent box, and the exact wording
accepted is recorded with the subscription. Confirming a subscription with the confirmation token
through POST /v1/agent/checkout-intents/{id}/confirm answers 409 hosted_confirmation_required.
The card used for the first payment is kept for the later deliveries where the store’s payment provider allows it; otherwise the shopper is sent a payment link for each delivery. The subscription begins when the first order is paid, never before.
Requires the shopper’s credential and personalization consent. A request without a shopper credential
answers 409 account_required. A replay of the same Idempotency-Key returns the same intent with
confirmation_token and confirmation_url null.
POST
/
v1
/
agent
/
me
/
shopper-subscriptions
Start a Subscribe & Save subscription
curl --request POST \
--url https://api.tybritelabs.com/v1/agent/me/shopper-subscriptions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"offer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"interval_count": 26,
"items": [
{
"variant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"quantity": 50
}
],
"shipping_address": {
"name": "<string>",
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>",
"latitude": 123,
"longitude": 123
},
"confirmation_mode": "hosted"
}
'import requests
url = "https://api.tybritelabs.com/v1/agent/me/shopper-subscriptions"
payload = {
"offer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"interval_count": 26,
"items": [
{
"variant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"quantity": 50
}
],
"shipping_address": {
"name": "<string>",
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>",
"latitude": 123,
"longitude": 123
},
"confirmation_mode": "hosted"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
offer_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
interval_count: 26,
items: [{variant_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a', quantity: 50}],
shipping_address: {
name: '<string>',
line1: '<string>',
line2: '<string>',
city: '<string>',
state: '<string>',
postal_code: '<string>',
country: '<string>',
latitude: 123,
longitude: 123
},
confirmation_mode: 'hosted'
})
};
fetch('https://api.tybritelabs.com/v1/agent/me/shopper-subscriptions', 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/me/shopper-subscriptions",
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([
'offer_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'interval_count' => 26,
'items' => [
[
'variant_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'quantity' => 50
]
],
'shipping_address' => [
'name' => '<string>',
'line1' => '<string>',
'line2' => '<string>',
'city' => '<string>',
'state' => '<string>',
'postal_code' => '<string>',
'country' => '<string>',
'latitude' => 123,
'longitude' => 123
],
'confirmation_mode' => 'hosted'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$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/me/shopper-subscriptions"
payload := strings.NewReader("{\n \"offer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"interval_count\": 26,\n \"items\": [\n {\n \"variant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"quantity\": 50\n }\n ],\n \"shipping_address\": {\n \"name\": \"<string>\",\n \"line1\": \"<string>\",\n \"line2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"latitude\": 123,\n \"longitude\": 123\n },\n \"confirmation_mode\": \"hosted\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
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/me/shopper-subscriptions")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"offer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"interval_count\": 26,\n \"items\": [\n {\n \"variant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"quantity\": 50\n }\n ],\n \"shipping_address\": {\n \"name\": \"<string>\",\n \"line1\": \"<string>\",\n \"line2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"latitude\": 123,\n \"longitude\": 123\n },\n \"confirmation_mode\": \"hosted\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tybritelabs.com/v1/agent/me/shopper-subscriptions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"offer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"interval_count\": 26,\n \"items\": [\n {\n \"variant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"quantity\": 50\n }\n ],\n \"shipping_address\": {\n \"name\": \"<string>\",\n \"line1\": \"<string>\",\n \"line2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"latitude\": 123,\n \"longitude\": 123\n },\n \"confirmation_mode\": \"hosted\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "<string>",
"confirmation_mode": "hosted",
"confirmation_url": "<string>",
"confirmation_token": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"total": 123,
"currency": "<string>",
"items": [
{}
],
"quote": {},
"subscribe_save": {
"offer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"interval_unit": "week",
"interval_count": 123,
"terms": {
"text_version": "<string>",
"lines": [
"<string>"
],
"agreement": "<string>",
"text": "<string>",
"first_charge_on": "2023-12-25",
"next_delivery_on": "2023-12-25",
"currency": "<string>",
"first_delivery_price": 123,
"price_per_delivery": 123,
"min_deliveries": 123,
"free_shipping": true
},
"accepted_at": "2023-11-07T05:31:56Z"
}
},
"evidence": [
{}
],
"computed_at": "2023-11-07T05:31:56Z",
"environment": "production",
"currency": "<string>"
}{
"error": {
"code": "invalid_request",
"message": "Invalid request parameters",
"details": "The 'email' field is required"
}
}{
"error": {
"code": "unauthorized",
"message": "Missing or invalid Authorization header"
}
}{
"error": {
"code": "consent_required",
"message": "The shopper has not granted personalization. Ask them to, then call POST /v1/agent/me/consent."
}
}{
"error": {
"code": "account_required",
"message": "Subscribe & Save needs a signed-in shopper. Have the shopper sign in or create an account with this store, then try again with their credential."
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests for this API key. Please slow down and try again shortly.",
"remaining": 0,
"reset": 1706198400
}
}{
"error": {
"code": "server_error",
"message": "An unexpected error occurred"
}
}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/*): Secret key required - 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.
Headers
Unique per subscription. A retry with the same key returns the same checkout.
Maximum string length:
200Customer session token from POST /v1/auth/login or POST /v1/auth/verify-otp. Provide exactly one of x-auth-token, x-external-auth, or x-idp-token.
Bring-your-own-auth assertion identifying the customer. Provide exactly one of x-auth-token, x-external-auth, or x-idp-token.
A raw token from the store's own identity provider, verified by the store's configured Auth verifier. Provide exactly one of x-auth-token, x-external-auth, or x-idp-token.
Body
application/json
An offer from GET /v1/agent/products/{id}/subscribe-save.
Available options:
week, month With interval_unit, one of the intervals the offer allows.
Required range:
1 <= x <= 52The first order. The lines the offer covers become the subscription; any others are bought once.
Required array length:
1 - 25 elementsShow child attributes
Show child attributes
Where the first order is delivered. line1 (or coordinates) and country are required.
Show child attributes
Show child attributes
Optional. A subscription is always confirmed on the hosted page.
Available options:
hosted Response
A replay of an earlier request with the same Idempotency-Key; the token and link are null.
⌘I
Start a Subscribe & Save subscription
curl --request POST \
--url https://api.tybritelabs.com/v1/agent/me/shopper-subscriptions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"offer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"interval_count": 26,
"items": [
{
"variant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"quantity": 50
}
],
"shipping_address": {
"name": "<string>",
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>",
"latitude": 123,
"longitude": 123
},
"confirmation_mode": "hosted"
}
'import requests
url = "https://api.tybritelabs.com/v1/agent/me/shopper-subscriptions"
payload = {
"offer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"interval_count": 26,
"items": [
{
"variant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"quantity": 50
}
],
"shipping_address": {
"name": "<string>",
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>",
"latitude": 123,
"longitude": 123
},
"confirmation_mode": "hosted"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
offer_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
interval_count: 26,
items: [{variant_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a', quantity: 50}],
shipping_address: {
name: '<string>',
line1: '<string>',
line2: '<string>',
city: '<string>',
state: '<string>',
postal_code: '<string>',
country: '<string>',
latitude: 123,
longitude: 123
},
confirmation_mode: 'hosted'
})
};
fetch('https://api.tybritelabs.com/v1/agent/me/shopper-subscriptions', 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/me/shopper-subscriptions",
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([
'offer_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'interval_count' => 26,
'items' => [
[
'variant_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'quantity' => 50
]
],
'shipping_address' => [
'name' => '<string>',
'line1' => '<string>',
'line2' => '<string>',
'city' => '<string>',
'state' => '<string>',
'postal_code' => '<string>',
'country' => '<string>',
'latitude' => 123,
'longitude' => 123
],
'confirmation_mode' => 'hosted'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$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/me/shopper-subscriptions"
payload := strings.NewReader("{\n \"offer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"interval_count\": 26,\n \"items\": [\n {\n \"variant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"quantity\": 50\n }\n ],\n \"shipping_address\": {\n \"name\": \"<string>\",\n \"line1\": \"<string>\",\n \"line2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"latitude\": 123,\n \"longitude\": 123\n },\n \"confirmation_mode\": \"hosted\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
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/me/shopper-subscriptions")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"offer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"interval_count\": 26,\n \"items\": [\n {\n \"variant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"quantity\": 50\n }\n ],\n \"shipping_address\": {\n \"name\": \"<string>\",\n \"line1\": \"<string>\",\n \"line2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"latitude\": 123,\n \"longitude\": 123\n },\n \"confirmation_mode\": \"hosted\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tybritelabs.com/v1/agent/me/shopper-subscriptions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"offer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"interval_count\": 26,\n \"items\": [\n {\n \"variant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"quantity\": 50\n }\n ],\n \"shipping_address\": {\n \"name\": \"<string>\",\n \"line1\": \"<string>\",\n \"line2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"latitude\": 123,\n \"longitude\": 123\n },\n \"confirmation_mode\": \"hosted\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "<string>",
"confirmation_mode": "hosted",
"confirmation_url": "<string>",
"confirmation_token": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"total": 123,
"currency": "<string>",
"items": [
{}
],
"quote": {},
"subscribe_save": {
"offer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"interval_unit": "week",
"interval_count": 123,
"terms": {
"text_version": "<string>",
"lines": [
"<string>"
],
"agreement": "<string>",
"text": "<string>",
"first_charge_on": "2023-12-25",
"next_delivery_on": "2023-12-25",
"currency": "<string>",
"first_delivery_price": 123,
"price_per_delivery": 123,
"min_deliveries": 123,
"free_shipping": true
},
"accepted_at": "2023-11-07T05:31:56Z"
}
},
"evidence": [
{}
],
"computed_at": "2023-11-07T05:31:56Z",
"environment": "production",
"currency": "<string>"
}{
"error": {
"code": "invalid_request",
"message": "Invalid request parameters",
"details": "The 'email' field is required"
}
}{
"error": {
"code": "unauthorized",
"message": "Missing or invalid Authorization header"
}
}{
"error": {
"code": "consent_required",
"message": "The shopper has not granted personalization. Ask them to, then call POST /v1/agent/me/consent."
}
}{
"error": {
"code": "account_required",
"message": "Subscribe & Save needs a signed-in shopper. Have the shopper sign in or create an account with this store, then try again with their credential."
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests for this API key. Please slow down and try again shortly.",
"remaining": 0,
"reset": 1706198400
}
}{
"error": {
"code": "server_error",
"message": "An unexpected error occurred"
}
}