Skip to main content

Custom Metadata

Web Billing supports custom metadata that you can send along when executing the purchase. The metadata will be propagated to webhook events and the Stripe customer object to enable its use in other systems, such as marketing or attribution tools.

purchases-js will also automatically collect any utm parameters in the URL and send it as metadata when invoking purchase(). You can opt-out of this behavior by setting the autoCollectUTMAsMetadata flag to false in the configure method.

How to send custom metadata when invoking purchase()​

When invoking purchase(), you can provide a metadata object using the PurchaseParams interface

    try {
        const {customerInfo} = await Purchases.getSharedInstance().purchase({
            rcPackage: pkg,
            metadata: {
                a_custom_key: "a custom value",
            },
        });
        if (Object.keys(customerInfo.entitlements.active).includes("pro")) {
            // Unlock that great "pro" content
        }
    } catch (e) {
        if (
            e instanceof PurchasesError &&
            e.errorCode == ErrorCode.UserCancelledError
        ) {
            // User cancelled the purchase process, don't do anything
        } else {
            // Handle errors
        }
    }

The metadata property accepts a key-value object with any custom data you want to send along with the purchase. The accepted values are string, number, boolean and null.

After purchasing with the metadata set up you will receive it in the Initial Purchase webhook event and in the Stripe Customer object.

Opt out of the automatic collection of UTM parameters​

You can opt-out of the automatic collection of UTM parameters by setting the autoCollectUTMAsMetadata flag to false in the configure method. Here's an example:

    const appUserId = authentication.getAppUserId(); // Replace with your own authentication system
    const httpConfig = {}; // Any setting you want to customize in purchases-js HTTP client.
    const flagsConfig = {autoCollectUTMAsMetadata: false};
    const purchases = Purchases.configure(WEB_BILLING_PUBLIC_API_KEY, appUserId, httpConfig, flagsConfig);