Account Linking FAQ

This guide provides answers to FAQs.

Frequently asked questions

Can Account Linking handle accounts with 2FA, CAPTCHA or other authentication challenges?

Sometimes the user’s input is required to successfully log in to a retailer account. This can happen when the user has 2FA enabled for an account, or when the retailer shows a CAPTCHA for extra verification, or in various other situations.

For both verifyRetailer and grabNewOrders this is handled in the same way:

  • The BRAccountLinkingError will indicate the stages of this process

  • BRAccountLinkingErrorVerificationNeeded indicates that the SDK has encountered a page that requires the user’s input. The UIViewController parameter of the callback will be populated with the view controller that you should display

  • BRAccountLinkingErrorVerificationCompleted indicates that the user successfully authenticated and you should now dismiss the view controller (note that the UIViewController callback parameter will be nil in this case but you do not need it to dismiss a presented modal, simply call, e.g. self.dismiss(animated: false))


let taskId = BRAccountLinkingManager.shared().grabNewOrders(for: .walmart) { retailer, order, remaining, viewController, errorCode, sessionID in

  if (errorCode == .verificationNeeded) {
    self.present(viewController, animated: true)
  } else if errorCode == .verificationCompleted {
    self.dismiss(animated: false)
  } else if errorCode == .none {
    // Order may be returned here         
    if (remaining <= 0) {
      // Grab Orders Completed Successfully
      // No more orders to fetch
  } else {
    // Grab Orders Failed. Check error for more info

Can I execute Account Linking from a background thread?

Account Linking is not thread safe so we recommend all execution is done on the main thread.

Linking multiple accounts for the same merchant is not supported. You have to unlink the account first before you link a different one for the same retailer.

Can I change user’s credentials?

Modifying user’s credentials is not allowed after the BRAccountLinkingConnection object is created. In order for you to change the credentials, you have to unlink the account first and then create and link new connection with different credentials.

let username = "user 1"
let password = "pass 1"
let connection = BRAccountLinkingConnection(retailer: .walmart, username: username, password: password)
BRAccountLinkingManager.shared().linkRetailer(with: connection)

BRAccountLinkingManager.shared().unlinkAccount(for: .walmart) {
    let conn = BRAccountLinkingConnection(retailer: .walmart, username: "user 2", password: "pass 2")
    conn.configuration.dayCutoff = 30
    BRAccountLinkingManager.shared().linkRetailer(with: conn)


It is recommended to call verifyRetailer before linking if unsure the credentials are valid

grabNewOrders returns success but i don’t see any of my orders!

The most common reasons for that are:

  • Make sure your connection dayCutoff or dateCutoff is large enough to capture your orders. You can verify that by login in your web account and verifying that you have purchases newer than your dayCutoff.
  • Have you tried resetting the orders history? Very often developers forget to reset the cache while testing. By default the SDK maintains an internal date of the last successful search for each retailer so that each time you attempt to retrieve new messages, you will only get messages since the last successful check, and subject to the day cutoff that you set (default is 15 days).

You can also reach out to us at, if you are still not seeing orders after trying the steps above.


Unlinking account won’t reset the user’s cache if the same user is linked again. To make sure the cache is removed, you must call BRAccountLinkingManager.shared().resetHistory(for: .walmart) for your retailer

Can I fetch In-Store orders with Account Linking?

Yes, Account Linking supports In-Store purchases as long as they are visible in your account on the web. Please check your retailer’s guidelines on how to link your In-Store purchases so they appear in your web account.


Target, Walmart, Kroger are just few of the popular merchants that allow their customers to see their In-Store purchases on the web.

What order types Account Linking supports?

Account Linking supports 5 order types:

  1. In-Store - Purchases done in store.
  2. Delivery - Purchases that are shipped to the customer.
  3. Pickup - Online purchases, picked in store by the customer.
  4. Digital - movies, eBooks, etc…
  5. Subscription

Does Account Linking return an order status of my purchases?

Account Linking supports 6 status values: cancelled, refunded, returned, completed, shipped, ordered. Depending on the retailer and the order type you may see these values populated in one of the following places:

  1. Order status - A status representing the whole order
  2. Shipment status - A status representing a single shipment. Available for Delivery orders only
  3. Product status - A status for a single product.

Is Account Linking going to return a previously fetched order, if its status changes from shipped to delivered?

Account Linking only returns an order once. To get the most recent version of an order you have to re-scrape the order by resetting the order history.

BRAccountLinkingManager.shared().resetHistory(for: .walmart)

How does Account Linking handles the user’s credentials?

All credentials are stored locally on device’s keychain. They don’t leave the device and are only used by Account Linking, if authentication is required.

What data should I expect from Account Linking?

Account Linking returns orders as BRScanResult objects. You may see different properties of that object populated with values, depending on the retailer and the order type. For example: A In-Store order would return a list with BRProducts in its products property, while a Delivery order would have the shipments property populated with BRShipment objects. See order examples here


We recommend our clients support all fields they care about despite not seeing values at the moment for some of the retailers. That way they may benefit from any OTA updates down the road without the need to submit a new app update.

How frequent does the background fetch executes?

Although our background job is scheduled to run every hour, it is up to the device (OS) to decide if a background task should be executed or not.