Skip to main content

Integrating Talon.One

Before reading this tutorial, ensure that you have some understanding of the following concepts:

In this tutorial, we are sharing information with Talon.One using the customer session and customer profile entities.

Understanding the context#

Before getting started with the implementation, let's set up some business context.

Let's imagine that we are setting up an integration between Talon.One and our clothing store. We already have an application in the Campaign Manager, and it contains the following rule:

  • Any valid coupon code gives a 20% discount.

Choosing the SDK and the API#

According to the integration checklist, let's select an SDK and the API.

  • SDK: In our case, let's imagine our project uses Python, so we will use the Python SDK.
  • API: We're working with customer sessions and profiles, so we must use the Integration API V2.

Creating a Talon.One API key#

Create your API key:

  1. If you do not have an Application in the Campaign Manager already, create one.
  2. Open the Application.
  3. We assume that we have the rule mentioned earlier created in the Application.
  4. Click Settings > Developer Settings > Create a new API key.
  5. Use the API in your integration:
import talon_onefrom import ApiException
# Create configuration with your host destination and authorization using api_key_v1configuration = talon_one.Configuration(    host = "", # edit the host    api_key_prefix = {        "Authorization": "ApiKey-v1"    },    api_key = {        "Authorization": "f725d5a03e091ce9ab8bf51ee6c9ca37066e42f386b08bcf77ceddfe5364560"    })
# Instantiate the IntegrationAPI with out credentialsintegration_api = talon_one.IntegrationApi(talon_one.ApiClient(configuration))

Creating a customer session#

In Talon.One, a customer order, or transaction, is represented by a customer session and the Customer Session resource. This resource is essential, it's used to keep Talon.One updated about what the customer is doing, and to respond accordingly. For example, when the customer changes the content of the cart, notify Talon.One by updating the Customer Session resource to represent the new state of the cart.


A Talon.One customer session has nothing to do with a server session. The API client decides when to close the session.

To create a session and update it, we use the Integration API's updateCustomerSession endpoint. A session has a state, in our case we'll create it as open, which is the default. To understand session states, see [Managing session states][sessionsSates].

Back to our context, let's imagine that a shopper started creating a shopping cart. At this given time, the cart contains a couple of items and a coupon code. Let's communicate this to Talon.One to check if any rule applies.

This session should contain:

  • 2 cart items which exist in our shop's catalog.
  • A coupon (xmas20).

To do so, we apply the following steps:

  1. Create a NewCustomerSessionV2 object to be fed to the updateCustomerSession endpoint. In this case, we do not provide a customer profile id, which creates an anonymous session. For more information about customer profiles, see the tutorial.
  2. Add the 2 cart items and the coupon to the NewCustomerSessionV2 object.
  3. Send the request.
  4. Store the response for later processing.

The following code applies the above steps:

# ...# Instantiate the IntegrationAPI with out credentialsintegration_api = talon_one.IntegrationApi(talon_one.ApiClient(configuration))
# Prepare a NewCustomerSessionV2 object with the cart items and the coupon codecustomer_session = talon_one.NewCustomerSessionV2()customer_session.cart_items = [    talon_one.CartItem("Red Spring Blouse", "rdbs-1111", 1, 49, "Shirts"),    talon_one.CartItem("Denim Trousers", "dtr-2222", 1, 74, "Trousers"),]customer_session.coupon_codes = ["xmas20"]
# Instantiating a new IntegrationRequest objectintegration_request = talon_one.IntegrationRequest(customer_session)

Running this sample executes the request and we now have the response in the integration_request variable.

See also:

Performance tips#

Do more with one call: The Update customer session endpoint offers a responseContent property that you can use to save API calls. For example, you can use this property to retrieve the customer profile information without having to use another endpoint.

Reduce response time: When you query the Update customer session endpoint but do not require to run rules, set the runRuleEngine parameter to false to skip Rule Engine execution and get even faster response times.

Processing effects#

In the previous section, we sent an update to Talon.One. For every session or profile update that we send, Talon.One runs all applicable rules and returns the effects in the API response.

The way we process these effects depends on the SDK. We can register effect handlers or loop through the effects array in the response. With the Python SDK, we loop over the effects.

In our case, we have only one rule that applies a 20% discount if the coupon code is valid so we can expect the following effects:

To process the effects, let's loop through the effects array from the response. To keep the code sample small, let's only look for the setDiscount and rejectCoupon effects.

# ... auth
# API requestintegration_request = talon_one.IntegrationRequest(customer_session)
try:    api_response = integration_api.update_customer_session_v2(        "my_session_id", integration_request    )
    # Parse the effects    for effect in api_response.effects:        if effect.effect_type == "setDiscount":            # Initiating right props instance according to the effect type            setDiscountProps = integration_api.api_client.deserialize_model(                effect.props, talon_one.SetDiscountEffectProps            )
            # Access the specific effect properties            name = (,)            value = setDiscountProps.value            print(                "setDiscount triggered:\n"                f" Effect name: {name}\n"                f" Discount value: {value}"            )            # Apply the discount to the cart...
        elif effect.effect_type == "rejectCoupon":            rejectCouponEffectProps = integration_api.api_client.deserialize_model(                effect.props, talon_one.RejectCouponEffectProps            )            print(f"Coupon was rejected: {rejectCouponEffectProps.rejection_reason}")            # Display banner to the user...
except ApiException as e:    print("Exception when calling IntegrationApi->update_customer_session_v2: %s\n" % e)

Adding extra information to a customer session#

You might have to pass data that is not supported by the SDK. For example, you can readily create cart items, but what if we want to pass shipping-related information? We can do this with custom attributes.

In our case, let's imagine that we want to pass the city of the delivery address. Let's define create them in the Campaign Manager:

  1. Click Account > Dev Tools > Attributes > Create Attribute.
  2. In Associated entity, select Customer session. This means our customer session resource will store the attributes.
  3. In Attribute type, select String.
  4. In API Name, type shippingCity. This is the name to reference in the API call.
  5. Fill in all the other fields as required to enable the attribute in your application.

We can now set this custom attribute in API calls:

integration_request = talon_one.IntegrationRequest(    {        "attributes": {            "shippingCity": "Seattle",        }    },)api_response = integration_api.update_customer_session_v2("my_session_id", integration_request)

We can check that the shippingCity was added to our session with the Management API's List application sessions and Get session endpoints.

Managing customer profiles#

Aside from customer session, we can manage customer profiles. They store the attributes of your customers. For example, a profile stores the identifier, address, device, location or shopping history data of a customer.

A customer profile is represented inside Talon.One by the CustomerProfile entity.

A customer profile is the owner of a customer session and may have many sessions over its lifetime. Profiles are created and updated using the updateCustomerProfile endpoint, which works like the updateCustomerSession endpoint explained above.


The identifier of a customer profile is stored in the integration id attribute.

Creating a customer profile#

Let's create a customer profile with id customer-1234 and store a name and some shipping information in it:

  • We can use any of the built-in attributes to define our customer. To see the available attributes, see Customer entity attributes.
  • We can create custom attributes on the customer entity to store extra information.

Let's use the Name, ShippingCity and ShippingRegion built-in attributes and a custom attribute named MyAttribute in this example. We assume that MyAttribute has been created and assigned to the customer entity.

# Define a profile id.customer_profile_id = 'customer-1234'# Create the payload of the request.# We assume that these attributes have been created and# associated to the Customer Profile entity in the Campaign Manager.body = talon_one.NewCustomerProfile({  'Name': "Anthony Ray",  'ShippingCity': "Seattle",  'ShippingRegion': "Washington",  'MyAttribute': "my value"})# Execute the requestapi_response = integration_api.update_customer_profile_v2(customer_profile_id, body)

We can now use this customer profile with our sessions.

Connecting a customer profile to a customer session#

In the examples used for the customer session tutorial above, we used anonymous sessions. These sessions are not connected to any customer profile, which is not recommended.

To connect a session to a profile, let's set the profile_id property of the session to the value of the customer profile id:

# Create the customer profile.customer_profile_id = "customer-1234"body = talon_one.NewCustomerProfile(    {"Name": "Anthony Ray", "ShippingCity": "Seattle", "ShippingRegion": "Washington"})api_response = integration_api.update_customer_profile_v2(customer_profile_id, body)
# Create customer session payloadcustomer_session = talon_one.NewCustomerSessionV2()# Add the profile id# This is how we bind the session to the profilecustomer_session.profile_id = customer_profile_id# Create the requestintegration_request = talon_one.IntegrationRequest(customer_session)# Execute the requestapi_response = integration_api.update_customer_session_v2(    "my_session_id", integration_request)

Closing the session#

We've seen how to create a session, bind it to a customer profile, and add custom attributes to it. At the end of the order workflow, in our case the payment step, we have to close the session. Doing so increments campaign budget limit counters, redeem potential coupons, etc.

To close the session, we update the state property to closed:

# Reuse our previous customer_session object# and update the statecustomer_session.state = "closed"# Create the requestintegration_request = talon_one.IntegrationRequest(customer_session)# Execute the requestapi_response = integration_api.update_customer_session_v2(    "my_session_id", integration_request)

For more information about how to manage sessions, see Managing session states.