Skip to main content

​
Overview

Dynamic Links are personalized Link URLs that are generated programmatically for a specific customer connection. They’re useful when you need to:
  • Reauthenticate an existing connection
  • Prefill customer context (such as email or mobile)
  • Create personalized or time-limited linking experiences
Instead of using a universal Link URL, you can dynamically create one by generating a connection token.

​
The flow

The flow begins when a customer chooses to connect their retail account to your app or website. Follow the steps below to dynamically generate and launch a personalized Link URL.

​
Step 1. Create a new connection

A connection represents the link between a customer’s retail accounts and your system. If you don’t already have a connection_id, you can create one by sending a POST /connection request. Request body 
{
   "customer_id": "8a46e581-48ba-498a-9ad0-2ee72582e1af",
   "email": "alice@example.com",
   "mobile": "+123456789"
   "retailer_id": "instacart",
}
A successful response will include a 201 Created status code and a connection_id. Store this connection_id on your system. Response body 
{
  "connection_id": "01J51S0JYV6N7K1030CV1ZKSCA",
  "customer_id": "8a46e581-48ba-498a-9ad0-2ee72582e1af",
  "email": "alice@example.com",
  "mobile": "+1234567890"
  "retailer_id": "instacart",
  "status": "initialized",
}
New connections are in an initialized status. You can view the status of any connection you have created by sending a GET /connection/{connection_id} request.

​
Step 2. Request a connection token

A connection token is a short-lived JWT used to authorize access to Subtotal Link or other Subtotal API resources. To create a connection token, send a POST /connection/{connection_id}/token request. Include the connection_id from the previous step as a URL parameter to specify which connection you’re creating a token for. Request body 
{
  "scope": "link"
}
A successful response will include a 201 Created status code and a connection_token. Response body 
{
   "connection_token": "eyJhbGciOiAiUlMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiYXV0aC50eXBlY2FzdGxlLmNvbSIsICJzdWIiOiAiMDFKN1M5VFEyOENRSkQ1WTVaTlZQR0NTNkgiLCAiYXVkIjogInR5cGVjYXN0bGVfYXBpIiwgImV4cCI6IDE3MzkyNDM2MjYsICJpYXQiOiAxNzM5MjQxODI2LCAianRpIjogIjAxSktTRThBRzU4SFlCQkE2UDkwMTBWMjRIIiwgImNsaWVudF9pZCI6ICIwMUo3UzlUUTI4Q1FKRDVZNVpOVlBHQ1M2SCIsICJjb25uZWN0aW9uX2lkIjogIjAxSktTRTdRMU4xS1IxQUFBUEJCQVA0M0I1IiwgInNjb3BlIjogImFjY2VzcyJ9.OdAuJiA9sLyMyffIXhkg721bB-yRizmRTs0C-gmtGzlBplJq7qvOoxxcunfDNQw2PdU8zFMlBvwLUbuQsjthX1wcbGO0TsPgcS0-_MoAZ-WR5ZdbP4qTemZfmirMjVXXdA4oUtQwc-zxJwrZ0hn0Lb1ctKLmtnJhXoXVXRfGeby_0VmHhVJiUuzLSxnKsYnrrcTn9V8zR4BlMNmWWmr_rL5FomTgCCrj0xD_dsOZcg12rhWv4A3S7oOsJAL9-0poXSMdj9k5o0zT3-HdrFgHbbQIkGbHwcaz5KvwgPl35xZG-fTBZH0J-azQDZBC-aX59mFxxrTI_mJb8OUgtsSsbA"
}
Append the connection_token to the end of the base Link URL link.subtotal.com to create a fully-formed Dynamic Link, You can optionally include a redirect_url as a query parameter to specify where customers should be sent after completing the flow. 
https://link.subtotal.com/{{connection_token}}?redirect_url=https%3A%2F%2Fexample.com%2Fprofile
Connections move to an Active status when a customer successfully authenticates with the retailer.