Implement Bill Navigator
Overview
This guide explains how to enable Bill Navigator for an end user through Pinwheel's SDK.
Bill Navigator allows users to connect their existing bank accounts and credit cards and automatically identifies recurring bills & subscriptions. The user can then perform an automated payment method switch for their associated bills and subscriptions or will be prompted with instructions to perform a manual switch when an automated switch is not supported. Finally, Users can mark manual switches as completed and use Pinwheel’s overview screens to keep track of which bills they have switched.
Prerequisites
Link SDK version 3.0
In order to use Bill Navigator, the Link SDK used in your application must be upgraded to version 3.0 or later. We recommend upgrading to the latest version for maximum conversion.
API and Webhook Version v2025-07-08
The use of Bill Navigator requires version v2025-07-08 or higher. Breaking changes for each API version upgrade are listed in our breaking change list. Functionality of older versions can be found by using the API version dropdown in the top left corner of this page.
Step 1: Create a Link token
Start by creating a Link Token and specifying "Bill Navigator" for the solution parameter. To enable bill switching and bill cancellation functionality, specify bill_switch in the features parameter.
Note: bill_switch is optional. If you do not include it, Bill Navigator will still identify recurring bills and subscriptions and offer all the subscription-management features and benefits outlined in the Overview. In this scenario, it is not necessary to add cards or allocation data in the link token request (see below).
Bill Navigator
If bill switching is specified as a feature, you must provide details for the card and target bank account that you want the user to switch their bills to. Each bank account needs to include type, account_number, and routing_number and is recommended to include name as well, especially if multiple accounts are included. See Link Token Creation docs for full details on required fields.
If bill switching is not required, then it is not required to send cards or allocation data.
POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
Pinwheel-Version: 2025-07-08
x-api-secret: YOUR-API-SECRET
{
"org_name": "YOUR APP NAME",
"end_user_id": "my_user_12345",
"allocation": {
"targets": [
{
"name": "My Checking Account",
"type": "checking",
"routing_number": "07464755",
"account_number": "193464372203"
}
]
},
"cards": [
{
"card_name": "Card Name",
"card_number": "12345678912345",
"cvc": "111",
"expiration_date": "05/29",
"name_on_card": "Jane Doe",
"card_zip_code": "12345",
"billing_address": "123 Lane St",
"billing_address2": "Apt 987",
"city": "New York",
"state": "NY"
}
],
"end_user": {
"platform_matching": {
"first_name": "John",
"last_name": "Smith",
"email": "[email protected]"
}
},
"solution": "Bill Navigator",
"required_jobs": [
"bill_switch",
]
}
POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
Pinwheel-Version: 2025-07-08
x-api-secret: YOUR-API-SECRET
{
"org_name": "YOUR APP NAME",
"end_user_id": "my_user_12345",
"end_user": {
"platform_matching": {
"first_name": "John",
"last_name": "Smith",
"email": "[email protected]"
}
},
"solution": "Bill Navigator",
"features": []
}
Step 2: Initialize Link
Use the Link token to open the Link modal in your client application. In addition to passing in the token, you can optionally pass several callback handlers.
<!DOCTYPE html>
<html>
<head>
<script src="https://cdn.getpinwheel.com/pinwheel-v2.3.js"></script>
<script>
Pinwheel.open({
linkToken: "INSERT LINK TOKEN",
onSuccess: (result) => {
console.log("Job succeeded!");
},
});
</script>
</head>
<body></body>
</html>
The onSuccess callback handler is executed on job success and contains metadata about the bill switch job. It is important to note that multiple bill switch jobs can be executed within a single Pinwheel link flow.
{
"meta": {
"count": 1
},
"data": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d",
"link_token_id": "97f420ff-5d0a-46ee-9cfc-6f17d5d31256",
"name": "bill_switch",
"timestamp": "2021-01-12T02:36:01.287148+00:00",
"outcome": "success",
"params": {
"action": "full_switch",
"allocation": {
"target": {
"account_type": "checking"
}
}
}
}
]
}
Step 3: Returning users
Pinwheel will use end_user_id passed in the Link token to keep track of returning users for recurring transaction monitoring and continued updating. Users who have previously connected an account will maintain their list of recurring transactions. For this use case a link token can be created exactly as above.
POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
Pinwheel-Version: 2025-07-08
x-api-secret: YOUR-API-SECRET
{
"org_name": "YOUR APP NAME",
"end_user_id": "my_user_12345",
"allocation": {
"targets": [
{
"name": "My Checking Account",
"type": "checking",
"routing_number": "07464755",
"account_number": "193464372203"
}
]
},
"cards": [
{
"card_name": "Card Name",
"card_number": "12345678912345",
"cvc": "111",
"expiration_date": "05/29",
"name_on_card": "Jane Doe",
"card_zip_code": "12345",
"billing_address": "123 Lane St",
"billing_address2": "Apt 987",
"city": "New York",
"state": "NY"
}
],
"end_user": {
"platform_matching": {
"first_name": "John",
"last_name": "Smith",
"email": "[email protected]"
}
},
"solution": "Bill Navigator",
"features": [
"bill_switch"
]
}
Once you've created the Link token, follow Step 2 to initialize the Link.
Updated 5 days ago