Populating Custom Field with Promo Code at Checkout

In this documentation, we will explore how to update a custom field when a user uses a promo code at checkout. By adding specific code to the integration script's checkout complete callback, you can achieve this functionality seamlessly.

The goal is to populate a custom field with specific information when a user applies a promo code at checkout. This allows you to capture relevant data related to promo code usage, enhancing the user's experience and enabling personalized interactions.

Integration Script Update

To update a custom field when a user uses a promo code at checkout, you need to add the following code to the integration script's checkout complete callback payload:

tp.push(["addHandler", "checkoutComplete", function(conversion){ 
   if (conversion.promotionId != null) { 
     fetch(
      '{{ENVIROMENT}}/id/api/v1/identity/userinfo?aid=' + // SB -> https://sandbox.piano.io
        tp.aid +
        '&access_token=' +
        tp.pianoId.getToken() +
        '&lang=en_US',
      {
        method: 'PUT',
        headers: {
          'Content-Type': 'application/json; charset=UTF-8',
        },
        body: JSON.stringify({
          uid: tp.pianoId.getUser().uid,
          form_name: 'Test_Form', // Form ID e.g. MyAccountFields
          custom_field_values: [
            {
              field_name: 'Book', // Field ID , not a name of the CF
              value: "Text",
            },
          ],
        }),
      }
    );
   }
}]);

Note: Replace the variable {{ENVIROMENT}} with the Identity Management API base URL according to your environment.

• The checkoutComplete callback is triggered when the checkout process is completed.

• The conversion parameter contains relevant data about the completed checkout, including whether a promo code was used.

• The code checks if a promo code was used by verifying conversion.promotionId is not null.

• If a promo code was used, the script sends a PUT request to the specified endpoint with the necessary data to update the custom field.

Before implementing this functionality in a production environment, it is essential to thoroughly test it on your Sandbox application. This ensures that the integration works as expected and minimizes any potential issues during deployment.

Last updated: June 26, 2026