Skip to main content
A Link token gives a consumer a reusable URL for connecting their retailer accounts. Create the token from your backend, then send the consumer to their URL. They can choose from your enabled retailers and return to connect additional accounts. The token is opaque, not a JWT. It has the prefix 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 with X-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.
Keep API credentials on your backend and verify the consumer’s identity before issuing their URL.
A successful request returns 201 Created.
Use the returned link_token to construct the URL:
V1 does not support a redirect or fallback URL.

​
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 the link_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.
If you supplied a key, an exact replay can recover the original token, but does not extend its lifetime or undo revocation. It returns the original creation response; use the metadata list for current status. To replace an expired or revoked token, use a new key or omit the header.

​
List metadata

List Link tokens requires customer_id and optionally filters by status=active, expired, or revoked:
The response is { "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:
Revocation is permanent. The API returns 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. 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.

​
Handling URLs securely

Anyone with the URL can use it, so keep stored tokens secure and share links only with the intended consumer. Do not put PII in URL parameters or tags.