Skip to main content

Creating custom coupons

A number of use cases may require creating custom coupons using the Management API. Custom coupons are coupons with custom attributes that we can leverage to tweak the coupons' 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's requests to the UpdateCustomerProfile endpoint.

In 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 integration 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
}
note

BEARER_TOKEN comes from the Create session endpoint.

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 can dynamically assign the profile ID to the BelongsToProfileId attribute.

One 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>"
    }
}
note

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 now has 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.