​
Overview

Subtotal Link is the client-side component that customers interact with to link their retail accounts to your app or website. Subtotal Link handles credential validation, multi-factor authentication, and error handling for each retailer that Subtotal supports. Check out our demo of Subtotal Link to see how it works.
Subtotal Link is the only available method for connecting retail accounts and is required for all Subtotal integrations.

​
Configuration

Sign into the Subtotal Dashboard to configure each of the items below.
  • Logo - Upload your logo to brand the Subtotal Link experience for your customers.
  • Link URL - The default URL for Subtotal Link is link.subtotal.com. Configuring a subdomain of your primary domain is recommended.
  • Retailers - Specify a list of retailers for your project. Customers will link accounts from these retailers.

​
The flow

The flow begins when a customer chooses to connect their retail account to your app or website. We’ll guide you through each step to ensure a smooth integration.

​
Step 1. Create a new connection

Connections represent links between customers’ retail accounts and your system. To create a connection, send a POST /connection request. Include a customer_id and merchant_id in the request body to specify which customer is establishing a connection to which merchant. Request body 
{
   "customer_id": "8a46e581-48ba-498a-9ad0-2ee72582e1af",
   "merchant_id": "01J7SC0NN73R6F5AVSP3XKPDV2"
}
A successful response will include a 201 Created status code and a connection_id. The connection_id is a unique identifier that you’ll store on your system and use in future API requests. Response body 
{
   "connection_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
}
New connections have a Pending Link 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

Connection tokens are short-lived JWTs that are used to authorize access to Subtotal Link or other resources in the Subtotal API. 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. Set the scope to link in the request body to specify that this connection token will be used with Subtotal Link. Request body 
{
  "scope": "link"
}
A successful response will include a 201 Created status code and a connection_token. You’ll pass the connection_token to Subtotal Link in the next step. Response body 
{
   "connection_token": "eyJhbGciOiAiUlMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiYXV0aC50eXBlY2FzdGxlLmNvbSIsICJzdWIiOiAiMDFKN1M5VFEyOENRSkQ1WTVaTlZQR0NTNkgiLCAiYXVkIjogInR5cGVjYXN0bGVfYXBpIiwgImV4cCI6IDE3MzkyNDM2MjYsICJpYXQiOiAxNzM5MjQxODI2LCAianRpIjogIjAxSktTRThBRzU4SFlCQkE2UDkwMTBWMjRIIiwgImNsaWVudF9pZCI6ICIwMUo3UzlUUTI4Q1FKRDVZNVpOVlBHQ1M2SCIsICJjb25uZWN0aW9uX2lkIjogIjAxSktTRTdRMU4xS1IxQUFBUEJCQVA0M0I1IiwgInNjb3BlIjogImFjY2VzcyJ9.OdAuJiA9sLyMyffIXhkg721bB-yRizmRTs0C-gmtGzlBplJq7qvOoxxcunfDNQw2PdU8zFMlBvwLUbuQsjthX1wcbGO0TsPgcS0-_MoAZ-WR5ZdbP4qTemZfmirMjVXXdA4oUtQwc-zxJwrZ0hn0Lb1ctKLmtnJhXoXVXRfGeby_0VmHhVJiUuzLSxnKsYnrrcTn9V8zR4BlMNmWWmr_rL5FomTgCCrj0xD_dsOZcg12rhWv4A3S7oOsJAL9-0poXSMdj9k5o0zT3-HdrFgHbbQIkGbHwcaz5KvwgPl35xZG-fTBZH0J-azQDZBC-aX59mFxxrTI_mJb8OUgtsSsbA"
}
From your front-end application, redirect your users to the Link URL configured for your project. Include the connection_token as a query parameter in the URL. Additionally, include redirect_url as a query parameter in the URL. Customers will be redirected to this URL after their session with Subtotal Link is complete.
Connections move to an Active status when a customer successfully verifies their credentials and links their account.

​
Next steps

Take a look at our recommended next steps.

Get a list of purchases

Query a list of purchases for any active connection.

Configure a custom domain

Host Subtotal Link on a subdomain of your primary website.