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.
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
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'
});
intentId
String Allows restoring the previous WhenThen Intent SDK state for the consequent updateIntent( )
and completeIntent( )
calls.
Promise<{
errors: Array<{ message: string; }>;
}>;
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).
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
}
]
}
});
trackingId
String ﹡ paymentFlowId
String ﹡ The id of payment flow to run this intent against.
You can get this value from Settings -> Developers.
customer
Object customer.id
String customer.email
String customer.name
String customer.isGuest
Boolean amount
Object ﹡ amount.amount
number ﹡ amount.currency
String ﹡ ISO 4217 Code. Only "EUR" and "USD" currencies are supported at the moment.
location
Object location.country
String Three-letter country codes in ISO 3166-1 alpha-3.
cart
Object cart.id
String cart.weight
String cart.itemCount
String cart.items
[IntentCartItem] ﹡ Promise<{
data: StartIntentOutput;
errors: Array<{ message: string; }>;
}>;
StartIntentOutput
id
String date
Date trackingId
String paymentFlowId
String currency
String ISO 4217 Code e.g. EUR
amount
Object amount.formattedAmount
String amount.rawAmount
number status
Object Current status of this payment intent. See Checkout Status options
statusDate
Date location
Object location.country
String Three-letter country codes in ISO 3166-1 alpha-3.
customer
Object customer.id
String customer.isGuest
Boolean timeline
Object timeline.intentStarted
Object timeline.shipping
Object timeline.delivery
Object timeline.billing
Object timeline.paymentAttempts
[Object] timeline.completeCheckout
Object cart
Object cart.id
String cart.weight
String cart.itemCount
String cart.items
[IntentCartItem] 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'
}
});
trackingId
String customer
Object customer.id
String customer.email
String customer.name
String customer.isGuest
Boolean amount
Object amount.amount
Number amount.currency
String ISO 4217 Code e.g. EUR
location
Object location.country
String Three-letter country codes in ISO 3166-1 alpha-3.
cart
Object cart.id
String cart.weight
String cart.itemCount
String cart.items
[IntentCartItem] ﹡ billing
Object billing.status
String Status for billing address. See Form Step Status options
shipping
Object shipping.status
String Status for shipping address. See Form Step Status options
delivery
Object delivery.status
String Status for delivery option. See Form Step Status options.
Promise<{
data: UpdateIntentOutput;
errors: Array<{ message: string; }>;
}>;
UpdateIntentOutput
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'
});
paymentReference
String Promise<{
data: CompleteIntentOutput;
errors: Array<{ message: string; }>;
}>;
CompleteIntentOutput