Intent
Public

Monitor, analyze and optimise your checkout for payment intents, attempts, acceptance, fees and much more.

Use the Intent API to help track your sales funnel, from when a customer begins the checkout process to payment completion. The benefit of using this API is that you can get rich insights on active and inactive checkout sessions, potentially lost payments, and failed payment attempts.

Intent is part of the whenthen-checkout-sdk. It provides unique insight into every stage of your customers checkout sessions. Intent also publishes Active and Inactive checkout sessions, in real-time, into your dashboard allowing you to monitor and analyze and take action to optimise your checkout for optimal conversion.

Tech Tutorial

API Reference

Installation

The WhenThen Intent SDK is available on npm. See @whenthen/sdk-intent for an API Reference.

npm install --save @whenthen/sdk-intent
# or
yarn add @whenthen/sdk-intent

Install WhenThen intent SDK package from npm public registry using npm or yarn.

Currently our SDKs are published as private packages so you will need to use the following auth token to install from npm

echo "//registry.npmjs.org/:_authToken=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" > .npmrc

Initialisation

import { WhenThenIntent } from '@whenthen/sdk-intent';

window.addEventListener('load', async () => {
  const intent = WhenThenIntent({ apiKey: 'PUBLIC_KEY_OR_CLIENT_TOKEN_XXX' });
  const { errors } = await intent.initialize();
});

Initialise WhenThen Intent SDK with your Public Key or a Client Token. You can view and manage your API keys in the WhenThen Web Application.

WhenThen intent SDK must be initialized using the initialize() function before any checkout events are emitted.

WhenThenIntent() function also supports 2nd optional parameter:

const intent = WhenThenIntent({
  apiKey: 'PUBLIC_KEY_OR_CLIENT_TOKEN_XXX',
  intentId: '84c76017-5c1c-4e23-b55e-c868f305d508'
});

Init Options Table

ValueType

intentIdString
Allows restoring the previous WhenThen Intent SDK state for the consequent updateIntent( ) and completeIntent( ) calls.

Init Result

Promise<{
	errors: Array<{ message: string; }>;
}>;

How it works

The intents API provides you with three methods: startIntent( ), updateIntent( ), and completeIntent( ). These methods should be called at each stage of your checkout process.

startIntent( ) will set the context for the consequent updateIntent( ) and completeIntent( ) calls. If the intent is already started - include intentId to options parameter of WhenThenIntent( ) function (See Init Options).

Start Intent

startIntent( ) starts a new payment flow instance and creates an intent for a checkout session which can be used to track the life cycle of the checkout.

You must pass us your paymentFlowId when starting an intent. You can retrieve this value by navigating to the settings of your payment flow in the WhenThen Web Application.

const { data, errors } = await intent.startIntent({
trackingId: '45ef20e0-7e1b-4b52-9e6e-a6dcd1db6792',
paymentFlowId: '88e5b224-1319-4040-9e43-c843372acfe1',
amount: {
    amount: 5999,
    currency: 'USD'
},
customer: {
    id: '65o5a442-1319-4040-9e43-c843372aclif',
    name: 'Joe Smith',
    email: 'john@test.com',
    isGuest: true
},
location: {
    country: 'USA'
},
cart: {
    id: '32fe20h0-7e1b-4b52-9e6e-a6dcd1db3609',
    weight: 12,
    itemCount: 1,
    items: [
      {
          id: '99l5h442-1319-4040-9e43-c843372acfil',
          quantity: 2,
          title: 'Some Title',
          variantTitle: 'Variant Title',
          weight: 64,
          taxable: true,
          requiresShipping: true,
          price: 30,
          sku: '69s3t442-3501-5050-9e43-c843372aflic',
          lineTotal: 100,
          image: 'https://image.url',
          discountedPrice: 21,
          totalDiscount: 21
      }
    ]
}
});

Start Intent Options Table

PropType

trackingIdString ﹡
A unique tracking id for tracking the intent on your site e.g. an order id or checkout id.
paymentFlowIdString ﹡
The id of payment flow to run this intent against.
You can get this value from Settings -> Developers.
customerObject
Customer object
customer.idString
This can be your own customer id, or if you have a vault customer you can use that
customer.emailString
Email of the customer to track
customer.nameString
Name of the customer to track
customer.isGuestBoolean
If the customer is a guest
amountObject ﹡
amount.amountnumber ﹡
Total amount for checkout in minor units e.g. 5099 = 50.99
amount.currencyString ﹡
ISO 4217 Code. Only "EUR" and "USD" currencies are supported at the moment.
locationObject
If location is specified it will be used. If location is not specified we will use GeoLocation
location.countryString
Three-letter country codes in ISO 3166-1 alpha-3.
cartObject
Object describing the cart
cart.idString
The id of the cart
cart.weightString
The weight of the cart
cart.itemCountString
The count of the cart items
cart.items[IntentCartItem] ﹡
A list of cart items

Start Intent Result

Promise<{
  data: StartIntentOutput;
  errors: Array<{ message: string; }>;
}>;

StartIntentOutput

StartIntentOutput Table

PropType

idString
The intent id for future use and updates
dateDate
Date the intent was created
trackingIdString
A unique tracking id for tracking the intent on your site e.g. an order id or checkout id
paymentFlowIdString
The id of payment flow this intent is run against
currencyString
ISO 4217 Code e.g. EUR
amountObject
amount.formattedAmountString
Formatted amount
amount.rawAmountnumber
Raw amount
statusObject
Current status of this payment intent. See Checkout Status options
statusDateDate
Date the last status was changed
locationObject
location.countryString
Three-letter country codes in ISO 3166-1 alpha-3.
customerObject
PII details are not exposed for SDK calls
customer.idString
Id of the customer
customer.isGuestBoolean
If the customer is a guest
timelineObject
A timeline representing the status of various steps of the checkout stage
timeline.intentStartedObject
timeline.shippingObject
Details for status of the shipping address section of the checkout form
timeline.deliveryObject
Details for status of the delivery option section of the checkout form
timeline.billingObject
Details for status of the billing address section of the checkout form
timeline.paymentAttempts[Object]
Set when a payment attempt has been made
timeline.completeCheckoutObject
Set when purchase is complete and completePaymentIntent is called
cartObject
Object describing the cart
cart.idString
The id of the cart
cart.weightString
The weight of the cart
cart.itemCountString
The count of the cart items
cart.items[IntentCartItem]
A list of cart items

Update Intent

Use updateIntent( ) to update any of the intent details or status. For example, here we are changing the shipping form status to COMPLETE and delivery options status to IN_PROGRESS

const { data, errors } = await intent.updateIntent({
  shipping: {
    status: 'COMPLETE'
  },
  delivery: {
    status: 'IN_PROGRESS'
  }
});

Update Intent Options Table

PropType

trackingIdString
A unique tracking id for tracking the intent on your site e.g. an order id or checkout id.
customerObject
Customer object
customer.idString
This can be your own customer id, or if ou have a vault customer you can use that
customer.emailString
Email of the customer to track
customer.nameString
Name of the customer to track
customer.isGuestBoolean
If the customer is a guest
amountObject
amount.amountNumber
Total amount for checkout in minor units e.g. 5099 = 50.99
amount.currencyString
ISO 4217 Code e.g. EUR
locationObject
If location is specified it will be used. If location is not specified we will use GeoLocation
location.countryString
Three-letter country codes in ISO 3166-1 alpha-3.
cartObject
Object describing the cart
cart.idString
The id of the cart
cart.weightString
The weight of the cart
cart.itemCountString
The count of the cart items
cart.items[IntentCartItem] ﹡
A list of cart items
billingObject
billing.statusString
Status for billing address. See Form Step Status options
shippingObject
shipping.statusString
Status for shipping address. See Form Step Status options
deliveryObject
delivery.statusString
Status for delivery option. See Form Step Status options.

Update Intent Result

Promise<{
  data: UpdateIntentOutput;
  errors: Array<{ message: string; }>;
}>;

UpdateIntentOutput

UpdateIntentOutput Table

See Start Intent Result

Complete Intent

Call this when the payment is complete. The intent will be updated to COMPLETE and the intent will be linked to the payment in the WhenThen system.

const { data, errors } = await intent.completeIntent({
  paymentReference: '88e5b224-1319-4040-9e43-c843372acfe1'
});

Complete Intent Options Table

PropType

paymentReferenceString
The payment reference from the payment processor

Complete Intent Result

Promise<{
  data: CompleteIntentOutput;
  errors: Array<{ message: string; }>;
}>;

CompleteIntentOutput

CompleteIntentOutput Table

See Start Intent Result

IntentPublic

Intent
Public