12th Apr 2021

Creating Custom Coupons

A number of use cases may require creating adaptive coupons using the Management API. This guide shows you how you can programmatically create coupons with attributes to configure their behaviour.

Understanding the context

Let's consider a campaign that rewards individual customers with a personal coupon code. To do this, our campaign rule needs to contain a coupon belongs to the current user logic. This logic relies on adding an attribute to each coupon that carry the information about which profile it belongs to. In short, we must match a coupon to a profile id.

Note about the profile id: The profile id originally comes from the integration layer, when the integration calls the UpdateCustomerProfile endpoint. Inside Talon.One, you can find its value in the customer profile entity's IntegrationId or in the customer session entity's profileId, if the session is linked to the customer profile. For more information, see the tutorial.

Creating the custom attribute programmatically

Let's start by creating the custom attribute for our coupons. We can do this using the Campaign Manager's UI or programmatically using the Management API. Let's do it via the API.

We can name the attribute BelongsToProfileId and bind it to the coupons entity. To create it, let's use the Create attribute endpoint with the following curl example:

curl --location --request POST 'https://[YOUR_DEPLOYMENT].talon.one/v1/attributes' \
--header 'Authorization: Bearer [BEARER_TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "entity": "Coupon",
    "name": "BelongsToProfileId",
    "title": "BelongsToProfileId",
    "type": "string",
    "description": "The value of the profile id that owns this coupon.",
    "suggestions": [],
    "editable": true
}

The custom attribute is created, we can use it in our coupons.

Creating the coupons programmatically

To create the coupons programmatically, we use the Create coupons endpoint. We can add the attributes object to the payload to set custom attributes.

In our case, we would dynamically assign the profile id to the BelongsToProfileId attribute.

The request looks like this:

curl --location --request POST 'https://[YOUR_DEPLOYMENT].talon.one/v1/applications/[APPLICATION_ID]/campaigns/[CAMPAIGN_ID]/coupons' \
--header 'Authorization: Bearer [BEARER_TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "usageLimit": 1,
    "couponPattern": "###-###-###",
    "numberOfCoupons": 1,
    "attributes":{
        "BelongsToProfileId": "<myProfileId>"
    }
}

Notice the usageLimit property set to 1 and the attributes object. <myProfileId> is owned by the integration layer, so we assume that the code around this call would set the value.

This is how we can set custom attributes on coupons programmatically. We can also use one of the available SDKs.

Creating the rule

Talon.One has now all the data required for our workflow, we can use this data in a rule.

The identifier of the customer is represented by the Session.ProfileId and the Profile.IntegrationId. These are identical.

Our rule is:

- Integration ID (Customer profile) is equal to BelongsToProfileId (Coupon)
- Coupon code is valid
  • Integration ID (Customer profile) is a built-in attribute set by the integration layer.
  • BelongsToProfileId is the custom attribute we created.
Still need help? Get in touch!
Last updated on 12th Apr 2021

Was this article helpful?

Thank you! You have already voted

If you’d like a member of our support team to respond to you, please send a note to support@talon.one