lt_v1_ followed by 43 base64url characters and contains no readable customer information. It expires after 30 days by default, with a configurable lifetime of 1–365 whole days.
Create a token and construct the URL
Call Create a Link token from your server. Authenticate withX-Api-Key, or a brand-authorized OAuth access token in Authorization: Bearer …. OAuth callers need connections:write to create or revoke and connections:read to list. Your Subtotal client must be active.
201 Created.
link_token to construct the URL:
Return to your app
The optionalredirect_url query parameter sets where the consumer goes when they select Exit, including after successful linking or from an unavailable-link screen. URL-encode its value. Without it, the success screen asks the consumer to close the window.
Only redirect_url is carried through retailer selection; other top-level query parameters are ignored.
Link result
When the consumer selects Exit, the redirect URL includessubtotal_link_result:
success: retailer authentication succeeded; purchase import may still be in progress.cancelled: the consumer exited before completing linking.timeout: the authentication session timed out or expired.invalid: the link is invalid, expired, or revoked.error: another linking or service failure occurred.
subtotal_link_result is replaced. Closing the tab does not guarantee a redirect. Use the result for your return screen and the API or webhooks to confirm connection state.
What consumers see
The URL opens a retailer selection screen with your brand name and icon and the retailers enabled for your program, sorted by name. Retailers you set tohidden, or to restricted for an audience the token’s email doesn’t match, are not shown; see Update a retailer.

- Subtotal Link starts for that retailer: consent, then the retailer login.
- An existing connection for that consumer and retailer is reused; otherwise a new one is created (see Inputs and attribution).
- After linking, Exit returns the consumer to your
redirect_url, if you set one.
Inputs and attribution
These values are immutable. Create a new token to change them or extend the lifetime.
Selecting a retailer reuses the newest non-revoked connection for your client, consumer, and retailer, or creates one if needed. Email, mobile, and tags apply only to new connections; existing connection metadata is unchanged.
Store and reuse a token
Store thelink_token and expires_at in your backend, associated with the consumer. Use the same token to construct links for future visits or to revoke access to that URL. You do not need a new token for each visit or retailer; multiple tokens for the same consumer can also be active at once.
Idempotency and token recovery
X-Subtotal-Idempotency-Key is optional. Include it to safely retry a creation request without issuing another token. Use a nonempty value up to 128 characters, and reuse the same key for retries. Keys are scoped to your client.
- The same key and normalized inputs return the original token and creation response, including the original expiry.
- The same key with different inputs returns
409 Conflict. - A new key creates a new token, even for the same consumer.
- Without a key, each successful request creates a new token.
List metadata
List Link tokens requirescustomer_id and optionally filters by status=active, expired, or revoked:
{ "link_tokens": [...] }, with customer_id, status, created_at, expires_at, and revoked_at on each item. It does not return the raw token.
Revoke or replace a URL
Revoke a Link token from your backend using the stored token:204 No Content, including for an already-revoked or expired token. An unknown token or one owned by another client returns 404.
Revoking or expiring a Link token prevents future exchanges. It does not disconnect existing retailer connections or invalidate a connection JWT already issued for the 30-minute Link flow.
Expired and unavailable links
An unknown, expired, or revoked link displays:This link is no longer active. Ask the brand that sent it for a new link.Create a new token from your backend and provide the consumer with the replacement URL. Previously shared URLs do not change when you create a new token.