Change a Subscribe & Save subscription
Change one thing about the shopper’s subscription per request: the delivery interval, the
items, or where the deliveries go. A change to the items applies from the next delivery; a change to
the interval restarts the schedule from today. A change the offer or the store does not allow is refused with 400 or 409
and a message the shopper can read: an interval the offer does not list, an item the offer does not
cover, or item changes the store has turned off.
Send exactly one group of fields:
interval_unitwithinterval_count: the delivery interval, one of the offer’s intervals.items: the full list of items for each delivery, 1 to 50 entries. Items left out are removed.fulfillment_methodwithshipping_address_id(one of the shopper’s saved addresses) for delivery, or withpickup_location_idfor pickup, and optionallyshipping_option_id.
Customer-self access. Works with a publishable key (safe from the
browser). Provide the shopper’s session token in the x-auth-token
header (or the store’s bring-your-own-auth assertion in x-external-auth);
it must resolve to the customer in the {id} path parameter, otherwise the
request returns 403. A subscription that belongs to another shopper reads
as 404.
curl --request PATCH \
--url https://api.tybritelabs.com/v1/customers/{id}/shopper-subscriptions/{subscriptionId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-auth-token: <x-auth-token>' \
--data '
{
"interval_unit": "week",
"interval_count": 6
}
'{
"subscription": {
"id": "8d6a1c52-0b8f-4e63-a1f4-2c9d7e5b3a10",
"status": "active",
"offer_id": "4c1c7b9e-2f58-4f43-9d3a-6f0e2a8b1c11",
"offer_label": "Subscribe & save 15%",
"interval_unit": "month",
"interval_count": 1,
"next_delivery_on": "2026-11-28",
"fulfillment_method": "delivery",
"shipping_address_id": "c176eadf-13e3-4bdc-ba5b-06cfa3f2fcb9",
"pickup_location_id": null,
"renewal_mode": "off_session",
"payment_method": {
"id": "5a0e2d7c-91b4-4c3a-8e6f-1d2b3c4a5e60",
"brand": "visa",
"last4": "4242",
"exp_month": 12,
"exp_year": 2028
},
"terms": {
"offer_name": "Monthly coffee",
"discount_type": "percentage",
"discount_value": 1500,
"first_order_discount_value": 2000,
"min_cycles": 0,
"max_skips_per_year": 4,
"free_shipping": false,
"stacks_with_promotions": false,
"interval_unit": "month",
"interval_count": 1
},
"deliveries_completed": 3,
"paused_until": null,
"cancel_effective_on": null,
"created_at": "2026-08-28T09:30:00+00:00",
"items": [
{
"product_id": "715b8c10-eb11-4289-8c0e-2966e78cf9a5",
"variant_id": "15ca5a86-4b1b-47c3-8762-a1aa43941565",
"quantity": 2,
"name": "Colombian Roast 1 kg"
}
],
"pending_action": null
}
}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
The signed-in shopper's session token, obtained when the shopper logs in. Must resolve to the customer in the {id} path parameter.
Bring-your-own-auth assertion for stores that manage authentication in an external identity provider (Auth0, Clerk, Cognito, Firebase, NextAuth, SSO). Resolves the shopper whose subscriptions are managed.
Format: <base64url(JSON)>.<base64url(HMAC-SHA256(JSON))> where the JSON is { "external_id": "...", "iat": <unix>, "exp": <unix> } and the HMAC is keyed on the store's hmac_secret. Claim lifetime capped at 300 seconds. Provide exactly one of x-auth-token, x-external-auth, or x-idp-token.
A raw token from the store's own identity provider (e.g. a Firebase ID token). Galactic Core forwards it to the store's configured Auth verifier, which validates it against the provider and returns the identity; resolves the shopper whose subscriptions are managed.
Use this when the store wants Galactic Core to verify tokens on its behalf rather than signing an assertion itself. Verification is fail-closed: if the verifier rejects the token or is unreachable, the request is unauthenticated (401). Requires an Auth verifier to be configured for the store. Provide exactly one of x-auth-token, x-external-auth, or x-idp-token.
Path Parameters
The shopper's customer id.
The id of the Subscribe & Save subscription.
Body
week, month 1 <= x <= 521 - 50 elementsShow child attributes
Show child attributes
delivery, pickup One of the shopper's saved addresses. Used with fulfillment_method delivery.
A pickup location of the store. Used with fulfillment_method pickup.
200Response
The subscription after the change.
A shopper's Subscribe & Save subscription: a recurring delivery they agreed to, with the terms accepted at sign-up. Each delivery after the first is an ordinary order for the store.
status is active, paused, past_due (a delivery could not be paid and is being retried),
cancelled or ended. renewal_mode is off_session when a saved card is charged for each delivery,
or confirm when the shopper pays each delivery from a link sent to them.
Show child attributes
Show child attributes
curl --request PATCH \
--url https://api.tybritelabs.com/v1/customers/{id}/shopper-subscriptions/{subscriptionId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-auth-token: <x-auth-token>' \
--data '
{
"interval_unit": "week",
"interval_count": 6
}
'{
"subscription": {
"id": "8d6a1c52-0b8f-4e63-a1f4-2c9d7e5b3a10",
"status": "active",
"offer_id": "4c1c7b9e-2f58-4f43-9d3a-6f0e2a8b1c11",
"offer_label": "Subscribe & save 15%",
"interval_unit": "month",
"interval_count": 1,
"next_delivery_on": "2026-11-28",
"fulfillment_method": "delivery",
"shipping_address_id": "c176eadf-13e3-4bdc-ba5b-06cfa3f2fcb9",
"pickup_location_id": null,
"renewal_mode": "off_session",
"payment_method": {
"id": "5a0e2d7c-91b4-4c3a-8e6f-1d2b3c4a5e60",
"brand": "visa",
"last4": "4242",
"exp_month": 12,
"exp_year": 2028
},
"terms": {
"offer_name": "Monthly coffee",
"discount_type": "percentage",
"discount_value": 1500,
"first_order_discount_value": 2000,
"min_cycles": 0,
"max_skips_per_year": 4,
"free_shipping": false,
"stacks_with_promotions": false,
"interval_unit": "month",
"interval_count": 1
},
"deliveries_completed": 3,
"paused_until": null,
"cancel_effective_on": null,
"created_at": "2026-08-28T09:30:00+00:00",
"items": [
{
"product_id": "715b8c10-eb11-4289-8c0e-2966e78cf9a5",
"variant_id": "15ca5a86-4b1b-47c3-8762-a1aa43941565",
"quantity": 2,
"name": "Colombian Roast 1 kg"
}
],
"pending_action": null
}
}