Skip to main content
PUT
Report the storefront's address and routes

Authorizations

Authorization
string
header
required

API Key Authentication

Use your API key in the Authorization header:

Key Types:

Secret Keys (Server-Side Only):

  • Format: tybrite_sk_live_* (production) or tybrite_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) or tybrite_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-changing POST calls require a secret key, for store and marketplace keys alike; GET /v1/auth/me accepts 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 403 with the error code out_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 403 with endpoint_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.

Body

application/json
base_url
string<uri> | null
required

The storefront's public address: https, a domain name (not an IP address), no user name or password. null reports the storefront as taken down.

Maximum string length: 2048
Example:

"https://shop.example-store.com"

platform_url
string<uri> | null

The address the storefront also answers on before a custom domain is connected, if any.

Maximum string length: 2048
custom_domain
string | null

The host name of a custom domain connected to the storefront, if any.

Maximum string length: 253
Example:

"shop.example-store.com"

routes
object | null

Page templates by purpose. Allowed keys: product, collection, category, policy, account. Each value is a relative path beginning with /, at most 512 characters, and may contain {slug}. Routes require a base_url.

Example:

Response

The report as GC now holds it

base_url
string<uri> | null
required
routes
object
required
reported_at
string<date-time>
required
merchant_review
enum<string>
required

Where the merchant's review of base_url stands. pending: the merchant is being asked. accepted: the merchant adopted it. declined: the merchant kept their own address. matches_website: it is the address the store already uses, so nothing is asked. unpublished: the storefront was reported as taken down.

Available options:
pending,
accepted,
declined,
matches_website,
unpublished
platform_url
string<uri> | null
custom_domain
string | null