WhenThen

Intent
Publicinfo icon

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

link iconAPI 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.

info icon

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.

info icon

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