Executing Actions

Overview

Actions are a core component of the Manage product. They enable users to cancel, pause, or modify their plans—such as switching to a different tier or adjusting plan terms. Fetching updated data from a Company is also treated as an Action.

This guide walks you through determining what Actions are available, choosing an Action, and executing that Action on a user’s behalf. It assumes you’ve already configured the Transact SDK.

Discovering Actions

The first step in executing Actions is determining which Actions are available. How you look up available Actions varies based on your use-case. For example, if the user has already connected some Accounts or Atomic has detected Accounts from a user’s transactions, you can see available Actions on the Account data itself.

This section demonstrates the different approaches you can take to look up available Actions.

Account Actions

Support for specific Actions can depend on the current state of a user’s Account. For example, an Account that is already pending cancellation cannot be cancelled again, or a Company may support pausing a plan for some Accounts but not for others.

As such, Atomic maintains lists of usable Actions for Accounts and Account Expenses as fields on the Account object returned in the Get Accounts endpoint. These Actions can be retrieved like this:

const response = await fetch(`${API_URL}/pay-link/accounts`, {
  headers: AUTH_HEADERS,
});
const { accounts } = await response.json();
for (const account of accounts) {
  console.log(account.company.name);
  for (const expense of account.expenses) {
    console.log(expense.actions);
  }
}

Netflix
[
  {
    actionId: '[ENCODED_ACTION_ID]',
    type: 'view-account',
    automated: false
  },
  {
    actionId: '[ENCODED_ACTION_ID]',
    type: 'refresh',
    automated: true
  },
  {
    actionId: '[ENCODED_ACTION_ID]',
    type: 'change-plan',
    automated: false
  },
  {
    actionId: '[ENCODED_ACTION_ID]',
    type: 'pause-plan',
    automated: true
  },
  {
    actionId: '[ENCODED_ACTION_ID]',
    type: 'cancel-plan',
    automated: true
  }
]

Suggestion Actions

Suggestions highlight Actions the user is more likely to take. By analyzing the user's Accounts and transactions, the Suggestion Engine generates insights and ties them to Actions that can be presented to the user as a simple CTA. For example, the user is more likely to want to cancel a subscription they haven’t used in a long time.

Suggestions can be retrieved in one of two ways. First, Suggestions for connected Accounts are included as a field on the Account object returned in the Get Accounts endpoint. Second, all Suggestions, whether for a specific Account or more general (based on common savings opportunities), are available in the dedicated Get Suggestions endpoint. These Suggestions and the Actions associated with them can be retrieved like this:

const response = await fetch(`${API_URL}/pay-link/suggestions`, {
  headers: AUTH_HEADERS,
});

const { suggestions } = await response.json();

for (const suggestion of suggestions) {
  console.log(suggestion.references[0].company.name);
  console.log(suggestion.action);
}

Netflix
{
  actionId: '[ENCODED_ACTION_ID]',
  type: 'change-plan',
  automated: false
}
Apple
{
  actionId: '[ENCODED_ACTION_ID]',
  type: 'connect-account',
  automated: true
}

Company Actions

Sometimes, instead of starting with a connected Account or a Suggestion, you may want to look up available Actions based on a Company. For example, you may want to show the user what Actions are available for Spotify, regardless of whether the user has connected a Spotify Account.

To look up Actions for a Company, look up the id for that Company, then make a request to the Actions for Company endpoint, like this:

const companyResponse = await fetch(`${API_URL}/company/search`, {
  headers: {
    ...AUTH_HEADERS,
    "content-type": "application/json",
  },
  method: "POST",
  body: JSON.stringify({
    query: "Spotify",
    scopes: ["pay-link"],
  }),
});
const companyResult = await companyResponse.json();
const company = companyResult.data[0];

const response = await fetch(
  `${API_URL}/pay-link/actions-for-company/${company._id}`,
  {
    headers: AUTH_HEADERS,
  },
);
const { actions } = await response.json();
console.log(company.name);
console.log(actions);

Spotify
[
  {
    actionId: '[ENCODED_ACTION_ID]',
    type: 'connect-account',
    automated: true
  },
  {
    actionId: '[ENCODED_ACTION_ID]',
    type: 'cancel-plan',
    automated: true
  },
  {
    actionId: '[ENCODED_ACTION_ID]',
    type: 'pause-plan',
    automated: true
  },
  {
    actionId: '[ENCODED_ACTION_ID]',
    type: 'switch',
    automated: true
  }
]

Choosing an Action

Once you have retrieved available Actions, you must determine which Action to execute. There are two general approaches to making this determination: user-driven (in which you display available Actions directly to the user) and algorithm-driven (in which the user doesn't directly interface with a list of Actions).

User-Driven Choice

Patterns for user-driven Action selection may vary, but some common cases include:

• An Account or Expense detail view that includes a series of CTA buttons for the available Actions.
• A carousel of all available Suggestions, with a CTA button for each associated Action.
• A calendar view that shows when upcoming Expenses are due, in which choosing an Expense displays CTA buttons for the available Actions.

Algorithm-Driven Choice

It is typically preferable to allow the user to directly select an available Action, but there are cases in which an algorithm-driven choice may be needed. Some examples may include:

• Bulk cancellation based on a search algorithm, such as "streaming services that haven't been used in more than 30 days."
• A chatbot matching the user's queries to one or more available Actions.
• An algorithm that pauses subscriptions on a set schedule.

Taking an Action

Launch the Transact SDK

To execute an Action, use the actionId field in the relevant Action returned from the API. Call the transact exported by the Transact SDK, using the actionId as a parameter.

Show Progress in Your UI

Since Actions and subsequent refreshes can occur in the background, we recommend using your UI to let users know when they are in progress. This can reduce confusion, as users may re-attempt Actions if they're not sure they worked.

To do so, use the onLaunch, onFinish, and onClose callbacks in the transact function.

Update Your Data

Since Actions often change the state of the Account, you will want to refetch any Account data upon their completion.

You can use webhooks, polling, or client-side events to wait for updates to complete in the Atomic system, and then retrieve the data from the GET /pay-link/accounts endpoint.

You can also listen directly for updates using the pay-link-accounts-updated webhook.

For more in depth discussion of the options for retrieving data, review the relevant guide.

Further Reading