Handoffs
Add an overview of the Handoffs API here. This block is preserved across regenerations.
Endpoints
POST /api/v1/handoffs/redeem
Called by the tenant's own app server when a buyer arrives from checkout with ?token=. Verifies the token (signature, purpose, audience, issuer, 5-minute expiry), requires it to belong to this API key's tenant, and burns it: exactly one redeem succeeds. Returns the buyer's identity so the app can sign them in. Never call this from a browser; the token is a single-use credential and must not be logged.
Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.
The handoff token from the ?token= query parameter
Redeemed. data is { clerkUserId, email, contactId, sessionId, subscriptionId }. clerkUserId is the Clerk user PeakCommerce verified server-side for the person who completed this checkout: sign in exactly that user, and never look a user up by the email.
No content
Invalid handoff: bad signature, wrong audience, expired or malformed (invalid_handoff)
API key missing or invalid
Insufficient scope (handoffs:redeem required), or the token belongs to another tenant (handoff_wrong_tenant)
Post-purchase handoff is not configured for this tenant (handoff_not_configured)
Already redeemed (handoff_already_redeemed)
POST /api/v1/handoffs/redeem HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 16
{
"token": "text"
}No content
Notes, examples, or caveats for POST /handoffs/redeem go here.
GET /api/v1/settings/post-purchase-handoff
Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.
data is the setting, or null when not configured
No content
GET /api/v1/settings/post-purchase-handoff HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*
data is the setting, or null when not configured
No content
Notes, examples, or caveats for GET /settings/post-purchase-handoff go here.
PUT /api/v1/settings/post-purchase-handoff
{ audience, redirectUrl (https), activeKid, keys: [{ kid, secretRef }] }. secretRef is the NAME of the environment variable on the PeakCommerce service that holds the signing key (at least 32 characters), never the key itself. ?dryRun=true validates and returns before/after without writing. Audited.
Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.
data is { before, after, changed, written, dryRun }
No content
Validation failed (e.g. a key value where the env var name belongs)
PUT /api/v1/settings/post-purchase-handoff HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 2
{}No content
Notes, examples, or caveats for PUT /settings/post-purchase-handoff go here.
Last updated
Was this helpful?