Yatta Checkout User Guide

Web API

On this page you can find detailed information on how to add the drop-in API, as well as details about its methods, parameters and fields.

Adding the JavaScript library

Yatta Checkout is provided as a UMD (universal module definition for JavaScript modules). You can integrate this as a plain JavaScript library into your system.

The Yatta Checkout drop-in does all the work for server-side and client-side integration. For the integration you need to make sure that the Document Object Model (DOM) is already rendered. This can be done by including between the and tags in your HTML and before calling any of our functions like :

Note: If you test the web integration on your local machine, you must ensure that the website is served by an http server. (Otherwise, it’s not possible to test the integration properly.) To do this, you can use Python’s http.server module or another server module with equivalent functionality.

Start Checkout

Starts the Checkout. If the user is already subscribed to your product, the relevant subscription management is opened. Similarly, if the user already purchased your product and the product is only allowed to be purchased once, the purchase information is opened. If multiple one-time purchases are allowed, a user who already purchased is able to purchase again.

This example code snippet starts the Checkout in the live environment for a user who does not yet have a right to access the product, pre-selecting a yearly subscription, passing custom meta data through the purchase, setting a group context for and a redirect after a successful purchase.

This example code snippet starts the Checkout in the live environment for a user who might not yet have a right to access the product, pre-selecting a one-time purchase with quantity two and limited term of three years starting on 1 January 2024. It passes custom meta data through the purchase and sets a group context for and a redirect after a successful purchase.

productId
Required String

This is the ID of the product for which the Checkout should be started.

environment
Optional String with value 'LIVE' or 'PREVIEW'

Set to 'LIVE' by default, but 'PREVIEW' should be used for testing purposes.

Note: If your product is not yet live, the environment parameter will be ignored and the preview environment will be used by default.

manageAssetHint
Optional Boolean

False by default. Set to true if the user has the right to access the product and is not allowed to buy multiple times. They will not be notified again by the Checkout that they have usage rights.

This is recommended if your website adapts to the user's asset status—e.g., your "Purchase" button text changes to "Manage" if the user already has a license and is not allowed to own multiple ones.

type
Required String with value 'ONE_TIME_PURCHASE' or 'SUBSCRIPTION'

This can be defined to pre-select a one-time purchase or subscription. One-time purchase mode is set by default.

subscriptionInterval
Optional String with value 'MONTHLY' or 'YEARLY'

This can be defined to pre-select a subscription interval. Monthly is set by default. This is only used for type 'SUBSCRIPTION'.

quantity
Optional Number

This can be defined to select the quantity of your product to be purchased. This is only used for type 'ONE_TIME_PURCHASE'.

term
Optional String with value 'UNLIMITED' or object with runtime, unit (and startOfTerm)

This can be defined to select the term of the product to be purchased. If set to 'UNLIMITED' the purchase is valid for lifetime. Alternatively, an object with a runtime number, a unit set to 'DAY', 'WEEK', 'MONTH' or 'YEAR', and a optional startOfTerm date of the term in ISO-8601 format, e.g. 2019-09-26T00:00:00+0200, can be set. This is only used for type 'ONE_TIME_PURCHASE'.

customMetaData
Optional Object with up to 64 key-value pairs, keys are strings, values are of any type

This can be defined to pass any of your required data through the purchase process and, after a successful purchase, to you via callback. Maximum 64 key-value pairs are allowed. Keys are strings up to 42 characters. Values can be of any kind, but must be shorter than 1024 characters when stringified.

groupContext
Optional Object with ID and name

If the user buys within a certain group context, e.g., on behalf of a company, an object can be passed through the purchase process and will be returned to you after a successful purchase via callback. The object contains an id, i.e., a string identifying the group, and a name string for the name of the group.

onSuccess
Optional Object with optional redirectUrl

On successful purchase, certain actions might be desired. Therefore this object can be set, containing a redirectUrl string, defining the URL the user should be redirected to after making a purchase and closing the checkout drop-in.

Sign-in status change

Subscribe to changes to the current user's sign-in status.

callback
Required (signedIn: boolean) => void

Function called whenever the user's signed-in boolean changes.

Asset status change

Subscribe to changes to the asset status of the current user for a given product.

productId
Required String

Value is the ID of the product for which the asset status should be retrieved.

callback
Required (assetStatus: AssetStatus | null) => void

Function that is called whenever the user's asset status changes. The parameter for the callback has the type AssetStatus.

environment
Optional String with value 'LIVE' or 'PREVIEW'

Sets whether to retrieve the user's asset status for 'LIVE' or 'PREVIEW' environments.

Note: If your product is not yet live, the environment parameter will be ignored and the preview environment will be used by default.

AssetStatus object

The asset status for a specified product provided to the callback in the drop-in interface if the user is signed in and has the right to access the asset.

Note: When the AssetStatus object is null, the user does not have a license.

type
String with value 'ONE_TIME_PURCHASE' or 'SUBSCRIPTION'

This identifies if the type of the asset is a one-time purchase or a subscription.

bookingStatus
String with value 'ONGOING' or 'CANCELED'

Provides the booking status of the subscription. This is only used for type 'SUBSCRIPTION'.

License session change

Subscribe to changes to the session token of the current user for any of your products.

productId
Required String

Value is the ID of any product allowed to be checked out on the host page.

callback
Required (licenseSession: LicenseSession | null) => void

Function that is called whenever the license session token of the user changes. The parameter for the callback has the type LicenseSession.

LicenseSession object

The license session for any of your products to the callback in the drop-in interface if the user is signed in.

Note: When the LicenseSession object is null, the user is not signed in.

sessionToken
String

The session token can be used in conjunction with your API Key to get license information for the current user session through the REST API.

Sign in

Allows the user to sign in, then closes without additional actions.

Sign out

Signs the user out.

Links a non-Yatta account to the Checkout to ensure access to licenses for products that require a link to this account. This is only necessary if you want to use your own IAM.

accountId
Required String

A new ID for the account in your IAM to map the user to the Yatta account. With this ID, you can use our REST API to check if the user has an active license.

If you do not provide us with a linked account, we will generate an ID for you so you can use the Yatta IAM without calling this method.

email
Optional String

Email address used to auto-start the Yatta sign-in and to pre-fill Yatta authentication forms, when the checkout is started.

Note: Remember to update your Privacy Policy to reflect the fact you will be passing your user's email address to us for authentication.

Note: If a product that requires a linked account is sold using the Checkout, this API must be called every time the user signs in or out, and upon page load.

Implementation example

Here is a basic example of a Yatta Checkout website implementation showing how to initialize and open the Checkout on a website.

Note: The JavaScript library will embed Yatta Checkout on your website in an iframe. The content of this iframe is hosted on a Yatta domain. Modern browsers do not allow JavaScript to communicate between your website and the iframe due to cross-origin resource policy (CORP), so all communication is handled via window.postMessage (postMessage() is a global method that safely enables cross-origin communication).

Apple Safari reports the existence of an iframe with a different domain as an error in the JavaScript console: "Blocked a frame with origin...". This has no impact on the functionality of Yatta Checkout and this message may be ignored.