Download OpenAPI specification:Download
The Management API allows you to programmatically do what the Campaign Manager does. For example, use it for management purposes and backoffice systems.
For more background information about this API, see Management API overview
Ensure you authenticate to make requests to the API.
Warnings:
Are you looking for a different API?
If you need the API to:
This authentication scheme relies on a bearer token that you can use to access all the endpoints of the Management API.
To create the token:
token
property of the response in the HTTP header of your next queries:
Authorization: Bearer $TOKEN
.A token is valid for 3 months. In accordance with best pratices, use your generated token for all your API requests. Do not regenerate a token for each request.
Note: We recommend that you use a Management API key instead of a bearer token.
Authorization
The API key authentication gives you access to the endpoints selected by the admin who created the key. Using an API key is the recommended authentication method.
The key must be generated by an admin and given to the developer that requires it:
The developer can now use the API key in the HTTP header, prefixing it with ManagementKey-v1
:
Authorization: ManagementKey-v1 bd9479c59e16f9dbc644d33aa74d58270fe13bf3
Authorization
Operations for updating account information such as billing email addresses, inviting users, etc.
Retrieve all users in your account.
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
{- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "modified": "2021-09-12T10:12:42Z",
- "email": "john.doe@example.com",
- "accountId": 3886,
- "name": "John Doe",
- "state": "invited",
- "inviteToken": "Gy9b8w1irmQtEPo5RmbMmSPheL5h4",
- "isAdmin": false,
- "policy": {
- "Role": 127,
- "Applications": null
}, - "roles": [
- 71
], - "authMethod": "basic_auth",
- "applicationNotificationSubscriptions": { },
- "lastSignedIn": "2021-09-12T10:12:42Z",
- "lastAccessed": "2021-09-12T10:14:42Z",
- "latestFeedTimestamp": "2020-06-01T00:00:00Z",
- "additionalAttributes": { }
}
]
}
Retrieve the data (including an invitation code) for a user. Non-admin users can only get their own profile.
userId required | integer Example: 33 The ID of the user. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "modified": "2021-09-12T10:12:42Z",
- "email": "john.doe@example.com",
- "accountId": 3886,
- "name": "John Doe",
- "state": "invited",
- "inviteToken": "Gy9b8w1irmQtEPo5RmbMmSPheL5h4",
- "isAdmin": false,
- "policy": {
- "Role": 127,
- "Applications": null
}, - "roles": [
- 71
], - "authMethod": "basic_auth",
- "applicationNotificationSubscriptions": { },
- "lastSignedIn": "2021-09-12T10:12:42Z",
- "lastAccessed": "2021-09-12T10:14:42Z",
- "latestFeedTimestamp": "2020-06-01T00:00:00Z",
- "additionalAttributes": { }
}
Update the details of a specific user.
userId required | integer Example: 33 The ID of the user. |
body
name | string Name of the user. |
state | string Enum: "deactivated" "active" The state of the user.
Note: Only |
isAdmin | boolean Indicates whether the user is an |
policy | string Indicates the access level of the user. |
roles | Array of integers A list of the IDs of the roles assigned to the user. Note: To find the ID of a role, use the List roles endpoint. |
applicationNotificationSubscriptions | object Application notifications that the user is subscribed to. |
{- "name": "John Doe",
- "state": "deactivated",
- "isAdmin": false,
- "policy": {
- "Role": 127,
- "Applications": null
}, - "roles": [
- 1,
- 3
], - "applicationNotificationSubscriptions": { }
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "modified": "2021-09-12T10:12:42Z",
- "email": "john.doe@example.com",
- "accountId": 3886,
- "name": "John Doe",
- "state": "invited",
- "inviteToken": "Gy9b8w1irmQtEPo5RmbMmSPheL5h4",
- "isAdmin": false,
- "policy": {
- "Role": 127,
- "Applications": null
}, - "roles": [
- 71
], - "authMethod": "basic_auth",
- "applicationNotificationSubscriptions": { },
- "lastSignedIn": "2021-09-12T10:12:42Z",
- "lastAccessed": "2021-09-12T10:14:42Z",
- "latestFeedTimestamp": "2020-06-01T00:00:00Z",
- "additionalAttributes": { }
}
Delete a specific user.
userId required | integer Example: 33 The ID of the user. |
Validate the ownership of the API through a challenge-response mechanism.
This challenger endpoint is used by Okta to confirm that communication between Talon.One and Okta is correctly configured and accessible for provisioning and deprovisioning of Talon.One users, and that only Talon.One can receive and respond to events from Okta.
Retrieve a paginated list of groups created using the SCIM protocol with an identity provider, for example, Microsoft Entra ID.
In Talon.One, a Group
corresponds to a role, and members
are the users assigned to that role.
{- "Resources": [
- {
- "displayName": "Manager Role",
- "id": "283",
- "meta": {
- "resourceType": "Group",
- "created": "2024-06-25T17:43:46+02:00"
}, - "members": [
- {
- "value": "15",
- "display": "john.doe@example.com"
}
], - "schemas": [
- "urn:ietf:params:scim:schemas:core:2.0:Group"
]
}
], - "schemas": [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
], - "totalResults": 1
}
Create a new Talon.One group using the SCIM Group provisioning protocol with an identity provider, for example, Microsoft Entra ID, and assign members from the payload to the new group.
In Talon.One, a Group
corresponds to a role, and members
are the users assigned to that role.
body
displayName | string Display name of the group (Talon.One role). | ||||
Array of objects List of members to assign to the new Talon.One role. | |||||
Array
|
{- "displayName": "Manager",
- "members": [
- {
- "value": "258",
- "display": "john.doe@example.com"
}
]
}
{- "displayName": "Manager",
- "members": [
- {
- "value": "258",
- "display": "john.doe@example.com"
}
], - "id": "359"
}
Retrieve data for a specific group created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
In Talon.One, a Group
corresponds to a role, and members
are the users assigned to that role.
groupId required | integer Example: 44 The ID of the group. |
{- "displayName": "Manager",
- "members": [
- {
- "value": "258",
- "display": "john.doe@example.com"
}
], - "id": "359"
}
Delete a specific group created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
In Talon.One, a Group
corresponds to a role, and members
are the users assigned to that role.
groupId required | integer Example: 44 The ID of the group. |
Update the details of a specific group created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID. This endpoint replaces all attributes of the given group with the attributes provided in the request payload.
In Talon.One, a Group
corresponds to a role, and members
are the users assigned to that role.
groupId required | integer Example: 44 The ID of the group. |
body
displayName | string Display name of the group (Talon.One role). | ||||
Array of objects List of members to assign to the new Talon.One role. | |||||
Array
|
{- "displayName": "Manager",
- "members": [
- {
- "value": "258",
- "display": "john.doe@example.com"
}
]
}
{- "displayName": "Manager",
- "members": [
- {
- "value": "258",
- "display": "john.doe@example.com"
}
], - "id": "359"
}
Update certain attributes of a group created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID. This endpoint allows for selective adding, removing, or replacing of specific group attributes while other attributes remain unchanged.
In Talon.One, a Group
corresponds to a role, and members
are the users assigned to that role.
groupId required | integer Example: 44 The ID of the group. |
body
required | Array of objects | ||||||
Array
| |||||||
schemas | Array of strings SCIM schema for the given resource. |
{- "Operations": [
- {
- "op": "replace",
- "path": "active",
- "value": "test"
}, - {
- "op": "add",
- "path": "nickName",
- "value": "johndoe"
}
], - "schemas": [
- "urn:ietf:params:scim:api:messages:2.0:PatchOp"
]
}
{- "displayName": "Manager",
- "members": [
- {
- "value": "258",
- "display": "john.doe@example.com"
}
], - "id": "359"
}
Retrieve a paginated list of users that have been provisioned using the SCIM protocol with an identity provider, for example, Microsoft Entra ID.
{- "Resources": [
- {
- "active": true,
- "displayName": "John Doe",
- "id": "283",
- "meta": {
- "resourceType": "User",
- "created": "2024-06-25T17:43:46+02:00"
}, - "userName": "john.doe@example.com",
- "schemas": [
- "urn:ietf:params:scim:schemas:core:2.0:User",
- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
]
}
], - "schemas": [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
], - "totalResults": 1
}
Create a new Talon.One user using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
body
userName required | string Unique identifier of the user. This is usually an email address. | ||
active | boolean Status of the user. | ||
displayName | string Display name of the user. | ||
object The components of the user’s real name. | |||
|
{- "active": true,
- "displayName": "John Doe",
- "userName": "john.doe@example.com",
- "name": {
- "formatted": "Mr. John J Doe"
}
}
{- "active": true,
- "displayName": "John Doe",
- "userName": "john.doe@example.com",
- "name": {
- "formatted": "Mr. John J Doe"
}, - "id": "359"
}
Retrieve data for a specific Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
userId required | integer Example: 33 The ID of the user. |
{- "active": true,
- "displayName": "John Doe",
- "userName": "john.doe@example.com",
- "name": {
- "formatted": "Mr. John J Doe"
}, - "id": "359"
}
Delete a specific Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
userId required | integer Example: 33 The ID of the user. |
Update the details of a specific Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
This endpoint replaces all attributes of the specific user with the attributes provided in the request payload.
userId required | integer Example: 33 The ID of the user. |
body
userName required | string Unique identifier of the user. This is usually an email address. | ||
active | boolean Status of the user. | ||
displayName | string Display name of the user. | ||
object The components of the user’s real name. | |||
|
{- "active": true,
- "displayName": "John Doe",
- "userName": "john.doe@example.com",
- "name": {
- "formatted": "Mr. John J Doe"
}
}
{- "active": true,
- "displayName": "John Doe",
- "userName": "john.doe@example.com",
- "name": {
- "formatted": "Mr. John J Doe"
}, - "id": "359"
}
Update certain attributes of a specific Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
This endpoint allows for selective adding, removing, or replacing specific attributes while leaving other attributes unchanged.
userId required | integer Example: 33 The ID of the user. |
body
required | Array of objects | ||||||
Array
| |||||||
schemas | Array of strings SCIM schema for the given resource. |
{- "Operations": [
- {
- "op": "replace",
- "path": "active",
- "value": "test"
}, - {
- "op": "add",
- "path": "nickName",
- "value": "johndoe"
}
], - "schemas": [
- "urn:ietf:params:scim:api:messages:2.0:PatchOp"
]
}
{- "active": true,
- "displayName": "John Doe",
- "userName": "john.doe@example.com",
- "name": {
- "formatted": "Mr. John J Doe"
}, - "id": "359"
}
Retrieve a list of resource types supported by the SCIM provisioning protocol.
Resource types define the various kinds of resources that can be managed via the SCIM API, such as users, groups, or custom-defined resources.
{- "Resources": [
- {
- "id": "User",
- "name": "User",
- "description": "User Account"
}
]
}
Retrieve the configuration settings of the SCIM service provider. It provides details about the features and capabilities supported by the SCIM API, such as the different operation settings.
{- "bulk": {
- "maxOperations": 1000,
- "maxPayloadSize": 1048576,
- "supported": true
}, - "changePassword": {
- "supported": false
}, - "documentationUri": "example.com/scim/docs",
- "filter": {
- "maxResults": 100,
- "supported": true
}, - "patch": {
- "supported": true
}, - "schemas": [
- "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
], - "x-sort": {
- "supported": false
}
}
Retrieve a list of schemas supported by the SCIM provisioning protocol.
Schemas define the structure and attributes of the different resources that can be managed via the SCIM API, such as users, groups, and any custom-defined resources.
{- "Resources": [
- {
- "id": "urn:ietf:params:scim:schemas:core:2.0:User",
- "name": "User",
- "description": "User Account",
- "attributes": [
- {
- "name": "userName",
- "required": true,
- "mutability": "readWrite"
}, - {
- "name": "profileUrl",
- "required": false,
- "mutability": "readWrite"
}
]
}
], - "schemas": [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
], - "totalResults": 0
}
Delete a specific user by their email address.
body
email required | string <email> The email address associated with the user profile. |
{- "email": "john.doe@example.com"
}
Enable a disabled user by their email address.
body
email required | string <email> The email address associated with the user profile. |
{- "email": "john.doe@example.com"
}
Disable a specific user by their email address.
body
email required | string <email> The email address associated with the user profile. |
{- "email": "john.doe@example.com"
}
Invite a user from an external identity provider to Talon.One by sending an invitation to their email address.
body
email required | string <email> Email address of the user. |
name | string Name of the user. |
userGroups | Array of strings List of user groups in the external identity provider. If there are roles in Talon.One whose names match these user groups, those roles will be automatically assigned to the user upon invitation. |
{- "name": "John Doe",
- "userGroups": [
- "Managers",
- "Customer support"
], - "email": "john.doe@example.com"
}
Create a new user in the account and send an invitation to their email address.
Note: The invitation token is valid for 24 hours after the email has been sent. You can resend an invitation to a user with the Resend invitation email endpoint.
body
email required | string <email> Email address of the user. |
name | string Name of the user. |
isAdmin | boolean Indicates whether the user is an |
roles | Array of integers A list of the IDs of the roles assigned to the user. |
acl | string Indicates the access level of the user. |
{- "name": "John Doe",
- "email": "john.doe@example.com",
- "isAdmin": false,
- "roles": [
- 13
], - "acl": "string"
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "modified": "2021-09-12T10:12:42Z",
- "email": "john.doe@example.com",
- "accountId": 3886,
- "name": "John Doe",
- "state": "invited",
- "inviteToken": "Gy9b8w1irmQtEPo5RmbMmSPheL5h4",
- "isAdmin": false,
- "policy": {
- "Role": 127,
- "Applications": null
}, - "roles": [
- 71
], - "authMethod": "basic_auth",
- "applicationNotificationSubscriptions": { },
- "lastSignedIn": "2021-09-12T10:12:42Z",
- "lastAccessed": "2021-09-12T10:14:42Z",
- "latestFeedTimestamp": "2020-06-01T00:00:00Z",
- "additionalAttributes": { }
}
Resend an email invitation to an existing user.
Note: The invitation token is valid for 24 hours after the email has been sent.
body
email required | string <email> Email address of the user. |
token required | string Invitation token of the user. |
{- "email": "john.doe@example.com",
- "token": "Gy9b8w1irmQtEPo5RmbMmSPheL5h4"
}
{- "email": "john.doe@example.com",
- "token": "Gy9b8w1irmQtEPo5RmbMmSPheL5h4"
}
Send an email with a password recovery link to the email address of an existing account.
Note: The password recovery link expires 30 minutes after this endpoint is triggered.
body
email required | string <email> non-empty |
{- "email": "user@example.com"
}
{- "email": "user@example.com"
}
Consumes the supplied password reset token and updates the password for the associated account.
body
password required | string The new password for your account. |
resetToken required | string non-empty |
{- "password": "Admin&12943!7",
- "resetToken": "Z2VgacVNkexLKBUIzsRDDZSGxnIkC53y"
}
{- "password": "Admin&12943!7",
- "resetToken": "Z2VgacVNkexLKBUIzsRDDZSGxnIkC53y"
}
Return the details of your companies Talon.One account.
accountId required | integer Example: 28 The identifier of the account. Retrieve it via the
List users in account endpoint in the |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "modified": "2021-09-12T10:12:42Z",
- "companyName": "string",
- "domainName": "string",
- "state": "active",
- "billingEmail": "user@example.com",
- "planName": "string",
- "planExpires": "2019-08-24T14:15:22Z",
- "applicationLimit": 0,
- "userLimit": 0,
- "campaignLimit": 0,
- "apiLimit": 0,
- "applicationCount": 0,
- "userCount": 0,
- "campaignsActiveCount": 0,
- "campaignsInactiveCount": 0,
- "attributes": { }
}
Return the analytics of your Talon.One account.
accountId required | integer Example: 28 The identifier of the account. Retrieve it via the
List users in account endpoint in the |
{- "applications": 11,
- "liveApplications": 6,
- "sandboxApplications": 2,
- "campaigns": 35,
- "activeCampaigns": 15,
- "liveActiveCampaigns": 10,
- "coupons": 850,
- "activeCoupons": 650,
- "expiredCoupons": 200,
- "referralCodes": 500,
- "activeReferralCodes": 100,
- "expiredReferralCodes": 400,
- "activeRules": 35,
- "users": 0,
- "roles": 10,
- "customAttributes": 18,
- "webhooks": 2,
- "loyaltyPrograms": 5,
- "liveLoyaltyPrograms": 5,
- "lastUpdatedAt": "2022-12-12T12:12:12Z"
}
Achievements allow you to reward a customer profile for performing a number of specific actions or reaching a transactional milestone within a defined period.
For example, you can use achievements to award your customers when they purchase five cups of coffee in one week or when they purchase items worth $3000 in three months.
Create a new achievement in a specific campaign.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
body
name required | string [ 1 .. 1000 ] characters ^[a-zA-Z]\w+$ The internal name of the achievement used in API requests. Note: The name should start with a letter. This cannot be changed after the achievement has been created. | ||||||||||||
title required | string The display name for the achievement in the Campaign Manager. | ||||||||||||
description required | string <string> A description of the achievement. | ||||||||||||
target required | number The required number of actions or the transactional milestone to complete the achievement. | ||||||||||||
period | string The relative duration after which the achievement ends and resets for a particular customer profile. Note: The The period is a positive real number followed by one letter indicating the time unit. Examples: Available units:
You can also round certain units down to the beginning of period and up to the end of period.:
Note: You can either use the round down and round up option or set an absolute period. | ||||||||||||
object Deprecated The absolute duration after which the achievement ends and resets for a particular customer profile. Note: The duration follows the time zone of the Application this achievement belongs to. | |||||||||||||
| |||||||||||||
recurrencePolicy | string Enum: "no_recurrence" "on_expiration" "on_completion" The policy that determines if and how the achievement recurs.
| ||||||||||||
activationPolicy | string Enum: "user_action" "fixed_schedule" The policy that determines how the achievement starts, ends, or resets.
| ||||||||||||
fixedStartDate | string <date-time> The achievement's start date when Note: It must be an RFC3339 timestamp string. | ||||||||||||
endDate | string <date-time> The achievement's end date. If defined, customers cannot participate in the achievement after this date. Note: It must be an RFC3339 timestamp string. |
{- "name": "Order50Discount",
- "title": "50% off on 50th purchase.",
- "description": "50% off for every 50th purchase in a year.",
- "target": 50,
- "period": "1Y",
- "periodEndOverride": {
- "month": 11,
- "dayOfMonth": 23,
- "hour": 23,
- "minute": 59,
- "second": 59
}, - "recurrencePolicy": "no_recurrence",
- "activationPolicy": "fixed_schedule",
- "fixedStartDate": "2024-01-15T15:04:05Z07:00",
- "endDate": "2024-02-15T15:04:05Z07:00"
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "name": "Order50Discount",
- "title": "50% off on 50th purchase.",
- "description": "50% off for every 50th purchase in a year.",
- "target": 50,
- "period": "1Y",
- "periodEndOverride": {
- "month": 11,
- "dayOfMonth": 23,
- "hour": 23,
- "minute": 59,
- "second": 59
}, - "recurrencePolicy": "no_recurrence",
- "activationPolicy": "fixed_schedule",
- "fixedStartDate": "2024-01-15T15:04:05Z07:00",
- "endDate": "2024-02-15T15:04:05Z07:00",
- "campaignId": 1,
- "userId": 1234,
- "createdBy": "John Doe",
- "hasProgress": true,
- "status": "inprogress"
}
List all the achievements for a specific campaign.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
pageSize | integer [ 1 .. 50 ] Default: 50 Example: pageSize=50 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
title | string Example: title=achievement1 Filter by the display name for the achievement in the campaign manager. Note: If no |
{- "hasMore": true,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "name": "Order50Discount",
- "title": "50% off on 50th purchase.",
- "description": "50% off for every 50th purchase in a year.",
- "target": 50,
- "period": "1Y",
- "periodEndOverride": {
- "month": 11,
- "dayOfMonth": 23,
- "hour": 23,
- "minute": 59,
- "second": 59
}, - "recurrencePolicy": "no_recurrence",
- "activationPolicy": "fixed_schedule",
- "fixedStartDate": "2024-01-15T15:04:05Z07:00",
- "endDate": "2024-02-15T15:04:05Z07:00",
- "campaignId": 1,
- "userId": 1234,
- "createdBy": "John Doe",
- "hasProgress": true,
- "status": "inprogress"
}
]
}
Get the details of a specific achievement.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
achievementId required | integer Example: 45 The ID of the achievement. You can get this ID with the List achievement endpoint. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "name": "Order50Discount",
- "title": "50% off on 50th purchase.",
- "description": "50% off for every 50th purchase in a year.",
- "target": 50,
- "period": "1Y",
- "periodEndOverride": {
- "month": 11,
- "dayOfMonth": 23,
- "hour": 23,
- "minute": 59,
- "second": 59
}, - "recurrencePolicy": "no_recurrence",
- "activationPolicy": "fixed_schedule",
- "fixedStartDate": "2024-01-15T15:04:05Z07:00",
- "endDate": "2024-02-15T15:04:05Z07:00",
- "campaignId": 1,
- "userId": 1234,
- "createdBy": "John Doe",
- "hasProgress": true,
- "status": "inprogress"
}
Update the details of a specific achievement.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
achievementId required | integer Example: 45 The ID of the achievement. You can get this ID with the List achievement endpoint. |
body
name | string [ 1 .. 1000 ] characters ^[a-zA-Z]\w+$ The internal name of the achievement used in API requests. Note: The name should start with a letter. This cannot be changed after the achievement has been created. | ||||||||||||
title | string The display name for the achievement in the Campaign Manager. | ||||||||||||
description | string <string> A description of the achievement. | ||||||||||||
target | number The required number of actions or the transactional milestone to complete the achievement. | ||||||||||||
period | string The relative duration after which the achievement ends and resets for a particular customer profile. Note: The The period is a positive real number followed by one letter indicating the time unit. Examples: Available units:
You can also round certain units down to the beginning of period and up to the end of period.:
Note: You can either use the round down and round up option or set an absolute period. | ||||||||||||
object Deprecated The absolute duration after which the achievement ends and resets for a particular customer profile. Note: The duration follows the time zone of the Application this achievement belongs to. | |||||||||||||
| |||||||||||||
recurrencePolicy | string Enum: "no_recurrence" "on_expiration" "on_completion" The policy that determines if and how the achievement recurs.
| ||||||||||||
activationPolicy | string Enum: "user_action" "fixed_schedule" The policy that determines how the achievement starts, ends, or resets.
| ||||||||||||
fixedStartDate | string <date-time> The achievement's start date when Note: It must be an RFC3339 timestamp string. | ||||||||||||
endDate | string <date-time> The achievement's end date. If defined, customers cannot participate in the achievement after this date. Note: It must be an RFC3339 timestamp string. |
{- "name": "Order50Discount",
- "title": "50% off on 50th purchase.",
- "description": "50% off for every 50th purchase in a year.",
- "target": 50,
- "period": "1Y",
- "periodEndOverride": {
- "month": 11,
- "dayOfMonth": 23,
- "hour": 23,
- "minute": 59,
- "second": 59
}, - "recurrencePolicy": "no_recurrence",
- "activationPolicy": "fixed_schedule",
- "fixedStartDate": "2024-01-15T15:04:05Z07:00",
- "endDate": "2024-02-15T15:04:05Z07:00"
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "name": "Order50Discount",
- "title": "50% off on 50th purchase.",
- "description": "50% off for every 50th purchase in a year.",
- "target": 50,
- "period": "1Y",
- "periodEndOverride": {
- "month": 11,
- "dayOfMonth": 23,
- "hour": 23,
- "minute": 59,
- "second": 59
}, - "recurrencePolicy": "no_recurrence",
- "activationPolicy": "fixed_schedule",
- "fixedStartDate": "2024-01-15T15:04:05Z07:00",
- "endDate": "2024-02-15T15:04:05Z07:00",
- "campaignId": 1,
- "userId": 1234,
- "createdBy": "John Doe",
- "hasProgress": true,
- "status": "inprogress"
}
Delete the specified achievement.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
achievementId required | integer Example: 45 The ID of the achievement. You can get this ID with the List achievement endpoint. |
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
Download a CSV file containing a list of all the customers who have participated in and are currently participating in the given achievement.
The CSV file contains the following columns:
profileIntegrationID
: The integration ID of the customer profile participating in the achievement.title
: The display name of the achievement in the Campaign Manager.target
: The required number of actions or the transactional milestone to complete the achievement.progress
: The current progress of the customer in the achievement.status
: The status of the achievement. Can be one of: ['inprogress', 'completed', 'expired'].startDate
: The date on which the customer profile started the achievement in RFC3339.endDate
: The date on which the achievement ends and resets for the customer profile in RFC3339.completionDate
: The date on which the customer profile completed the achievement in RFC3339.applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
achievementId required | integer Example: 45 The ID of the achievement. You can get this ID with the List achievement endpoint. |
profileIntegrationID,title,target,progress,status,startDate,endDate,completionDate user1231,CoffeeFree10Orders,10.00,5,inprogress,2023-12-10T11:42:25+01:00,2024-01-10T11:42:25+01:00, user341,CoffeeFree10Orders,10.00,10,completed,2023-12-10T11:42:25+01:00,2024-01-10T11:42:25+01:00,2023-12-20T10:24:34+01:00
For the given customer profile, list all the achievements that match your filter criteria.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
integrationId required | string Example: customer1 The integration identifier for this customer profile. Must be:
Once set, you cannot update this identifier. |
pageSize | integer [ 1 .. 50 ] Default: 50 Example: pageSize=50 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
achievementId | integer Example: achievementId=41 The ID of the achievement. You can get this ID with the List achievement endpoint. |
title | string Example: title=achievement1 Filter results by the |
{- "hasMore": true,
- "data": [
- {
- "status": "completed",
- "progress": 10,
- "startDate": "2024-01-01T15:04:05Z07:00",
- "completionDate": "2024-01-15T15:04:05Z07:00",
- "endDate": "2024-02-01T15:04:05Z07:00",
- "achievementId": 3,
- "name": "FreeCoffee10Orders",
- "title": "50% off on 50th purchase.",
- "description": "50% off for every 50th purchase in a year.",
- "campaignId": 3,
- "target": 10,
- "achievementRecurrencePolicy": "no_recurrence",
- "achievementActivationPolicy": "fixed_schedule",
- "achievementFixedStartDate": "2024-01-15T15:04:05Z07:00",
- "achievementEndDate": "2024-02-15T15:04:05Z07:00"
}
]
}
An extra fee applied to the cart. For example, shipping fees or processing fees.
See the docs.
Create an additional cost.
These additional costs are shared across all applications in your account, and are never required.
body
name required | string^[A-Za-z]\w*$ The internal name used in API requests. |
title required | string^[A-Za-z][A-Za-z0-9_.!~*'() -]*$ The human-readable name for the additional cost that will be shown in the Campaign Manager. Like |
description required | string A description of this additional cost. |
subscribedApplicationsIds | Array of integers A list of the IDs of the applications that are subscribed to this additional cost. |
type | string Default: "session" Enum: "session" "item" "both" The type of additional cost. Possible value:
|
{- "name": "shippingFee",
- "title": "Shipping fee",
- "description": "A shipping fee",
- "subscribedApplicationsIds": [
- 3,
- 13
], - "type": "session"
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "name": "shippingFee",
- "title": "Shipping fee",
- "description": "A shipping fee",
- "subscribedApplicationsIds": [
- 3,
- 13
], - "type": "session"
}
Returns all the defined additional costs for the account.
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
{- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "name": "shippingFee",
- "title": "Shipping fee",
- "description": "A shipping fee",
- "subscribedApplicationsIds": [
- 3,
- 13
], - "type": "session"
}
]
}
Returns the additional cost.
additionalCostId required | integer Example: 2 The ID of the additional cost. You can find the ID the the Campaign Manager's URL when you display the details of the cost in Account > Tools > Additional costs. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "name": "shippingFee",
- "title": "Shipping fee",
- "description": "A shipping fee",
- "subscribedApplicationsIds": [
- 3,
- 13
], - "type": "session"
}
Updates an existing additional cost. Once created, the only property of an additional cost that cannot be changed is the name
property (or API name in the Campaign Manager). This restriction is in place to prevent accidentally breaking live integrations.
additionalCostId required | integer Example: 2 The ID of the additional cost. You can find the ID the the Campaign Manager's URL when you display the details of the cost in Account > Tools > Additional costs. |
body
name required | string^[A-Za-z]\w*$ The internal name used in API requests. |
title required | string^[A-Za-z][A-Za-z0-9_.!~*'() -]*$ The human-readable name for the additional cost that will be shown in the Campaign Manager. Like |
description required | string A description of this additional cost. |
subscribedApplicationsIds | Array of integers A list of the IDs of the applications that are subscribed to this additional cost. |
type | string Default: "session" Enum: "session" "item" "both" The type of additional cost. Possible value:
|
{- "name": "shippingFee",
- "title": "Shipping fee",
- "description": "A shipping fee",
- "subscribedApplicationsIds": [
- 3,
- 13
], - "type": "session"
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "name": "shippingFee",
- "title": "Shipping fee",
- "description": "A shipping fee",
- "subscribedApplicationsIds": [
- 3,
- 13
], - "type": "session"
}
Analytics are used to retrieve statistical data about the performance of campaigns within an Application.
Download a CSV file containing the triggered effects that match the given attributes.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
The generated file can contain the following columns:
applicationid
: The ID of the Application.campaignid
: The ID of the campaign.couponid
: The ID of the coupon, when applicable to the effect.created
: The timestamp of the effect.event_type
: The name of the event. See the docs.eventid
: The internal ID of the effect.name
: The effect name. See the docs.profileintegrationid
: The ID of the customer profile, when applicable.props
: The properties of the effect.ruleindex
: The index of the rule.rulesetid
: The ID of the rule set.sessionid
: The internal ID of the session that triggered the effect.profileid
: The internal ID of the customer profile.sessionintegrationid
: The integration ID of the session.total_revenue
: The total revenue.store_integration_id
: The integration ID of the store. You choose this ID when you create a store.applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId | number Example: campaignId=49 Filter results by campaign ID. |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string. You can use any time zone setting. Talon.One will convert to UTC internally. |
createdAfter | string <date-time> Example: createdAfter=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string. You can use any time zone setting. Talon.One will convert to UTC internally. |
dateFormat | string Enum: "excel" "ISO8601" Example: dateFormat=excel Determines the format of dates in the export document. |
created,name,applicationid,campaignid,rulesetid,ruleindex,sessionintegrationid,profileintegrationid,sessionid,profileid,eventid,event_type,total_revenue,props,couponid,store_id,store_integration_id 2021-06-02T21:14:16Z,rejectCoupon,270,0,0,0,newsession1,,9168,0,95797,talon_session_created,265.00,"{""value"": ""XMAS20"", ""rejectionReason"": ""CouponNotFound""}",,115,STORE-001 2021-09-01T13:04:04Z,setDiscountPerItem,270,3882,13599,0,test_flattening_2,integid_4,9707,4800,98806,talon_session_updated,405.00,"{""name"": ""10% off per item#1"", ""value"": 11.0, ""position"": 1}",,116,STORE-002
Download a CSV file containing the customer sessions that match the request.
Important: Archived sessions cannot be exported. See the retention policy.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
id
: The internal ID of the session.firstsession
: Whether this is a first session.integrationid
: The integration ID of the session.applicationid
: The ID of the Application.profileid
: The internal ID of the customer profile.profileintegrationid
: The integration ID of the customer profile.created
: The timestamp when the session was created.state
: The state of the session.cartitems
: The cart items in the session.discounts
: The discounts in the session.total
: The total value of cart items and additional costs in the session, before any discounts are applied.attributes
: The attributes set in the session.closedat
: Timestamp when the session was closed.cancelledat
: Timestamp when the session was cancelled.referral
: The referral code in the session.identifiers
: The identifiers in the session.additional_costs
: The additional costs in the session.updated
: Timestamp of the last session update.store_integration_id
: The integration ID of the store.coupons
: Coupon codes in the session.applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string. |
createdAfter | string <date-time> Example: createdAfter=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string. |
profileIntegrationId | string Example: profileIntegrationId=customer1 Only return sessions for the customer that matches this customer integration ID. |
dateFormat | string Enum: "excel" "ISO8601" Example: dateFormat=excel Determines the format of dates in the export document. |
customerSessionState | string Enum: "open" "closed" "partially_returned" "cancelled" Example: customerSessionState=open Filter results by state. |
id,firstsession,integrationid,applicationid,profileid,profileintegrationid,created,state,cartitems,discounts,total,attributes,closedat,cancelledat,referral,identifiers,additional_costs,updated,store_integration_id,coupons 12328,true,62791173fbf323ee5cfd96f3,270,6111,dxclwds,2022-05-09T13:05:31Z,open,"[{""sku"": ""B00004TKVY"", ""name"": ""Gravel bike - \""Aisle of Man\"""", ""price"": 1800, ""weight"": 6, ""category"": ""gravelbikes"", ""position"": 0, ""quantity"": 1, ""attributes"": {""color"": [""black,white""], ""material"": ""titanium""}, ""returnedQuantity"": 0, ""remainingQuantity"": 1}]","{}",1850.00,"{""ShippingCost"": 50, ""PaymentMethod"": ""creditcard"", ""ShippingMethod"": ""Standard""}",0001-01-01T00:00:00Z,0001-01-01T00:00:00Z,,"null","{""ShippingCost"": {""price"": 50}}",2022-05-09T13:13:28Z,"STORE-001","[""SORRY5QMUJRWA""]"
Represents an Application in the Campaign Manager. An Application is the target of every Integration API request to Talon.One.
One Application can hold various API keys used for Integration API requests.
You may have multiple Applications within one account, for example staging and production, or different international markets.
See the docs.
List all applications in the current account.
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
{- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "modified": "2021-09-12T10:12:42Z",
- "accountId": 3886,
- "name": "My Application",
- "description": "A test Application",
- "timezone": "Europe/Berlin",
- "currency": "EUR",
- "caseSensitivity": "sensitive",
- "attributes": { },
- "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "defaultDiscountScope": "sessionTotal",
- "enableCascadingDiscounts": true,
- "enableFlattenedCartItems": true,
- "attributesSettings": {
- "mandatory": {
- "campaigns": [
- "string"
], - "coupons": [
- "string"
]
}
}, - "sandbox": true,
- "enablePartialDiscounts": false,
- "defaultDiscountAdditionalCostPerItemScope": "price",
- "defaultEvaluationGroupId": 3,
- "defaultCartItemFilterId": 3,
- "enableCampaignStateManagement": false,
- "loyaltyPrograms": [
- {
- "id": 139,
- "created": "2020-06-10T09:05:27.993483Z",
- "title": "Point collection",
- "description": "Customers collect 10 points per 1$ spent",
- "subscribedApplications": [
- 132,
- 97
], - "defaultValidity": "2W_U",
- "defaultPending": "immediate",
- "allowSubledger": false,
- "usersPerCardLimit": 111,
- "sandbox": true,
- "programJoinPolicy": "not_join",
- "tiersExpirationPolicy": "tier_start_date",
- "tierCycleStartDate": "2021-09-12T10:12:42Z",
- "tiersExpireIn": "27W_U",
- "tiersDowngradePolicy": "one_down",
- "cardCodeSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "returnPolicy": "only_pending",
- "accountID": 1,
- "name": "my_program",
- "tiers": [
- {
- "name": "Gold",
- "minPoints": 300,
- "id": 3,
- "created": "2021-06-10T09:05:27.993483Z",
- "programID": 139
}, - {
- "name": "Silver",
- "minPoints": 200,
- "id": 2,
- "created": "2021-06-10T09:04:59.355258Z",
- "programID": 139
}, - {
- "name": "Bronze",
- "minPoints": 100,
- "id": 1,
- "created": "2021-06-10T09:04:39.355258Z",
- "programID": 139
}
], - "timezone": "Europe/Berlin",
- "cardBased": true,
- "canUpdateTiers": true,
- "canUpdateJoinPolicy": true,
- "canUpdateTierExpirationPolicy": true,
- "canUpgradeToAdvancedTiers": true,
- "canUpdateSubledgers": true
}
]
}
]
}
Get the application specified by the ID.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "modified": "2021-09-12T10:12:42Z",
- "accountId": 3886,
- "name": "My Application",
- "description": "A test Application",
- "timezone": "Europe/Berlin",
- "currency": "EUR",
- "caseSensitivity": "sensitive",
- "attributes": { },
- "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "defaultDiscountScope": "sessionTotal",
- "enableCascadingDiscounts": true,
- "enableFlattenedCartItems": true,
- "attributesSettings": {
- "mandatory": {
- "campaigns": [
- "string"
], - "coupons": [
- "string"
]
}
}, - "sandbox": true,
- "enablePartialDiscounts": false,
- "defaultDiscountAdditionalCostPerItemScope": "price",
- "defaultEvaluationGroupId": 3,
- "defaultCartItemFilterId": 3,
- "enableCampaignStateManagement": false,
- "loyaltyPrograms": [
- {
- "id": 139,
- "created": "2020-06-10T09:05:27.993483Z",
- "title": "Point collection",
- "description": "Customers collect 10 points per 1$ spent",
- "subscribedApplications": [
- 132,
- 97
], - "defaultValidity": "2W_U",
- "defaultPending": "immediate",
- "allowSubledger": false,
- "usersPerCardLimit": 111,
- "sandbox": true,
- "programJoinPolicy": "not_join",
- "tiersExpirationPolicy": "tier_start_date",
- "tierCycleStartDate": "2021-09-12T10:12:42Z",
- "tiersExpireIn": "27W_U",
- "tiersDowngradePolicy": "one_down",
- "cardCodeSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "returnPolicy": "only_pending",
- "accountID": 1,
- "name": "my_program",
- "tiers": [
- {
- "name": "Gold",
- "minPoints": 300,
- "id": 3,
- "created": "2021-06-10T09:05:27.993483Z",
- "programID": 139
}, - {
- "name": "Silver",
- "minPoints": 200,
- "id": 2,
- "created": "2021-06-10T09:04:59.355258Z",
- "programID": 139
}, - {
- "name": "Bronze",
- "minPoints": 100,
- "id": 1,
- "created": "2021-06-10T09:04:39.355258Z",
- "programID": 139
}
], - "timezone": "Europe/Berlin",
- "cardBased": true,
- "canUpdateTiers": true,
- "canUpdateJoinPolicy": true,
- "canUpdateTierExpirationPolicy": true,
- "canUpgradeToAdvancedTiers": true,
- "canUpdateSubledgers": true
}
]
}
Display the health of the Application and show the last time the Application was used.
You can also find this information in the Campaign Manager. In your Application, click Settings > Integration API Keys. See the docs.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
{- "summary": "OK",
- "lastUsed": "2021-09-12T10:12:42Z"
}
Represents a piece of information related to one of the entities avaialbe in the Campaign Manager. Use them to create highly customized rules.
See the docs.
Create a custom attribute in this account. Custom attributes allow you to add data to Talon.One domain entities like campaigns, coupons, customers and so on.
These attributes can then be given values when creating/updating these entities, and these values can be used in your campaign rules.
For example, you could define a zipCode
field for customer sessions,
and add a rule to your campaign that only allows certain ZIP codes.
These attributes are shared across all Applications in your account and are never required.
body
entity required | string Enum: "Application" "Campaign" "CustomerProfile" "CustomerSession" "CartItem" "Coupon" "Event" "Giveaway" "Referral" "Store" The name of the entity that can have this attribute. When creating or updating the entities of a given type, you can include an |
name required | string^[A-Za-z]\w*$ The attribute name that will be used in API requests and Talang. E.g. if |
title required | string^[A-Za-z][A-Za-z0-9_.!~*'() -]*$ The human-readable name for the attribute that will be shown in the Campaign Manager. Like |
type required | string Enum: "string" "number" "boolean" "time" "(list string)" "(list number)" "(list time)" "location" "(list location)" The data type of the attribute, a |
description required | string A description of this attribute. |
suggestions required | Array of strings <= 50 items [ items non-empty ] A list of suggestions for the attribute. |
editable required | boolean Whether or not this attribute can be edited. |
eventType | string |
hasAllowedList | boolean Default: false Whether or not this attribute has an allowed list of values associated with it. |
restrictedBySuggestions | boolean Default: false Whether or not this attribute's value is restricted by suggestions ( |
subscribedApplicationsIds | Array of integers A list of the IDs of the applications where this attribute is available. |
subscribedCatalogsIds | Array of integers A list of the IDs of the catalogs where this attribute is available. |
allowedSubscriptions | Array of strings <= 2 items Items Enum: "application" "catalog" A list of allowed subscription types for this attribute. Note: This only applies to attributes associated with the |
{- "entity": "Event",
- "eventType": "pageViewed",
- "name": "pageViewed",
- "title": "Page view event",
- "type": "string",
- "description": "Event triggered when a customer displays a page.",
- "suggestions": [
- "string"
], - "hasAllowedList": false,
- "restrictedBySuggestions": false,
- "editable": true,
- "subscribedApplicationsIds": [
- 1,
- 4,
- 9
], - "subscribedCatalogsIds": [
- 2,
- 5
], - "allowedSubscriptions": [
- "application",
- "catalog"
]
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "entity": "Event",
- "eventType": "pageViewed",
- "name": "pageViewed",
- "title": "Page view event",
- "type": "string",
- "description": "Event triggered when a customer displays a page.",
- "suggestions": [
- "string"
], - "hasAllowedList": false,
- "restrictedBySuggestions": false,
- "editable": true,
- "subscribedApplicationsIds": [
- 1,
- 4,
- 9
], - "subscribedCatalogsIds": [
- 2,
- 5
], - "allowedSubscriptions": [
- "application",
- "catalog"
], - "eventTypeId": 22
}
Return all the custom attributes for the account.
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
entity | string Example: entity=entity1 Returned attributes will be filtered by supplied entity. |
{- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "entity": "Event",
- "eventType": "pageViewed",
- "name": "pageViewed",
- "title": "Page view event",
- "type": "string",
- "description": "Event triggered when a customer displays a page.",
- "suggestions": [
- "string"
], - "hasAllowedList": false,
- "restrictedBySuggestions": false,
- "editable": true,
- "subscribedApplicationsIds": [
- 1,
- 4,
- 9
], - "subscribedCatalogsIds": [
- 2,
- 5
], - "allowedSubscriptions": [
- "application",
- "catalog"
], - "eventTypeId": 22
}
]
}
Retrieve the specified custom attribute.
attributeId required | integer Example: 31 The ID of the attribute. You can find the ID in the Campaign Manager's URL when you display the details of an attribute in Account > Tools > Attributes. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "entity": "Event",
- "eventType": "pageViewed",
- "name": "pageViewed",
- "title": "Page view event",
- "type": "string",
- "description": "Event triggered when a customer displays a page.",
- "suggestions": [
- "string"
], - "hasAllowedList": false,
- "restrictedBySuggestions": false,
- "editable": true,
- "subscribedApplicationsIds": [
- 1,
- 4,
- 9
], - "subscribedCatalogsIds": [
- 2,
- 5
], - "allowedSubscriptions": [
- "application",
- "catalog"
], - "eventTypeId": 22
}
Update an existing custom attribute. Once created, the only property of a custom attribute that can be changed is the description.
To change the type
or name
property of a custom attribute, create a new attribute and
update any relevant integrations and rules to use the new attribute.
attributeId required | integer Example: 31 The ID of the attribute. You can find the ID in the Campaign Manager's URL when you display the details of an attribute in Account > Tools > Attributes. |
body
entity required | string Enum: "Application" "Campaign" "CustomerProfile" "CustomerSession" "CartItem" "Coupon" "Event" "Giveaway" "Referral" "Store" The name of the entity that can have this attribute. When creating or updating the entities of a given type, you can include an |
name required | string^[A-Za-z]\w*$ The attribute name that will be used in API requests and Talang. E.g. if |
title required | string^[A-Za-z][A-Za-z0-9_.!~*'() -]*$ The human-readable name for the attribute that will be shown in the Campaign Manager. Like |
type required | string Enum: "string" "number" "boolean" "time" "(list string)" "(list number)" "(list time)" "location" "(list location)" The data type of the attribute, a |
description required | string A description of this attribute. |
suggestions required | Array of strings <= 50 items [ items non-empty ] A list of suggestions for the attribute. |
editable required | boolean Whether or not this attribute can be edited. |
eventType | string |
hasAllowedList | boolean Default: false Whether or not this attribute has an allowed list of values associated with it. |
restrictedBySuggestions | boolean Default: false Whether or not this attribute's value is restricted by suggestions ( |
subscribedApplicationsIds | Array of integers A list of the IDs of the applications where this attribute is available. |
subscribedCatalogsIds | Array of integers A list of the IDs of the catalogs where this attribute is available. |
allowedSubscriptions | Array of strings <= 2 items Items Enum: "application" "catalog" A list of allowed subscription types for this attribute. Note: This only applies to attributes associated with the |
{- "entity": "Event",
- "eventType": "pageViewed",
- "name": "pageViewed",
- "title": "Page view event",
- "type": "string",
- "description": "Event triggered when a customer displays a page.",
- "suggestions": [
- "string"
], - "hasAllowedList": false,
- "restrictedBySuggestions": false,
- "editable": true,
- "subscribedApplicationsIds": [
- 1,
- 4,
- 9
], - "subscribedCatalogsIds": [
- 2,
- 5
], - "allowedSubscriptions": [
- "application",
- "catalog"
]
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "entity": "Event",
- "eventType": "pageViewed",
- "name": "pageViewed",
- "title": "Page view event",
- "type": "string",
- "description": "Event triggered when a customer displays a page.",
- "suggestions": [
- "string"
], - "hasAllowedList": false,
- "restrictedBySuggestions": false,
- "editable": true,
- "subscribedApplicationsIds": [
- 1,
- 4,
- 9
], - "subscribedCatalogsIds": [
- 2,
- 5
], - "allowedSubscriptions": [
- "application",
- "catalog"
], - "eventTypeId": 22
}
Upload a CSV file containing a list of picklist values for the specified attribute.
The file should be sent as multipart data.
The import replaces the previous list of allowed values for this attribute, if any.
The CSV file must only contain the following column:
item
(required): the values in your allowed list, for example a list of SKU's.An allowed list is limited to 500,000 items.
Example:
item
CS-VG-04032021-UP-50D-10
CS-DV-04042021-UP-49D-12
CS-DG-02082021-UP-50G-07
attributeId required | integer Example: 31 The ID of the attribute. You can find the ID in the Campaign Manager's URL when you display the details of an attribute in Account > Tools > Attributes. |
upFile | string <csv> The file containing the data that is being imported. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "userId": 388,
- "entity": "AttributeAllowedList",
- "amount": 10
}
Represents lists of customer profiles that allow you to target specific groups of customers in your campaigns. Audiences can be synced from customer data platforms or created directly in Talon.One.
See the docs.
Get all audiences created in the account. To create an audience, use Create audience.
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
withTotalResultSize | boolean When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.
|
{- "hasMore": true,
- "totalResultSize": 1,
- "data": [
- {
- "accountId": 3886,
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "name": "Travel audience",
- "sandbox": true,
- "description": "Travel audience 18-27",
- "integration": "mparticle",
- "integrationId": "382370BKDB946",
- "createdIn3rdParty": false,
- "lastUpdate": "2022-04-26T11:02:38Z"
}
]
}
Get a list of audience IDs and their member count.
audienceIds required | string Example: audienceIds=audience1 The IDs of one or more audiences, separated by commas, by which to filter results. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
{- "hasMore": true,
- "data": [
- {
- "audienceId": 1,
- "membersCount": 1234
}
]
}
Get a paginated list of the customer profiles in a given audience.
A maximum of 1000 customer profiles per page is allowed.
audienceId required | integer Example: 10 The ID of the audience. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
profileQuery | string Example: profileQuery=profile1 The filter to select a profile. |
{- "hasMore": true,
- "data": [
- {
- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "integrationId": "URNGV8294NV",
- "attributes": {
- "Language": "english",
- "ShippingCountry": "DE"
}, - "accountId": 31,
- "closedSessions": 3,
- "totalSales": 299.99,
- "loyaltyMemberships": [
- {
- "joined": "2012-03-20T14:15:22Z",
- "loyaltyProgramId": 323414846
}
], - "audienceMemberships": [
- {
- "id": 2,
- "name": "Travel audience"
}
], - "lastActivity": "2020-02-08T14:15:20Z",
- "sandbox": false
}
]
}
Upload a CSV file containing the integration IDs of the members you want to add to an audience.
The file should be sent as multipart data and should contain only the following column (required):
profileintegrationid
: The integration ID of the customer profile.The import replaces the previous list of audience members.
Note: We recommend limiting your file size to 500MB.
Example:
profileintegrationid
charles
alexa
audienceId required | integer Example: 10 The ID of the audience. |
upFile | string <csv> The file containing the data that is being imported. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "userId": 388,
- "entity": "AttributeAllowedList",
- "amount": 10
}
Download a CSV file containing the integration IDs of the members of an audience.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
The file contains the following column:
profileintegrationid
: The integration ID of the customer profile.audienceId required | integer Example: 10 The ID of the audience. |
profileintegrationid URNGV8294NV BZGGC2454PA
Represents the campaign access groups you can create in your Applications to organize your campaigns based on the type of campaign or the team in charge.
See the docs.
List the campaign access groups in the current account.
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
{- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "modified": "2021-09-12T10:12:42Z",
- "accountId": 3886,
- "name": "Europe access group",
- "description": "A group that gives access to all the campaigns for the Europe market.",
- "subscribedApplicationsIds": [
- 1,
- 2,
- 3
], - "campaignIds": [
- 4,
- 6,
- 8
]
}
]
}
Get a campaign access group specified by its ID.
campaignGroupId required | integer Example: 37 The ID of the campaign access group. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "modified": "2021-09-12T10:12:42Z",
- "accountId": 3886,
- "name": "Europe access group",
- "description": "A group that gives access to all the campaigns for the Europe market.",
- "subscribedApplicationsIds": [
- 1,
- 2,
- 3
], - "campaignIds": [
- 4,
- 6,
- 8
]
}
Retrieve a list of campaign templates.
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
state | string Enum: "draft" "enabled" "disabled" Example: state=draft Filter results by the state of the campaign template. |
name | string Example: name=template1 Filter results performing case-insensitive matching against the name of the campaign template. |
tags | string Example: tags=tag1 Filter results performing case-insensitive matching against the tags of the campaign template. When used in conjunction with the "name" query parameter, a logical OR will be performed to search both tags and name for the provided values. |
userId | integer Example: userId=34 Filter results by user ID. |
{- "hasMore": true,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "userId": 388,
- "name": "Discount campaign",
- "description": "This is a template for a discount campaign.",
- "instructions": "Use this template for discount campaigns. Set the campaign properties according to the campaign goals, and don't forget to set an end date.",
- "campaignAttributes": { },
- "couponAttributes": { },
- "state": "draft",
- "activeRulesetId": 5,
- "tags": [
- "discount"
], - "features": [
- "coupons"
], - "couponSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "couponReservationSettings": {
- "reservationLimit": 45,
- "isReservationMandatory": false
}, - "referralSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "templateParams": [
- {
- "name": "discount_value",
- "type": "number",
- "description": "This is a template parameter of type `number`.",
- "attributeId": 42
}
], - "applicationsIds": [
- 1,
- 2,
- 3
], - "campaignCollections": [
- {
- "name": "My collection",
- "description": "My collection of SKUs"
}
], - "defaultCampaignGroupId": 42,
- "campaignType": "advanced",
- "updated": "2022-08-24T14:15:22Z",
- "updatedBy": "Jane Doe",
- "validApplicationIds": [
- 1,
- 2,
- 3
], - "isUserFavorite": false
}
]
}
Use the campaign template referenced in the request body to create a new campaign in one of the connected Applications.
If the template was created from a campaign with rules referencing campaign collections, the corresponding collections for the new campaign are created automatically.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
body
name required | string non-empty A user-facing name for this campaign. | ||||||||||||||||
templateId required | integer The ID of the Campaign Template which will be used in order to create the Campaign. | ||||||||||||||||
description | string A detailed description of the campaign. | ||||||||||||||||
campaignAttributesOverrides | object Custom Campaign Attributes. If the Campaign Template defines the same values, they will be overridden. | ||||||||||||||||
Array of objects Actual values to replace the template placeholder values in the Ruleset bindings. Values for all Template Parameters must be provided. | |||||||||||||||||
Array
| |||||||||||||||||
Array of objects Limits for this Campaign. If the Campaign Template or Application define default values for the same limits, they will be overridden. | |||||||||||||||||
Array
| |||||||||||||||||
campaignGroups | Array of integers The IDs of the campaign groups this campaign belongs to. | ||||||||||||||||
tags | Array of strings <= 50 items [ items [ 1 .. 50 ] characters ] A list of tags for the campaign. If the campaign template has tags, they will be overridden by this list. | ||||||||||||||||
evaluationGroupId | integer The ID of the campaign evaluation group the campaign belongs to. | ||||||||||||||||
linkedStoreIds | Array of integers A list of store IDs that are linked to the campaign. Note: Campaigns with linked store IDs will only be evaluated when there is a customer session update that references a linked store. |
{- "name": "Discount campaign",
- "description": "This template is for discount campaigns.",
- "templateId": 4,
- "campaignAttributesOverrides": { },
- "templateParamValues": [
- {
- "name": "my property",
- "type": "templateParameter",
- "expression": [
- "string1",
- "string2"
], - "valueType": "string",
- "minValue": 0,
- "maxValue": 19.9,
- "attributeId": 100,
- "description": "This is a template parameter of type `number`."
}
], - "limitOverrides": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "campaignGroups": [
- 1,
- 3
], - "tags": [
- "summer"
], - "evaluationGroupId": 2,
- "linkedStoreIds": [
- 1,
- 2,
- 3
]
}
{- "campaign": {
- "id": 4,
- "created": "2020-06-10T09:05:27.993483Z",
- "applicationId": 322,
- "userId": 388,
- "name": "Summer promotions",
- "description": "Campaign for all summer 2021 promotions",
- "startTime": "2021-07-20T22:00:00Z",
- "endTime": "2021-09-22T22:00:00Z",
- "attributes": { },
- "state": "enabled",
- "activeRulesetId": 6,
- "tags": [
- "summer"
], - "features": [
- "coupons",
- "referrals"
], - "couponSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "referralSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "campaignGroups": [
- 1,
- 3
], - "type": "advanced",
- "linkedStoreIds": [
- 1,
- 2,
- 3
], - "budgets": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "counter": 42
}
], - "couponRedemptionCount": 163,
- "referralRedemptionCount": 3,
- "discountCount": 288,
- "discountEffectCount": 343,
- "couponCreationCount": 16,
- "customEffectCount": 0,
- "referralCreationCount": 8,
- "addFreeItemEffectCount": 0,
- "awardedGiveawaysCount": 9,
- "createdLoyaltyPointsCount": 9,
- "createdLoyaltyPointsEffectCount": 2,
- "redeemedLoyaltyPointsCount": 8,
- "redeemedLoyaltyPointsEffectCount": 9,
- "callApiEffectCount": 0,
- "reservecouponEffectCount": 9,
- "lastActivity": "2022-11-10T23:00:00Z",
- "updated": "2022-10-97T35:00:00Z",
- "createdBy": "John Doe",
- "updatedBy": "Jane Doe",
- "templateId": 3,
- "frontendState": "running",
- "storesImported": true,
- "valueMapsIds": [
- 100,
- 215
], - "revisionFrontendState": "revised",
- "activeRevisionId": 6,
- "activeRevisionVersionId": 6,
- "version": 6,
- "currentRevisionId": 6,
- "currentRevisionVersionId": 6,
- "stageRevision": false
}, - "ruleset": {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "userId": 388,
- "rules": [
- {
- "id": "7fa800a8-ac8d-4792-85dc-c4650dcc8f23",
- "parentId": "7fa800a8-ac8d-4792-85dc-c4650dcc8f23",
- "title": "Give discount via coupon",
- "description": "Creates a discount when a coupon is valid",
- "bindings": [
- {
- "name": "my property",
- "type": "templateParameter",
- "expression": [
- "string1",
- "string2"
], - "valueType": "string",
- "minValue": 0,
- "maxValue": 19.9,
- "attributeId": 100,
- "description": "This is a template parameter of type `number`."
}
], - "condition": [
- "and",
- [
- "couponValid"
]
], - "effects": [
- "catch",
- [
- "noop"
], - [
- "setDiscount",
- "10% off",
- [
- "*",
- [
- ".",
- "Session",
- "Total"
], - [
- "/",
- 10,
- 100
]
]
]
]
}
], - "strikethroughRules": [
- {
- "id": "7fa800a8-ac8d-4792-85dc-c4650dcc8f23",
- "parentId": "7fa800a8-ac8d-4792-85dc-c4650dcc8f23",
- "title": "Give discount via coupon",
- "description": "Creates a discount when a coupon is valid",
- "bindings": [
- {
- "name": "my property",
- "type": "templateParameter",
- "expression": [
- "string1",
- "string2"
], - "valueType": "string",
- "minValue": 0,
- "maxValue": 19.9,
- "attributeId": 100,
- "description": "This is a template parameter of type `number`."
}
], - "condition": [
- "and",
- [
- "couponValid"
]
], - "effects": [
- "catch",
- [
- "noop"
], - [
- "setDiscount",
- "10% off",
- [
- "*",
- [
- ".",
- "Session",
- "Total"
], - [
- "/",
- 10,
- 100
]
]
]
]
}
], - "bindings": [ ],
- "rbVersion": "v2",
- "activate": true,
- "campaignId": 320,
- "templateId": 3,
- "activatedAt": "2019-08-24T14:15:22Z"
}, - "collections": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "modified": "2021-09-12T10:12:42Z",
- "description": "My collection of SKUs",
- "subscribedApplicationsIds": [
- 1,
- 2,
- 3
], - "name": "My collection",
- "modifiedBy": 48,
- "createdBy": 134,
- "applicationId": 1,
- "campaignId": 7,
- "payload": [
- "KTL-WH-ET-1",
- "KTL-BL-ET-1"
]
}
]
}
Represents the primary resource used to control the behavior of the Talon.One Rule Engine. They combine rulesets, coupons, and limits into a single unit.
See the docs.
List the campaigns of the specified application that match your filter criteria.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
campaignState | string Enum: "enabled" "disabled" "archived" "scheduled" "running" "expired" "staged" Example: campaignState=enabled Filter results by the state of the campaign.
|
name | string Example: name=campaign1 Filter results performing case-insensitive matching against the name of the campaign. |
tags | string Example: tags=tag1 Filter results performing case-insensitive matching against the tags of the campaign. When used in conjunction with the "name" query parameter, a logical OR will be performed to search both tags and name for the provided values |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
createdAfter | string <date-time> Example: createdAfter=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
campaignGroupId | integer Example: campaignGroupId=12 Filter results to campaigns owned by the specified campaign access group ID. |
templateId | integer Example: templateId=18 The ID of the campaign template this campaign was created from. |
storeId | integer Example: storeId=23 Filter results to campaigns linked to the specified store ID. |
{- "totalResultSize": 1,
- "data": [
- {
- "id": 4,
- "created": "2020-06-10T09:05:27.993483Z",
- "applicationId": 322,
- "userId": 388,
- "name": "Summer promotions",
- "description": "Campaign for all summer 2021 promotions",
- "startTime": "2021-07-20T22:00:00Z",
- "endTime": "2021-09-22T22:00:00Z",
- "attributes": { },
- "state": "enabled",
- "activeRulesetId": 6,
- "tags": [
- "summer"
], - "features": [
- "coupons",
- "referrals"
], - "couponSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "referralSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "campaignGroups": [
- 1,
- 3
], - "type": "advanced",
- "linkedStoreIds": [
- 1,
- 2,
- 3
], - "budgets": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "counter": 42
}
], - "couponRedemptionCount": 163,
- "referralRedemptionCount": 3,
- "discountCount": 288,
- "discountEffectCount": 343,
- "couponCreationCount": 16,
- "customEffectCount": 0,
- "referralCreationCount": 8,
- "addFreeItemEffectCount": 0,
- "awardedGiveawaysCount": 9,
- "createdLoyaltyPointsCount": 9,
- "createdLoyaltyPointsEffectCount": 2,
- "redeemedLoyaltyPointsCount": 8,
- "redeemedLoyaltyPointsEffectCount": 9,
- "callApiEffectCount": 0,
- "reservecouponEffectCount": 9,
- "lastActivity": "2022-11-10T23:00:00Z",
- "updated": "2022-10-97T35:00:00Z",
- "createdBy": "John Doe",
- "updatedBy": "Jane Doe",
- "templateId": 3,
- "frontendState": "running",
- "storesImported": true,
- "valueMapsIds": [
- 100,
- 215
], - "revisionFrontendState": "revised",
- "activeRevisionId": 6,
- "activeRevisionVersionId": 6,
- "version": 6,
- "currentRevisionId": 6,
- "currentRevisionVersionId": 6,
- "stageRevision": false
}
]
}
Retrieve the given campaign.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
{- "id": 4,
- "created": "2020-06-10T09:05:27.993483Z",
- "applicationId": 322,
- "userId": 388,
- "name": "Summer promotions",
- "description": "Campaign for all summer 2021 promotions",
- "startTime": "2021-07-20T22:00:00Z",
- "endTime": "2021-09-22T22:00:00Z",
- "attributes": { },
- "state": "enabled",
- "activeRulesetId": 6,
- "tags": [
- "summer"
], - "features": [
- "coupons",
- "referrals"
], - "couponSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "referralSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "campaignGroups": [
- 1,
- 3
], - "type": "advanced",
- "linkedStoreIds": [
- 1,
- 2,
- 3
], - "budgets": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "counter": 42
}
], - "couponRedemptionCount": 163,
- "referralRedemptionCount": 3,
- "discountCount": 288,
- "discountEffectCount": 343,
- "couponCreationCount": 16,
- "customEffectCount": 0,
- "referralCreationCount": 8,
- "addFreeItemEffectCount": 0,
- "awardedGiveawaysCount": 9,
- "createdLoyaltyPointsCount": 9,
- "createdLoyaltyPointsEffectCount": 2,
- "redeemedLoyaltyPointsCount": 8,
- "redeemedLoyaltyPointsEffectCount": 9,
- "callApiEffectCount": 0,
- "reservecouponEffectCount": 9,
- "lastActivity": "2022-11-10T23:00:00Z",
- "updated": "2022-10-97T35:00:00Z",
- "createdBy": "John Doe",
- "updatedBy": "Jane Doe",
- "templateId": 3,
- "frontendState": "running",
- "storesImported": true,
- "valueMapsIds": [
- 100,
- 215
], - "revisionFrontendState": "revised",
- "activeRevisionId": 6,
- "activeRevisionVersionId": 6,
- "version": 6,
- "currentRevisionId": 6,
- "currentRevisionVersionId": 6,
- "stageRevision": false
}
Update the given campaign.
Important: You cannot use this endpoint to update campaigns if campaign staging and revisions is enabled for your Application.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
body
name required | string non-empty A user-facing name for this campaign. | ||||||||
tags required | Array of strings <= 50 items [ items [ 1 .. 50 ] characters ] A list of tags for the campaign. | ||||||||
required | Array of objects The set of limits that will operate for this campaign. | ||||||||
Array
| |||||||||
features required | Array of strings Items Enum: "coupons" "referrals" "loyalty" "giveaways" "strikethrough" "achievements" A list of features for the campaign. | ||||||||
description | string A detailed description of the campaign. | ||||||||
startTime | string <date-time> Timestamp when the campaign will become active. | ||||||||
endTime | string <date-time> Timestamp when the campaign will become inactive. | ||||||||
attributes | object Arbitrary properties associated with this campaign. | ||||||||
state | string Default: "enabled" Enum: "enabled" "disabled" "archived" A disabled or archived campaign is not evaluated for rules or coupons. | ||||||||
activeRulesetId | integer ID of Ruleset this campaign applies on customer session evaluation. | ||||||||
object | |||||||||
| |||||||||
object | |||||||||
| |||||||||
campaignGroups | Array of integers The IDs of the campaign groups this campaign belongs to. | ||||||||
evaluationGroupId | integer The ID of the campaign evaluation group the campaign belongs to. | ||||||||
type | string Default: "advanced" Enum: "cartItem" "advanced" The campaign type. Possible type values:
| ||||||||
linkedStoreIds | Array of integers A list of store IDs that you want to link to the campaign. Note:
|
{- "name": "Summer promotions",
- "description": "Campaign for all summer 2021 promotions",
- "startTime": "2021-07-20T22:00:00Z",
- "endTime": "2021-10-01T02:00:00Z",
- "attributes": {
- "myattribute": 20
}, - "state": "disabled",
- "activeRulesetId": 2,
- "tags": [
- "Summer",
- "Shoes"
], - "features": [
- "coupons",
- "loyalty"
], - "couponSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "referralSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "campaignGroups": [
- 1,
- 3
], - "evaluationGroupId": 2,
- "type": "advanced",
- "linkedStoreIds": [
- 1,
- 2,
- 3
]
}
{- "id": 4,
- "created": "2020-06-10T09:05:27.993483Z",
- "applicationId": 322,
- "userId": 388,
- "name": "Summer promotions",
- "description": "Campaign for all summer 2021 promotions",
- "startTime": "2021-07-20T22:00:00Z",
- "endTime": "2021-09-22T22:00:00Z",
- "attributes": { },
- "state": "enabled",
- "activeRulesetId": 6,
- "tags": [
- "summer"
], - "features": [
- "coupons",
- "referrals"
], - "couponSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "referralSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "campaignGroups": [
- 1,
- 3
], - "type": "advanced",
- "linkedStoreIds": [
- 1,
- 2,
- 3
], - "budgets": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "counter": 42
}
], - "couponRedemptionCount": 163,
- "referralRedemptionCount": 3,
- "discountCount": 288,
- "discountEffectCount": 343,
- "couponCreationCount": 16,
- "customEffectCount": 0,
- "referralCreationCount": 8,
- "addFreeItemEffectCount": 0,
- "awardedGiveawaysCount": 9,
- "createdLoyaltyPointsCount": 9,
- "createdLoyaltyPointsEffectCount": 2,
- "redeemedLoyaltyPointsCount": 8,
- "redeemedLoyaltyPointsEffectCount": 9,
- "callApiEffectCount": 0,
- "reservecouponEffectCount": 9,
- "lastActivity": "2022-11-10T23:00:00Z",
- "updated": "2022-10-97T35:00:00Z",
- "createdBy": "John Doe",
- "updatedBy": "Jane Doe",
- "templateId": 3,
- "frontendState": "running",
- "storesImported": true,
- "valueMapsIds": [
- 100,
- 215
], - "revisionFrontendState": "revised",
- "activeRevisionId": 6,
- "activeRevisionVersionId": 6,
- "version": 6,
- "currentRevisionId": 6,
- "currentRevisionVersionId": 6,
- "stageRevision": false
}
Delete the given campaign.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
Copy the campaign into all specified Applications.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
body
applicationIds required | Array of integers Application IDs of the applications to which a campaign should be copied to. |
name | string Name of the copied campaign (Defaults to "Copy of original campaign name"). |
description | string A detailed description of the campaign. |
startTime | string <date-time> Timestamp when the campaign will become active. |
endTime | string <date-time> Timestamp when the campaign will become inactive. |
tags | Array of strings <= 50 items [ items [ 1 .. 50 ] characters ] A list of tags for the campaign. |
evaluationGroupId | integer The ID of the campaign evaluation group the campaign belongs to. |
{- "name": "Copy of Summer promotions",
- "applicationIds": [
- 1,
- 2,
- 3
], - "description": "Campaign for all summer 2021 promotions",
- "startTime": "2021-06-01T09:00:27.993483Z",
- "endTime": "2021-09-10T01:00:00.993483Z",
- "tags": [
- "Summer",
- "Shoes"
], - "evaluationGroupId": 2
}
{- "totalResultSize": 1,
- "data": [
- {
- "id": 4,
- "created": "2020-06-10T09:05:27.993483Z",
- "applicationId": 322,
- "userId": 388,
- "name": "Summer promotions",
- "description": "Campaign for all summer 2021 promotions",
- "startTime": "2021-07-20T22:00:00Z",
- "endTime": "2021-09-22T22:00:00Z",
- "attributes": { },
- "state": "enabled",
- "activeRulesetId": 6,
- "tags": [
- "summer"
], - "features": [
- "coupons",
- "referrals"
], - "couponSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "referralSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "campaignGroups": [
- 1,
- 3
], - "type": "advanced",
- "linkedStoreIds": [
- 1,
- 2,
- 3
], - "budgets": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "counter": 42
}
], - "couponRedemptionCount": 163,
- "referralRedemptionCount": 3,
- "discountCount": 288,
- "discountEffectCount": 343,
- "couponCreationCount": 16,
- "customEffectCount": 0,
- "referralCreationCount": 8,
- "addFreeItemEffectCount": 0,
- "awardedGiveawaysCount": 9,
- "createdLoyaltyPointsCount": 9,
- "createdLoyaltyPointsEffectCount": 2,
- "redeemedLoyaltyPointsCount": 8,
- "redeemedLoyaltyPointsEffectCount": 9,
- "callApiEffectCount": 0,
- "reservecouponEffectCount": 9,
- "lastActivity": "2022-11-10T23:00:00Z",
- "updated": "2022-10-97T35:00:00Z",
- "createdBy": "John Doe",
- "updatedBy": "Jane Doe",
- "templateId": 3,
- "frontendState": "running",
- "storesImported": true,
- "valueMapsIds": [
- 100,
- 215
], - "revisionFrontendState": "revised",
- "activeRevisionId": 6,
- "activeRevisionVersionId": 6,
- "version": 6,
- "currentRevisionId": 6,
- "currentRevisionVersionId": 6,
- "stageRevision": false
}
]
}
Get a list of all the campaigns that match a set of attributes.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
campaignState | string Enum: "enabled" "disabled" "archived" "scheduled" "running" "expired" "staged" Example: campaignState=enabled Filter results by the state of the campaign.
|
body
attributes required | object Properties to match against a campaign. All provided attributes will be exactly matched against campaign attributes. |
{- "attributes": { }
}
{- "totalResultSize": 1,
- "data": [
- {
- "id": 4,
- "created": "2020-06-10T09:05:27.993483Z",
- "applicationId": 322,
- "userId": 388,
- "name": "Summer promotions",
- "description": "Campaign for all summer 2021 promotions",
- "startTime": "2021-07-20T22:00:00Z",
- "endTime": "2021-09-22T22:00:00Z",
- "attributes": { },
- "state": "enabled",
- "activeRulesetId": 6,
- "tags": [
- "summer"
], - "features": [
- "coupons",
- "referrals"
], - "couponSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "referralSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "campaignGroups": [
- 1,
- 3
], - "type": "advanced",
- "linkedStoreIds": [
- 1,
- 2,
- 3
], - "budgets": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "counter": 42
}
], - "couponRedemptionCount": 163,
- "referralRedemptionCount": 3,
- "discountCount": 288,
- "discountEffectCount": 343,
- "couponCreationCount": 16,
- "customEffectCount": 0,
- "referralCreationCount": 8,
- "addFreeItemEffectCount": 0,
- "awardedGiveawaysCount": 9,
- "createdLoyaltyPointsCount": 9,
- "createdLoyaltyPointsEffectCount": 2,
- "redeemedLoyaltyPointsCount": 8,
- "redeemedLoyaltyPointsEffectCount": 9,
- "callApiEffectCount": 0,
- "reservecouponEffectCount": 9,
- "lastActivity": "2022-11-10T23:00:00Z",
- "updated": "2022-10-97T35:00:00Z",
- "createdBy": "John Doe",
- "updatedBy": "Jane Doe",
- "templateId": 3,
- "frontendState": "running",
- "storesImported": true,
- "valueMapsIds": [
- 100,
- 215
], - "revisionFrontendState": "revised",
- "activeRevisionId": 6,
- "activeRevisionVersionId": 6,
- "version": 6,
- "currentRevisionId": 6,
- "currentRevisionVersionId": 6,
- "stageRevision": false
}
]
}
List all rulesets of this campaign. A ruleset is a revision of the rules of a campaign. Important: The response also includes deleted rules. You should only consider the latest revision of the returned rulesets.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
{- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "userId": 388,
- "rules": [
- {
- "id": "7fa800a8-ac8d-4792-85dc-c4650dcc8f23",
- "parentId": "7fa800a8-ac8d-4792-85dc-c4650dcc8f23",
- "title": "Give discount via coupon",
- "description": "Creates a discount when a coupon is valid",
- "bindings": [
- {
- "name": "my property",
- "type": "templateParameter",
- "expression": [
- "string1",
- "string2"
], - "valueType": "string",
- "minValue": 0,
- "maxValue": 19.9,
- "attributeId": 100,
- "description": "This is a template parameter of type `number`."
}
], - "condition": [
- "and",
- [
- "couponValid"
]
], - "effects": [
- "catch",
- [
- "noop"
], - [
- "setDiscount",
- "10% off",
- [
- "*",
- [
- ".",
- "Session",
- "Total"
], - [
- "/",
- 10,
- 100
]
]
]
]
}
], - "strikethroughRules": [
- {
- "id": "7fa800a8-ac8d-4792-85dc-c4650dcc8f23",
- "parentId": "7fa800a8-ac8d-4792-85dc-c4650dcc8f23",
- "title": "Give discount via coupon",
- "description": "Creates a discount when a coupon is valid",
- "bindings": [
- {
- "name": "my property",
- "type": "templateParameter",
- "expression": [
- "string1",
- "string2"
], - "valueType": "string",
- "minValue": 0,
- "maxValue": 19.9,
- "attributeId": 100,
- "description": "This is a template parameter of type `number`."
}
], - "condition": [
- "and",
- [
- "couponValid"
]
], - "effects": [
- "catch",
- [
- "noop"
], - [
- "setDiscount",
- "10% off",
- [
- "*",
- [
- ".",
- "Session",
- "Total"
], - [
- "/",
- 10,
- 100
]
]
]
]
}
], - "bindings": [ ],
- "rbVersion": "v2",
- "activate": true,
- "campaignId": 320,
- "templateId": 3,
- "activatedAt": "2019-08-24T14:15:22Z"
}
]
}
Retrieve the specified ruleset.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
rulesetId required | integer Example: 29 The ID of the ruleset. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "userId": 388,
- "rules": [
- {
- "id": "7fa800a8-ac8d-4792-85dc-c4650dcc8f23",
- "parentId": "7fa800a8-ac8d-4792-85dc-c4650dcc8f23",
- "title": "Give discount via coupon",
- "description": "Creates a discount when a coupon is valid",
- "bindings": [
- {
- "name": "my property",
- "type": "templateParameter",
- "expression": [
- "string1",
- "string2"
], - "valueType": "string",
- "minValue": 0,
- "maxValue": 19.9,
- "attributeId": 100,
- "description": "This is a template parameter of type `number`."
}
], - "condition": [
- "and",
- [
- "couponValid"
]
], - "effects": [
- "catch",
- [
- "noop"
], - [
- "setDiscount",
- "10% off",
- [
- "*",
- [
- ".",
- "Session",
- "Total"
], - [
- "/",
- 10,
- 100
]
]
]
]
}
], - "strikethroughRules": [
- {
- "id": "7fa800a8-ac8d-4792-85dc-c4650dcc8f23",
- "parentId": "7fa800a8-ac8d-4792-85dc-c4650dcc8f23",
- "title": "Give discount via coupon",
- "description": "Creates a discount when a coupon is valid",
- "bindings": [
- {
- "name": "my property",
- "type": "templateParameter",
- "expression": [
- "string1",
- "string2"
], - "valueType": "string",
- "minValue": 0,
- "maxValue": 19.9,
- "attributeId": 100,
- "description": "This is a template parameter of type `number`."
}
], - "condition": [
- "and",
- [
- "couponValid"
]
], - "effects": [
- "catch",
- [
- "noop"
], - [
- "setDiscount",
- "10% off",
- [
- "*",
- [
- ".",
- "Session",
- "Total"
], - [
- "/",
- 10,
- 100
]
]
]
]
}
], - "bindings": [ ],
- "rbVersion": "v2",
- "activate": true,
- "campaignId": 320,
- "templateId": 3,
- "activatedAt": "2019-08-24T14:15:22Z"
}
Retrieve statistical data about the performance of the given campaign.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
rangeStart required | string <date-time> Example: rangeStart=2024-05-29T15:04:05+07:00 Only return results from after this timestamp. Note:
|
rangeEnd required | string <date-time> Example: rangeEnd=2024-05-29T15:04:05+07:00 Only return results from before this timestamp. Note:
|
granularity | string Enum: "1 hour" "1 day" "1 week" "1 month" "1 year" Example: granularity=1 hour The time interval between the results in the returned time-series. |
{- "totalResultSize": 1,
- "data": [
- {
- "date": "2021-10-12T10:12:42Z",
- "campaignRevenue": 3539.76,
- "totalCampaignRevenue": 5784.63,
- "campaignRefund": 0,
- "totalCampaignRefund": 0,
- "campaignDiscountCosts": 0,
- "totalCampaignDiscountCosts": 0,
- "campaignRefundedDiscounts": 0,
- "totalCampaignRefundedDiscounts": 0,
- "campaignFreeItems": 0,
- "totalCampaignFreeItems": 86,
- "couponRedemptions": 0,
- "totalCouponRedemptions": 0,
- "couponRolledbackRedemptions": 0,
- "totalCouponRolledbackRedemptions": 0,
- "referralRedemptions": 0,
- "totalReferralRedemptions": 0,
- "couponsCreated": 0,
- "totalCouponsCreated": 0,
- "referralsCreated": 0,
- "totalReferralsCreated": 0,
- "addedLoyaltyPoints": 250,
- "totalAddedLoyaltyPoints": 340,
- "deductedLoyaltyPoints": 120,
- "totalDeductedLoyaltyPoints": 220
}
]
}
Represents a catalog of cart items with unique SKUs. Cart item catalogs allow you to synchronize your entire inventory with Talon.One.
See the docs.
Return a paginated list of cart items in the given catalog.
catalogId required | integer Example: 30 The ID of the catalog. You can find the ID in the Campaign Manager in Account > Tools > Cart item catalogs. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
withTotalResultSize | boolean When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.
|
sku | Array of strings Example: sku=SKU-1&sku=SKU-2 Filter results by one or more SKUs. Must be exact match. |
productNames | Array of strings Example: productNames=product1&productNames=product2 Filter results by one or more product names. Must be exact match. |
{- "hasMore": true,
- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "sku": "SKU1241028",
- "price": 99.99,
- "catalogid": 6,
- "version": 5,
- "attributes": [
- {
- "attributeid": 6,
- "name": "string",
- "value": null
}
], - "product": {
- "name": "sample_product"
}
}
]
}
Represents a collection of arbitrary values that you can use inside rules. For example, a list of SKUs.
See the docs.
List account-level collections in the account.
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
withTotalResultSize | boolean When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.
|
name | string Example: name=collection1 Filter by collection name. |
{- "hasMore": true,
- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "modified": "2021-09-12T10:12:42Z",
- "description": "My collection of SKUs",
- "subscribedApplicationsIds": [
- 1,
- 2,
- 3
], - "name": "My collection",
- "modifiedBy": 48,
- "createdBy": 134,
- "applicationId": 1,
- "campaignId": 7
}
]
}
Create an account-level collection.
body
name required | string non-empty ^[^[:cntrl:]\s][^[:cntrl:]]*$ The name of this collection. |
description | string A short description of the purpose of this collection. |
subscribedApplicationsIds | Array of integers A list of the IDs of the Applications where this collection is enabled. |
{- "description": "My collection of SKUs",
- "subscribedApplicationsIds": [
- 1,
- 2,
- 3
], - "name": "My collection"
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "modified": "2021-09-12T10:12:42Z",
- "description": "My collection of SKUs",
- "subscribedApplicationsIds": [
- 1,
- 2,
- 3
], - "name": "My collection",
- "modifiedBy": 48,
- "createdBy": 134,
- "applicationId": 1,
- "campaignId": 7,
- "payload": [
- "KTL-WH-ET-1",
- "KTL-BL-ET-1"
]
}
Retrieve a given account-level collection.
collectionId required | integer Example: 22 The ID of the collection. You can get it with the List collections in account endpoint. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "modified": "2021-09-12T10:12:42Z",
- "description": "My collection of SKUs",
- "subscribedApplicationsIds": [
- 1,
- 2,
- 3
], - "name": "My collection",
- "modifiedBy": 48,
- "createdBy": 134,
- "applicationId": 1,
- "campaignId": 7,
- "payload": [
- "KTL-WH-ET-1",
- "KTL-BL-ET-1"
]
}
Edit the description of a given account-level collection and enable or disable the collection in the specified Applications.
collectionId required | integer Example: 22 The ID of the collection. You can get it with the List collections in account endpoint. |
body
description | string A short description of the purpose of this collection. |
subscribedApplicationsIds | Array of integers A list of the IDs of the Applications where this collection is enabled. |
{- "description": "My collection of SKUs",
- "subscribedApplicationsIds": [
- 1,
- 2,
- 3
]
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "modified": "2021-09-12T10:12:42Z",
- "description": "My collection of SKUs",
- "subscribedApplicationsIds": [
- 1,
- 2,
- 3
], - "name": "My collection",
- "modifiedBy": 48,
- "createdBy": 134,
- "applicationId": 1,
- "campaignId": 7,
- "payload": [
- "KTL-WH-ET-1",
- "KTL-BL-ET-1"
]
}
Delete a given account-level collection.
collectionId required | integer Example: 22 The ID of the collection. You can get it with the List collections in account endpoint. |
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
Retrieve items from a given collection.
You can retrieve items from both account-level collections and campaign-level collections using this endpoint.
collectionId required | integer Example: 22 The ID of the collection. You can get it with the List collections in account endpoint. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
{- "hasMore": true,
- "data": [
- {
- "item": "string"
}
]
}
List campaign-level collections from all campaigns in a given Application.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
withTotalResultSize | boolean When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.
|
name | string Example: name=collection1 Filter by collection name. |
{- "hasMore": true,
- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "modified": "2021-09-12T10:12:42Z",
- "description": "My collection of SKUs",
- "subscribedApplicationsIds": [
- 1,
- 2,
- 3
], - "name": "My collection",
- "modifiedBy": 48,
- "createdBy": 134,
- "applicationId": 1,
- "campaignId": 7
}
]
}
List collections in a given campaign.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
withTotalResultSize | boolean When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.
|
name | string Example: name=collection1 Filter by collection name. |
{- "hasMore": true,
- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "modified": "2021-09-12T10:12:42Z",
- "description": "My collection of SKUs",
- "subscribedApplicationsIds": [
- 1,
- 2,
- 3
], - "name": "My collection",
- "modifiedBy": 48,
- "createdBy": 134,
- "applicationId": 1,
- "campaignId": 7
}
]
}
Create a campaign-level collection in a given campaign.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
body
name required | string non-empty ^[^[:cntrl:]\s][^[:cntrl:]]*$ The name of this collection. |
description | string A short description of the purpose of this collection. |
{- "description": "My collection of SKUs",
- "name": "My collection"
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "modified": "2021-09-12T10:12:42Z",
- "description": "My collection of SKUs",
- "subscribedApplicationsIds": [
- 1,
- 2,
- 3
], - "name": "My collection",
- "modifiedBy": 48,
- "createdBy": 134,
- "applicationId": 1,
- "campaignId": 7,
- "payload": [
- "KTL-WH-ET-1",
- "KTL-BL-ET-1"
]
}
Retrieve a given campaign-level collection.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
collectionId required | integer Example: 44 The ID of the collection. You can get it with the List collections in Application endpoint. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "modified": "2021-09-12T10:12:42Z",
- "description": "My collection of SKUs",
- "subscribedApplicationsIds": [
- 1,
- 2,
- 3
], - "name": "My collection",
- "modifiedBy": 48,
- "createdBy": 134,
- "applicationId": 1,
- "campaignId": 7,
- "payload": [
- "KTL-WH-ET-1",
- "KTL-BL-ET-1"
]
}
Edit the description of a given campaign-level collection.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
collectionId required | integer Example: 44 The ID of the collection. You can get it with the List collections in Application endpoint. |
body
description | string A short description of the purpose of this collection. |
{- "description": "My collection of SKUs"
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "modified": "2021-09-12T10:12:42Z",
- "description": "My collection of SKUs",
- "subscribedApplicationsIds": [
- 1,
- 2,
- 3
], - "name": "My collection",
- "modifiedBy": 48,
- "createdBy": 134,
- "applicationId": 1,
- "campaignId": 7,
- "payload": [
- "KTL-WH-ET-1",
- "KTL-BL-ET-1"
]
}
Delete a given campaign-level collection.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
collectionId required | integer Example: 44 The ID of the collection. You can get it with the List collections in Application endpoint. |
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
Upload a CSV file containing the collection of string values that should be attached as payload for collection. The file should be sent as multipart data.
The import replaces the initial content of the collection.
The CSV file must only contain the following column:
item
: the values in your collection.A collection is limited to 500,000 items.
Example:
item
Addidas
Nike
Asics
Note: Before sending a request to this endpoint, ensure the data in the CSV to import is different from the data currently stored in the collection.
collectionId required | integer Example: 22 The ID of the collection. You can get it with the List collections in account endpoint. |
upFile | string <csv> The file containing the data that is being imported. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "userId": 388,
- "entity": "AttributeAllowedList",
- "amount": 10
}
Upload a CSV file containing the collection of string values that should be attached as payload for collection. The file should be sent as multipart data.
The import replaces the initial content of the collection.
The CSV file must only contain the following column:
item
: the values in your collection.A collection is limited to 500,000 items.
Example:
item
Addidas
Nike
Asics
Note: Before sending a request to this endpoint, ensure the data in the CSV to import is different from the data currently stored in the collection.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
collectionId required | integer Example: 44 The ID of the collection. You can get it with the List collections in Application endpoint. |
upFile | string <csv> The file containing the data that is being imported. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "userId": 388,
- "entity": "AttributeAllowedList",
- "amount": 10
}
Download a CSV file containing items from a given account-level collection.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
collectionId required | integer Example: 22 The ID of the collection. You can get it with the List collections in account endpoint. |
item SKU1 SKU2 SKU3
Download a CSV file containing items from a given campaign-level collection.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
collectionId required | integer Example: 44 The ID of the collection. You can get it with the List collections in Application endpoint. |
item SKU1 SKU2 SKU3
Coupons are unique codes belonging to a particular campaign. They don't define any behavior on their own. Instead the campaign ruleset can include rules that validate coupons and carry out particular effects.
See the docs.
Create coupons according to some pattern. Up to 20.000 coupons can be created without a unique prefix. When a unique prefix is provided, up to 200.000 coupons can be created.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
silent | string Default: "yes" Example: silent=yes Possible values:
|
body
numberOfCoupons required | integer The number of new coupon codes to generate for the campaign. Must be at least 1. | ||||||||
usageLimit required | integer [ 0 .. 999999 ] The number of times the coupon code can be redeemed. | ||||||||
discountLimit | number [ 0 .. 1000000000000000 ] The total discount value that the code can give. Typically used to represent a gift card value. | ||||||||
reservationLimit | integer [ 0 .. 999999 ] The number of reservations that can be made with this coupon code. | ||||||||
startDate | string <date-time> Timestamp at which point the coupon becomes valid. | ||||||||
expiryDate | string <date-time> Expiration date of the coupon. Coupon never expires if this is omitted. | ||||||||
Array of objects Limits configuration for a coupon. These limits will override the limits set from the campaign. Note: Only usable when creating a single coupon which is not tied to a specific recipient. Only per-profile limits are allowed to be configured. | |||||||||
Array
| |||||||||
uniquePrefix | string DEPRECATED To create more than 20,000 coupons in one request, use Create coupons asynchronously endpoint. | ||||||||
attributes | object Arbitrary properties associated with this item. | ||||||||
recipientIntegrationId | string <= 1000 characters The integration ID for this coupon's beneficiary's profile. | ||||||||
validCharacters | Array of strings List of characters used to generate the random parts of a code. By default,
the list of characters is equivalent to the | ||||||||
couponPattern | string [ 3 .. 100 ] characters The pattern used to generate coupon codes.
The character | ||||||||
isReservationMandatory | boolean Default: false An indication of whether the code can be redeemed only if it has been reserved first. | ||||||||
implicitlyReserved | boolean An indication of whether the coupon is implicitly reserved for all customers. |
{- "usageLimit": 100,
- "discountLimit": 30,
- "reservationLimit": 45,
- "startDate": "2020-01-24T14:15:22Z",
- "expiryDate": "2023-08-24T14:15:22Z",
- "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "numberOfCoupons": 1,
- "uniquePrefix": "",
- "attributes": {
- "venueId": 12
}, - "recipientIntegrationId": "URNGV8294NV",
- "validCharacters": [
- "A",
- "B",
- "G",
- "Y"
], - "couponPattern": "SUMMER-#####",
- "isReservationMandatory": false,
- "implicitlyReserved": false
}
{- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "campaignId": 211,
- "value": "XMAS-20-2021",
- "usageLimit": 100,
- "discountLimit": 30,
- "reservationLimit": 45,
- "startDate": "2020-01-24T14:15:22Z",
- "expiryDate": "2023-08-24T14:15:22Z",
- "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "usageCounter": 10,
- "discountCounter": 10,
- "discountRemainder": 5,
- "reservationCounter": 1,
- "attributes": { },
- "referralId": 326632952,
- "recipientIntegrationId": "URNGV8294NV",
- "importId": 4,
- "reservation": false,
- "batchId": "32535-43255",
- "isReservationMandatory": false,
- "implicitlyReserved": false
}
]
}
Update all coupons or a specific batch of coupons in the given campaign.
You can find the batchId
on the Coupons page of your campaign
in the Campaign Manager, or you can use List coupons.
Important
PUT
endpoint, if you do not explicitly set a value for the startDate
and expiryDate
properties in your request, it is automatically set to null
.To update a specific coupon, use Update coupon.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
body
usageLimit | integer [ 0 .. 999999 ] The number of times the coupon code can be redeemed. |
discountLimit | number [ 0 .. 1000000000000000 ] The total discount value that the code can give. Typically used to represent a gift card value. |
reservationLimit | integer [ 0 .. 999999 ] The number of reservations that can be made with this coupon code. |
startDate | string <date-time> Timestamp at which point the coupon becomes valid. |
expiryDate | string <date-time> Expiration date of the coupon. Coupon never expires if this is omitted. |
attributes | object Optional property to set the value of custom coupon attributes. They are defined in the Campaign Manager, see Managing attributes. Coupon attributes can also be set to mandatory in your Application settings. If your Application uses mandatory attributes, you must use this property to set their value. |
batchID | string The ID of the batch the coupon(s) belong to. |
{- "usageLimit": 100,
- "discountLimit": 30,
- "reservationLimit": 45,
- "startDate": "2020-01-24T14:15:22Z",
- "expiryDate": "2023-08-24T14:15:22Z",
- "attributes": { },
- "batchID": "string"
}
Deletes all the coupons matching the specified criteria.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
value | string Example: value=SUMMER10 Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters. |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
createdAfter | string <date-time> Example: createdAfter=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
startsAfter | string <date-time> Example: startsAfter=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon start date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
startsBefore | string <date-time> Example: startsBefore=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon start date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
expiresAfter | string <date-time> Example: expiresAfter=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon expiration date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
expiresBefore | string <date-time> Example: expiresBefore=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon expiration date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
valid | string Enum: "expired" "validNow" "validFuture" Example: valid=validNow
|
batchId | string Example: batchId=nfinccze Filter results by batches of coupons |
usable | string Enum: "true" "false" Example: usable=false
|
referralId | integer Example: referralId=47 Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code. |
recipientIntegrationId | string Example: recipientIntegrationId=customer1 Filter results by match with a profile ID specified in the coupon's |
exactMatch | boolean Default: false Filter results to an exact case-insensitive matching against the coupon code |
Create coupons according to some pattern for up to 1000 recipients.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
silent | string Default: "yes" Example: silent=yes Possible values:
|
body
recipientsIntegrationIds required | Array of strings [ 1 .. 1000 ] items The integration IDs for recipients. |
usageLimit required | integer [ 0 .. 999999 ] The number of times the coupon code can be redeemed. |
discountLimit | number [ 0 .. 1000000000000000 ] The total discount value that the code can give. Typically used to represent a gift card value. |
reservationLimit | integer [ 0 .. 999999 ] The number of reservations that can be made with this coupon code. |
startDate | string <date-time> Timestamp at which point the coupon becomes valid. |
expiryDate | string <date-time> Expiration date of the coupon. Coupon never expires if this is omitted. |
attributes | object Arbitrary properties associated with this item. |
validCharacters | Array of strings List of characters used to generate the random parts of a code. By default, the list of
characters is equivalent to the |
couponPattern | string [ 3 .. 100 ] characters The pattern used to generate coupon codes. The character |
{- "usageLimit": 100,
- "discountLimit": 30,
- "reservationLimit": 45,
- "startDate": "2020-01-24T14:15:22Z",
- "expiryDate": "2023-08-24T14:15:22Z",
- "attributes": {
- "venueId": 12
}, - "recipientsIntegrationIds": [
- "URNGV8294NV",
- "BZGGC2454PA"
], - "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z"
], - "couponPattern": "SUMMER-#####"
}
{- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "campaignId": 211,
- "value": "XMAS-20-2021",
- "usageLimit": 100,
- "discountLimit": 30,
- "reservationLimit": 45,
- "startDate": "2020-01-24T14:15:22Z",
- "expiryDate": "2023-08-24T14:15:22Z",
- "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "usageCounter": 10,
- "discountCounter": 10,
- "discountRemainder": 5,
- "reservationCounter": 1,
- "attributes": { },
- "referralId": 326632952,
- "recipientIntegrationId": "URNGV8294NV",
- "importId": 4,
- "reservation": false,
- "batchId": "32535-43255",
- "isReservationMandatory": false,
- "implicitlyReserved": false
}
]
}
Create up to 5,000,000 coupons asynchronously. You should typically use this enpdoint when you create at least 20,001 coupons. You receive an email when the creation is complete.
If you want to create less than 20,001 coupons, you can use the Create coupons endpoint.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
body
numberOfCoupons required | integer [ 1 .. 5000000 ] The number of new coupon codes to generate for the campaign. | ||||
usageLimit required | integer [ 0 .. 999999 ] The number of times the coupon code can be redeemed. | ||||
attributes required | object Arbitrary properties associated with coupons. | ||||
discountLimit | number [ 0 .. 1000000000000000 ] The total discount value that the code can give. Typically used to represent a gift card value. | ||||
reservationLimit | integer [ 0 .. 999999 ] The number of reservations that can be made with this coupon code. | ||||
startDate | string <date-time> Timestamp at which point the coupon becomes valid. | ||||
expiryDate | string <date-time> Expiration date of the coupon. Coupon never expires if this is omitted. | ||||
object | |||||
|
{- "usageLimit": 100,
- "discountLimit": 30,
- "reservationLimit": 45,
- "startDate": "2020-01-24T14:15:22Z",
- "expiryDate": "2023-08-24T14:15:22Z",
- "numberOfCoupons": 200000,
- "couponSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "attributes": { }
}
{- "batchId": "tqyrgahe"
}
This endpoint handles creating a job to delete coupons asynchronously.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
body
required | object | ||||||||||||||||||||||||||||
|
{- "filters": {
- "createdBefore": "2019-08-24T14:15:22Z",
- "createdAfter": "2019-08-24T14:15:22Z",
- "startsAfter": "2019-08-24T14:15:22Z",
- "startsBefore": "2019-08-24T14:15:22Z",
- "valid": "expired",
- "usable": true,
- "redeemed": true,
- "recipientIntegrationId": "string",
- "exactMatch": false,
- "value": "string",
- "batchId": "string",
- "referralId": 0,
- "expiresAfter": "2019-08-24T14:15:22Z",
- "expiresBefore": "2019-08-24T14:15:22Z"
}
}
{- "id": 6
}
List all the coupons matching the specified criteria.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
value | string Example: value=SUMMER10 Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters. |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
createdAfter | string <date-time> Example: createdAfter=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
valid | string Enum: "expired" "validNow" "validFuture" Example: valid=validNow Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiration date is set and in the past. The second matches coupons in which start date is null or in the past and expiration date is null or in the future, the third matches coupons in which start date is set and in the future. |
usable | string Enum: "true" "false" Example: usable=false Either "true" or "false". If "true", only coupons where |
redeemed | string Enum: "true" "false" Example: redeemed=false
|
referralId | integer Example: referralId=47 Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code. |
recipientIntegrationId | string Example: recipientIntegrationId=customer1 Filter results by match with a profile ID specified in the coupon's RecipientIntegrationId field. |
batchId | string Example: batchId=nfinccze Filter results by batches of coupons |
exactMatch | boolean Default: false Filter results to an exact case-insensitive matching against the coupon code. |
expiresBefore | string <date-time> Example: expiresBefore=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon expiration date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
expiresAfter | string <date-time> Example: expiresAfter=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon expiration date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
startsBefore | string <date-time> Example: startsBefore=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon start date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
startsAfter | string <date-time> Example: startsAfter=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon start date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
valuesOnly | boolean Default: false Filter results to only return the coupon codes ( |
{- "hasMore": true,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "campaignId": 211,
- "value": "XMAS-20-2021",
- "usageLimit": 100,
- "discountLimit": 30,
- "reservationLimit": 45,
- "startDate": "2020-01-24T14:15:22Z",
- "expiryDate": "2023-08-24T14:15:22Z",
- "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "usageCounter": 10,
- "discountCounter": 10,
- "discountRemainder": 5,
- "reservationCounter": 1,
- "attributes": { },
- "referralId": 326632952,
- "recipientIntegrationId": "URNGV8294NV",
- "importId": 4,
- "reservation": false,
- "batchId": "32535-43255",
- "isReservationMandatory": false,
- "implicitlyReserved": false
}
]
}
Update the specified coupon.
Important
With this PUT
endpoint, if you do not explicitly set a value for the startDate
, expiryDate
, and recipientIntegrationId
properties in your request, it is automatically set to null
.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
couponId required | string Example: 1194 The internal ID of the coupon code. You can find this value in the |
body
usageLimit | integer [ 0 .. 999999 ] The number of times the coupon code can be redeemed. | ||||||||
discountLimit | number [ 0 .. 1000000000000000 ] The total discount value that the code can give. Typically used to represent a gift card value. | ||||||||
reservationLimit | integer [ 0 .. 999999 ] The number of reservations that can be made with this coupon code. | ||||||||
startDate | string <date-time> Timestamp at which point the coupon becomes valid. | ||||||||
expiryDate | string <date-time> Expiration date of the coupon. Coupon never expires if this is omitted. | ||||||||
Array of objects Limits configuration for a coupon. These limits will override the limits set from the campaign. Note: Only usable when creating a single coupon which is not tied to a specific recipient. Only per-profile limits are allowed to be configured. | |||||||||
Array
| |||||||||
recipientIntegrationId | string <= 1000 characters The integration ID for this coupon's beneficiary's profile. | ||||||||
attributes | object Arbitrary properties associated with this item. | ||||||||
isReservationMandatory | boolean Default: false An indication of whether the code can be redeemed only if it has been reserved first. | ||||||||
implicitlyReserved | boolean An indication of whether the coupon is implicitly reserved for all customers. |
{- "usageLimit": 100,
- "discountLimit": 30,
- "reservationLimit": 45,
- "startDate": "2020-01-24T14:15:22Z",
- "expiryDate": "2023-08-24T14:15:22Z",
- "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "recipientIntegrationId": "URNGV8294NV",
- "attributes": { },
- "isReservationMandatory": false,
- "implicitlyReserved": false
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "campaignId": 211,
- "value": "XMAS-20-2021",
- "usageLimit": 100,
- "discountLimit": 30,
- "reservationLimit": 45,
- "startDate": "2020-01-24T14:15:22Z",
- "expiryDate": "2023-08-24T14:15:22Z",
- "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "usageCounter": 10,
- "discountCounter": 10,
- "discountRemainder": 5,
- "reservationCounter": 1,
- "attributes": { },
- "referralId": 326632952,
- "recipientIntegrationId": "URNGV8294NV",
- "importId": 4,
- "reservation": false,
- "batchId": "32535-43255",
- "isReservationMandatory": false,
- "implicitlyReserved": false
}
Delete the specified coupon.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
couponId required | string Example: 1194 The internal ID of the coupon code. You can find this value in the |
List the coupons whose attributes match the query criteria in the given campaign.
The match is successful if all the attributes of the request are found in a coupon, even if the coupon has more attributes that are not present on the request.
Note: The total count is not included in the response.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
value | string Example: value=SUMMER10 Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters. |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
createdAfter | string <date-time> Example: createdAfter=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
valid | string Enum: "expired" "validNow" "validFuture" Example: valid=validNow Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiration date is set and in the past. The second matches coupons in which start date is null or in the past and expiration date is null or in the future, the third matches coupons in which start date is set and in the future. |
usable | string Enum: "true" "false" Example: usable=false Either "true" or "false". If "true", only coupons where |
referralId | integer Example: referralId=47 Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code. |
recipientIntegrationId | string Example: recipientIntegrationId=customer1 Filter results by match with a profile ID specified in the coupon's RecipientIntegrationId field. |
exactMatch | boolean Default: false Filter results to an exact case-insensitive matching against the coupon code. |
batchId | string Example: batchId=nfinccze Filter results by batches of coupons |
body
Object representing a set of of attributes and their respective values.
{- "my_attribute_1": "some value",
- "my_attribute_2": "some other value",
- "my_attribute_3": "some other value"
}
{- "hasMore": true,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "campaignId": 211,
- "value": "XMAS-20-2021",
- "usageLimit": 100,
- "discountLimit": 30,
- "reservationLimit": 45,
- "startDate": "2020-01-24T14:15:22Z",
- "expiryDate": "2023-08-24T14:15:22Z",
- "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "usageCounter": 10,
- "discountCounter": 10,
- "discountRemainder": 5,
- "reservationCounter": 1,
- "attributes": { },
- "referralId": 326632952,
- "recipientIntegrationId": "URNGV8294NV",
- "importId": 4,
- "reservation": false,
- "batchId": "32535-43255",
- "isReservationMandatory": false,
- "implicitlyReserved": false
}
]
}
List the coupons whose attributes match the query criteria in all the campaigns of the given Application.
The match is successful if all the attributes of the request are found in a coupon, even if the coupon has more attributes that are not present on the request.
Note: The total count is not included in the response.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
value | string Example: value=SUMMER10 Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters. |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
createdAfter | string <date-time> Example: createdAfter=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
valid | string Enum: "expired" "validNow" "validFuture" Example: valid=validNow Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiration date is set and in the past. The second matches coupons in which start date is null or in the past and expiration date is null or in the future, the third matches coupons in which start date is set and in the future. |
usable | string Enum: "true" "false" Example: usable=false Either "true" or "false". If "true", only coupons where |
referralId | integer Example: referralId=47 Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code. |
recipientIntegrationId | string Example: recipientIntegrationId=customer1 Filter results by match with a profile ID specified in the coupon's RecipientIntegrationId field. |
batchId | string Example: batchId=nfinccze Filter results by batches of coupons |
exactMatch | boolean Default: false Filter results to an exact case-insensitive matching against the coupon code. |
campaignState | string Enum: "enabled" "disabled" "archived" "scheduled" "running" "expired" "staged" Example: campaignState=enabled Filter results by the state of the campaign.
|
body
Object representing a set of of attributes and their respective values.
{- "my_attribute_1": "some value",
- "my_attribute_2": "some other value",
- "my_attribute_3": "some other value"
}
{- "hasMore": true,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "campaignId": 211,
- "value": "XMAS-20-2021",
- "usageLimit": 100,
- "discountLimit": 30,
- "reservationLimit": 45,
- "startDate": "2020-01-24T14:15:22Z",
- "expiryDate": "2023-08-24T14:15:22Z",
- "limits": [
- {
- "action": "createCoupon",
- "limit": 1000,
- "period": "yearly",
- "entities": [
- "Coupon"
]
}
], - "usageCounter": 10,
- "discountCounter": 10,
- "discountRemainder": 5,
- "reservationCounter": 1,
- "attributes": { },
- "referralId": 326632952,
- "recipientIntegrationId": "URNGV8294NV",
- "importId": 4,
- "reservation": false,
- "batchId": "32535-43255",
- "isReservationMandatory": false,
- "implicitlyReserved": false
}
]
}
Upload a CSV file containing the coupons that should be created. The file should be sent as multipart data.
The CSV file contains the following columns:
value
(required): The coupon code.
expirydate
: The end date in RFC3339 of the code redemption period.
startdate
: The start date in RFC3339 of the code redemption period.
recipientintegrationid
: The integration ID of the recipient of the coupon.
Only the customer with this integration ID can redeem this code. Available only for personal codes.
limitval
: The maximum number of redemptions of this code. For unlimited redemptions, use 0
. Defaults to 1
when not provided.
discountlimit
: The total discount value that the code can give. This is typically used to represent a gift card value.
attributes
: A JSON object describing custom coupon attribute names and their values, enclosed with double quotation marks.
For example, if you created a custom attribute
called category
associated with the coupon entity, the object in the CSV file, when opened in a text editor, must be: "{"category": "10_off"}"
.
You can use the time zone of your choice. It is converted to UTC internally by Talon.One.
Note: We recommend limiting your file size to 500MB.
Example:
"value","expirydate","startdate","recipientintegrationid","limitval","attributes","discountlimit"
COUP1,2018-07-01T04:00:00Z,2018-05-01T04:00:00Z,cust123,1,"{""Category"": ""10_off""}",2.4
Once imported, you can find the batchId
in the Campaign Manager or by
using List coupons.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
skipDuplicates | boolean An indicator of whether to skip duplicate coupon values instead of causing an error.
Duplicate values are ignored when |
upFile | string <csv> The file containing the data that is being imported. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "userId": 388,
- "entity": "AttributeAllowedList",
- "amount": 10
}
Download a CSV file containing the coupons that match the given properties.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
The CSV file can contain the following columns:
accountid
: The ID of your deployment.applicationid
: The ID of the Application this coupon is related to.attributes
: A json object describing custom referral attribute names and their values.batchid
: The ID of the batch this coupon is part of.campaignid
: The ID of the campaign this coupon is related to.counter
: The number of times this coupon has been redeemed.created
: The creation date in RFC3339 of the coupon code.deleted
: Whether the coupon code is deleted.deleted_changelogid
: The ID of the delete event in the logs.discount_counter
: The amount of discount given by this coupon.discount_limitval
: The maximum discount amount that can be given be this coupon.expirydate
: The end date in RFC3339 of the code redemption period.id
: The internal ID of the coupon code.importid
: The ID of the import job that created this coupon.is_reservation_mandatory
: Whether this coupon requires a reservation to be redeemed.limits
: The limits set on this coupon.limitval
: The maximum number of redemptions of this code.recipientintegrationid
: The integration ID of the recipient of the coupon.
Only the customer with this integration ID can redeem this code. Available only for personal codes.referralid
: The ID of the referral code that triggered the creation of this coupon (create coupon effect).reservation
: Whether the coupon can be reserved for multiple customers.reservation_counter
: How many times this coupon has been reserved.reservation_limitval
: The maximum of number of reservations this coupon can have.startdate
: The start date in RFC3339 of the code redemption period.value
: The coupon code.applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId | number Example: campaignId=49 Filter results by campaign ID. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
value | string Example: value=SUMMER10 Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters. |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
createdAfter | string <date-time> Example: createdAfter=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
valid | string Enum: "expired" "validNow" "validFuture" Example: valid=validNow Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiration date is set and in the past. The second matches coupons in which start date is null or in the past and expiration date is null or in the future, the third matches coupons in which start date is set and in the future. |
usable | string Enum: "true" "false" Example: usable=false Either "true" or "false". If "true", only coupons where |
referralId | integer Example: referralId=47 Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code. |
recipientIntegrationId | string Example: recipientIntegrationId=customer1 Filter results by match with a profile id specified in the coupon's RecipientIntegrationId field. |
batchId | string Example: batchId=nfinccze Filter results by batches of coupons |
exactMatch | boolean Default: false Filter results to an exact case-insensitive matching against the coupon code. |
dateFormat | string Enum: "excel" "ISO8601" Example: dateFormat=excel Determines the format of dates in the export document. |
campaignState | string Enum: "enabled" "disabled" "archived" "scheduled" "running" "expired" "staged" Example: campaignState=enabled Filter results by the state of the campaign.
|
valuesOnly | boolean Default: false Filter results to only return the coupon codes ( |
id,created,campaignid,value,expirydate,startdate,attributes,applicationid,deleted,deleted_changelogid,accountid,referralid,recipientintegrationid,importid,batchid,reservation,limits,limitval,counter,discount_counter,discount_limitval 20191301,2022-04-26T11:02:38Z,3882,COUP1,2022-04-27T10:56:47Z,2022-04-26T10:56:47Z,"{""test"": ""premium""}",270,,0,1,,cust123,671,axghjfdy,,"[]",1,0,0,1.5
Represents the data of a customer, including sessions and events used for reporting and debugging in the Campaign Manager.
List all the customers of the specified application.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
integrationId | string Example: integrationId=customer1 Filter results performing an exact matching against the profile integration identifier. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
withTotalResultSize | boolean When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.
|
{- "totalResultSize": 1,
- "hasMore": true,
- "data": [
- {
- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "integrationId": "URNGV8294NV",
- "attributes": {
- "Language": "english",
- "ShippingCountry": "DE"
}, - "accountId": 0,
- "closedSessions": 3,
- "totalSales": 299.99,
- "loyaltyMemberships": [
- {
- "joined": "2012-03-20T14:15:22Z",
- "loyaltyProgramId": 323414846
}
], - "audienceMemberships": [
- {
- "id": 2,
- "name": "Travel audience"
}
], - "lastActivity": "2020-02-08T14:15:20Z",
- "sandbox": false,
- "advocateIntegrationId": "string"
}
]
}
Get a list of the application customers matching the provided criteria.
The match is successful if all the attributes of the request are found in a profile, even if the profile has more attributes that are not present on the request.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
withTotalResultSize | boolean When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.
|
body
attributes | object Properties to match against a customer profile. All provided attributes will be exactly matched against profile attributes. |
integrationIDs | Array of strings |
profileIDs | Array of integers |
{- "attributes": { },
- "integrationIDs": [
- "string"
], - "profileIDs": [
- 0
]
}
{- "hasMore": true,
- "totalResultSize": 0,
- "data": [
- {
- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "integrationId": "URNGV8294NV",
- "attributes": {
- "Language": "english",
- "ShippingCountry": "DE"
}, - "accountId": 0,
- "closedSessions": 3,
- "totalSales": 299.99,
- "loyaltyMemberships": [
- {
- "joined": "2012-03-20T14:15:22Z",
- "loyaltyProgramId": 323414846
}
], - "audienceMemberships": [
- {
- "id": 2,
- "name": "Travel audience"
}
], - "lastActivity": "2020-02-08T14:15:20Z",
- "sandbox": false,
- "advocateIntegrationId": "string"
}
]
}
Get a list of the customer profiles matching the provided criteria.
The match is successful if all the attributes of the request are found in a profile, even if the profile has more attributes that are not present on the request.
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sandbox | boolean Default: false Indicates whether you are pointing to a sandbox or live customer. |
body
attributes | object Properties to match against a customer profile. All provided attributes will be exactly matched against profile attributes. |
integrationIDs | Array of strings |
profileIDs | Array of integers |
{- "attributes": { },
- "integrationIDs": [
- "string"
], - "profileIDs": [
- 0
]
}
{- "hasMore": true,
- "totalResultSize": 0,
- "data": [
- {
- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "integrationId": "URNGV8294NV",
- "attributes": {
- "Language": "english",
- "ShippingCountry": "DE"
}, - "accountId": 31,
- "closedSessions": 3,
- "totalSales": 299.99,
- "loyaltyMemberships": [
- {
- "joined": "2012-03-20T14:15:22Z",
- "loyaltyProgramId": 323414846
}
], - "audienceMemberships": [
- {
- "id": 2,
- "name": "Travel audience"
}
], - "lastActivity": "2020-02-08T14:15:20Z",
- "sandbox": false
}
]
}
Return the details of the specified customer profile.
Performance tips
You can retrieve the same information via the Integration API, which can save you extra API requests. consider these options:
runRuleEngine=false
.customerId required | integer Example: 3778 The value of the |
{- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "integrationId": "URNGV8294NV",
- "attributes": {
- "Language": "english",
- "ShippingCountry": "DE"
}, - "accountId": 31,
- "closedSessions": 3,
- "totalSales": 299.99,
- "loyaltyMemberships": [
- {
- "joined": "2012-03-20T14:15:22Z",
- "loyaltyProgramId": 323414846
}
], - "audienceMemberships": [
- {
- "id": 2,
- "name": "Travel audience"
}
], - "lastActivity": "2020-02-08T14:15:20Z",
- "sandbox": false
}
List all customer profiles.
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sandbox | boolean Default: false Indicates whether you are pointing to a sandbox or live customer. |
{- "hasMore": true,
- "data": [
- {
- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "integrationId": "URNGV8294NV",
- "attributes": {
- "Language": "english",
- "ShippingCountry": "DE"
}, - "accountId": 31,
- "closedSessions": 3,
- "totalSales": 299.99,
- "loyaltyMemberships": [
- {
- "joined": "2012-03-20T14:15:22Z",
- "loyaltyProgramId": 323414846
}
], - "audienceMemberships": [
- {
- "id": 2,
- "name": "Travel audience"
}
], - "lastActivity": "2020-02-08T14:15:20Z",
- "sandbox": false
}
]
}
Retrieve the customers of the specified application.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
customerId required | integer Example: 3778 The value of the |
{- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "integrationId": "URNGV8294NV",
- "attributes": {
- "Language": "english",
- "ShippingCountry": "DE"
}, - "accountId": 0,
- "closedSessions": 3,
- "totalSales": 299.99,
- "loyaltyMemberships": [
- {
- "joined": "2012-03-20T14:15:22Z",
- "loyaltyProgramId": 323414846
}
], - "audienceMemberships": [
- {
- "id": 2,
- "name": "Travel audience"
}
], - "lastActivity": "2020-02-08T14:15:20Z",
- "sandbox": false,
- "advocateIntegrationId": "string"
}
Fetch summary reports for all application customers based on a time range. Instead of having the total number of results in the response, this endpoint only mentions whether there are more results.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
rangeStart required | string <date-time> Example: rangeStart=2024-05-29T15:04:05+07:00 Only return results from after this timestamp. Note:
|
rangeEnd required | string <date-time> Example: rangeEnd=2024-05-29T15:04:05+07:00 Only return results from before this timestamp. Note:
|
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
name | string Example: name=customer1 Only return reports matching the customer name. |
integrationId | string Example: integrationId=customer1 Filter results performing an exact matching against the profile integration identifier. |
campaignName | string Example: campaignName=campaign1 Only return reports matching the campaign name. |
advocateName | string Example: advocateName=advocate1 Only return reports matching the current customer referrer name. |
{- "hasMore": true,
- "data": [
- {
- "integrationId": "URNGV8294NV",
- "created": "2020-02-07T08:15:22Z",
- "name": "string",
- "customerId": 0,
- "lastActivity": "2019-08-24T14:15:22Z",
- "couponRedemptions": 0,
- "couponUseAttempts": 0,
- "couponFailedAttempts": 0,
- "accruedDiscounts": 0,
- "accruedRevenue": 0,
- "totalOrders": 0,
- "totalOrdersNoCoupon": 0,
- "campaignName": "string"
}
]
}
Fetch the summary report of a given customer in the given application, in a time range.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
customerId required | integer Example: 3778 The value of the |
rangeStart required | string <date-time> Example: rangeStart=2024-05-29T15:04:05+07:00 Only return results from after this timestamp. Note:
|
rangeEnd required | string <date-time> Example: rangeEnd=2024-05-29T15:04:05+07:00 Only return results from before this timestamp. Note:
|
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
{- "integrationId": "URNGV8294NV",
- "created": "2020-02-07T08:15:22Z",
- "name": "string",
- "customerId": 0,
- "lastActivity": "2019-08-24T14:15:22Z",
- "couponRedemptions": 0,
- "couponUseAttempts": 0,
- "couponFailedAttempts": 0,
- "accruedDiscounts": 0,
- "accruedRevenue": 0,
- "totalOrders": 0,
- "totalOrdersNoCoupon": 0,
- "campaignName": "string"
}
Fetch analytics for a given customer in the given application.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
customerId required | integer Example: 3778 The value of the |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
{- "acceptedCoupons": 0,
- "createdCoupons": 0,
- "freeItems": 0,
- "totalOrders": 0,
- "totalDiscountedOrders": 0,
- "totalRevenue": 0,
- "totalDiscounts": 0
}
List all the sessions of the specified Application.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
profile | string Example: profile=customer1 Profile integration ID filter for sessions. Must be exact match. |
state | string Enum: "open" "closed" "partially_returned" "cancelled" Example: state=open Filter by sessions with this state. Must be exact match. |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Only return events created before this date. You can use any time zone setting. Talon.One will convert to UTC internally. |
createdAfter | string <date-time> Example: createdAfter=2024-05-29T15:04:05+07:00 Only return events created after this date. You can use any time zone setting. Talon.One will convert to UTC internally. |
coupon | string Example: coupon=SUMMER10 Filter by sessions with this coupon. Must be exact match. |
referral | string Example: referral=WPCNAQ5C Filter by sessions with this referral. Must be exact match. |
integrationId | string Example: integrationId=customer1 Filter by sessions with this integration ID. Must be exact match. |
storeIntegrationId | string Example: storeIntegrationId=store1 The integration ID of the store. You choose this ID when you create a store. |
{- "hasMore": true,
- "data": [
- {
- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "integrationId": "URNGV8294NV",
- "storeIntegrationId": "STORE-001",
- "applicationId": 322,
- "profileId": 138,
- "profileintegrationid": "382370BKDB946",
- "coupon": "BKDB946",
- "referral": "BKDB946",
- "state": "closed",
- "cartItems": [
- {
- "name": "Air Glide",
- "sku": "SKU1241028",
- "quantity": 1,
- "returnedQuantity": 1,
- "remainingQuantity": 1,
- "price": 99.99,
- "category": "shoes",
- "product": {
- "name": "sample_product"
}, - "weight": 1130,
- "height": 0,
- "width": 0,
- "length": 0,
- "position": 0,
- "attributes": {
- "image": "11.jpeg",
- "material": "leather"
}, - "additionalCosts": {
- "shipping": {
- "price": 9
}
}, - "catalogItemID": 0,
- "selectedPriceType": "member",
- "adjustmentReferenceId": "68851723-e6fa-488f-ace9-112581e6c19b",
- "adjustmentEffectiveFrom": "2021-09-12T10:12:42Z",
- "adjustmentEffectiveUntil": "2021-09-12T10:12:42Z",
- "prices": {
- "member": {
- "price": 90,
- "adjustmentReferenceId": "68851723-e6fa-488f-ace9-112581e6c19b",
- "effectiveFrom": "2025-05-25T00:00:00Z",
- "effectiveUntil": "2025-05-30T00:00:00Z"
}, - "base": {
- "price": 100
}
}
}
], - "discounts": {
- "property1": 0,
- "property2": 0
}, - "totalDiscounts": 100,
- "total": 200,
- "attributes": { }
}
]
}
Get the details of the given session. You can list the sessions with the List Application sessions endpoint.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
sessionId required | integer Example: 2533 The internal ID of the session. You can get the ID with the List Application sessions endpoint. |
{- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "integrationId": "URNGV8294NV",
- "storeIntegrationId": "STORE-001",
- "applicationId": 322,
- "profileId": 138,
- "profileintegrationid": "382370BKDB946",
- "coupon": "BKDB946",
- "referral": "BKDB946",
- "state": "closed",
- "cartItems": [
- {
- "name": "Air Glide",
- "sku": "SKU1241028",
- "quantity": 1,
- "returnedQuantity": 1,
- "remainingQuantity": 1,
- "price": 99.99,
- "category": "shoes",
- "product": {
- "name": "sample_product"
}, - "weight": 1130,
- "height": 0,
- "width": 0,
- "length": 0,
- "position": 0,
- "attributes": {
- "image": "11.jpeg",
- "material": "leather"
}, - "additionalCosts": {
- "shipping": {
- "price": 9
}
}, - "catalogItemID": 0,
- "selectedPriceType": "member",
- "adjustmentReferenceId": "68851723-e6fa-488f-ace9-112581e6c19b",
- "adjustmentEffectiveFrom": "2021-09-12T10:12:42Z",
- "adjustmentEffectiveUntil": "2021-09-12T10:12:42Z",
- "prices": {
- "member": {
- "price": 90,
- "adjustmentReferenceId": "68851723-e6fa-488f-ace9-112581e6c19b",
- "effectiveFrom": "2025-05-25T00:00:00Z",
- "effectiveUntil": "2025-05-30T00:00:00Z"
}, - "base": {
- "price": 100
}
}
}
], - "discounts": {
- "property1": 0,
- "property2": 0
}, - "totalDiscounts": 100,
- "total": 200,
- "attributes": { }
}
Lists all events recorded for an application. Instead of having the total number of results in the response, this endpoint only mentions whether there are more results.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
type | string Example: type=talon_session_created,talon_session_updated Comma-separated list of types by which to filter events. Must be exact match(es). |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Only return events created before this date. You can use any time zone setting. Talon.One will convert to UTC internally. |
createdAfter | string <date-time> Example: createdAfter=2024-05-29T15:04:05+07:00 Only return events created after this date. You can use any time zone setting. Talon.One will convert to UTC internally. |
session | string Example: session=session1 Session integration ID filter for events. Must be exact match. |
profile | string Example: profile=profile1 Profile integration ID filter for events. Must be exact match. |
customerName | string >= 2 characters Example: customerName=customer1 Customer name filter for events. Will match substrings case-insensitively. |
customerEmail | string >= 2 characters Example: customerEmail=john@doe.com Customer e-mail address filter for events. Will match substrings case-insensitively. |
couponCode | string Example: couponCode=SUMMER10 Coupon code |
referralCode | string Example: referralCode=WPCNAQ5C Referral code |
ruleQuery | string Example: ruleQuery=rule1 Rule name filter for events |
campaignQuery | string Example: campaignQuery=campaign1 Campaign name filter for events |
{- "hasMore": true,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "applicationId": 322,
- "profileId": 138,
- "storeId": 0,
- "storeIntegrationId": "STORE-001",
- "sessionId": 0,
- "type": "string",
- "attributes": { },
- "effects": [
- {
- "campaignId": 244,
- "rulesetId": 73,
- "ruleIndex": 2,
- "ruleName": "Give 20% discount",
- "effectType": "rejectCoupon",
- "triggeredByCoupon": 4928,
- "triggeredForCatalogItem": 786,
- "conditionIndex": 786,
- "evaluationGroupID": 3,
- "evaluationGroupMode": "stackable",
- "campaignRevisionId": 1,
- "campaignRevisionVersionId": 5,
- "selectedPriceType": "member",
- "selectedPrice": 100,
- "adjustmentReferenceId": "68851723-e6fa-488f-ace9-112581e6c19b",
- "props": {
- "value": "string"
}
}
], - "ruleFailureReasons": [
- {
- "campaignID": 0,
- "campaignName": "string",
- "rulesetID": 0,
- "couponID": 4928,
- "couponValue": "string",
- "referralID": 0,
- "referralValue": "string",
- "ruleIndex": 0,
- "ruleName": "string",
- "conditionIndex": 0,
- "effectIndex": 0,
- "details": "string",
- "evaluationGroupID": 3,
- "evaluationGroupMode": "stackable"
}
]
}
]
}
Get all of the distinct values of the Event type
property for events recorded in the application.
See also: Track an event
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
{- "totalResultSize": 1,
- "data": [
- "string"
]
}
Represents a single occurrence of a specific customer action, for example, updating the cart or signing up for a newsletter.
There are 2 types of events:
Fetch all event type definitions for your account.
name | string Example: name=event1 Filter results to event types with the given name. This parameter implies |
includeOldVersions | boolean Default: false Include all versions of every event type. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
{- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "title": "Survey Completed",
- "name": "surveyCompleted",
- "description": "The survey was submitted by the customer."
}
]
}
Represents a program that rewards customers with giveaways, such as free gift cards.
See the docs.
Upload a CSV file containing the giveaway codes that should be created. Send the file as multipart data.
The CSV file contains the following columns:
code
(required): The code of your giveaway, for instance, a gift card redemption code.
startdate
: The start date in RFC3339 of the code redemption period.
enddate
: The last date in RFC3339 of the code redemption period.
attributes
: A JSON object describing custom giveaway attribute names and their values, enclosed with double quotation marks.
For example, if you created a custom attribute
called provider
associated with the giveaway entity, the object in the CSV file, when opened in a text editor, must be: "{"provider": "myPartnerCompany"}"
.
The startdate
and enddate
have nothing to do with the validity of the codes. They are only used by the Rule Engine to award the codes or not.
You can use the time zone setting of your choice. The values are converted to UTC internally by Talon.One.
Note:
Example:
code,startdate,enddate,attributes
GIVEAWAY1,2020-11-10T23:00:00Z,2022-11-11T23:00:00Z,"{""provider"": ""Amazon""}"
GIVEAWAY2,2020-11-10T23:00:00Z,2022-11-11T23:00:00Z,"{""provider"": ""Amazon""}"
GIVEAWAY3,2021-01-10T23:00:00Z,2022-11-11T23:00:00Z,"{""provider"": ""Aliexpress""}"
poolId required | integer Example: 8 The ID of the pool. You can find it in the Campaign Manager, in the Giveaways section. |
upFile | string <csv> The file containing the data that is being imported. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "userId": 388,
- "entity": "AttributeAllowedList",
- "amount": 10
}
Download a CSV file containing the giveaway codes of a specific giveaway pool.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
The CSV file contains the following columns:
id
: The internal ID of the giveaway.poolid
: The internal ID of the giveaway pool.code
: The giveaway code.startdate
: The validity start date in RFC3339 of the giveaway (can be empty).enddate
: The validity end date in RFC3339 of the giveaway (can be empty).attributes
: Any custom attributes associated with the giveaway code (can be empty).used
: An indication of whether the giveaway is already awarded.importid
: The ID of the import which created the giveaway.created
: The creation time of the giveaway code.profileintegrationid
: The third-party integration ID of the customer profile that was awarded the giveaway. Can be empty if the giveaway was not awarded.profileid
: The internal ID of the customer profile that was awarded the giveaway. Can be empty if the giveaway was not awarded or an internal ID does not exist.poolId required | integer Example: 8 The ID of the pool. You can find it in the Campaign Manager, in the Giveaways section. |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Timestamp that filters the results to only contain giveaways created before this date. Must be an RFC3339 timestamp string. |
createdAfter | string <date-time> Example: createdAfter=2024-05-29T15:04:05+07:00 Timestamp that filters the results to only contain giveaways created after this date. Must be an RFC3339 timestamp string. |
id,poolid,code,startdate,enddate,attributes,used,importid,created,profileintegrationid,profileid 1,7,af18bc3839799451fb6d6b6467cf4c25e,2023-04-11T12:47:47Z,2024-04-11T12:47:47Z,"{""attribute"": ""value""}",true,2,2023-04-11T12:47:47Z,R195412,35
Retrieve the list of API calls sent to the specified Application.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
rangeStart required | string <date-time> Example: rangeStart=2024-05-29T15:04:05+07:00 Only return results from after this timestamp. Note:
|
rangeEnd required | string <date-time> Example: rangeEnd=2024-05-29T15:04:05+07:00 Only return results from before this timestamp. Note:
|
path | string Example: path=pattern1 Only return results where the request path matches the given regular expression. |
method | string Enum: "get" "put" "post" "delete" "patch" Example: method=get Only return results where the request method matches the given regular expression. |
status | string Enum: "success" "error" Example: status=success Filter results by HTTP status codes. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
{- "hasMore": true,
- "data": [
- {
- "uuid": "606e7d34-2d36-4d53-ac71-d4442c325985",
- "status": 200,
- "method": "PUT",
- "requestUri": "/v2/customer_sessions/Session136667",
- "time": "2023-01-16T16:00:00.700763Z",
- "requestPayload": "{\n \"customerSession\": {\n \"profileId\": \"customer123\",\n \"state\": \"closed\",\n...\n}",
- "responsePayload": "{\"coupons\":[],\"createdCoupons\":[],...}"
}
]
}
Retrieve all message log entries.
entityType required | string Enum: "application" "loyalty_program" "webhook" Example: entityType=application The entity type the log is related to. |
messageID | string Example: messageID=message1 Filter results by message ID. |
changeType | string Enum: "CampaignEvaluationTreeChanged" "CampaignNotification" "CouponCreated" "CouponUpdated" "CouponDeleted" "AsyncCouponsCreated" "CouponsDeleted" "CouponsUpdated" "CouponCodeExpiring" "StrikethroughPrice" … 12 more Example: changeType=CampaignEvaluationTreeChanged Filter results by change type. |
notificationIDs | string Example: notificationIDs=23,46 Filter results by notification ID (include up to 30 values, separated by a comma). |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Filter results where request and response times to return entries before parameter value, expected to be an RFC3339 timestamp string. You can use any time zone setting. Talon.One will convert to UTC internally. |
createdAfter | string <date-time> Example: createdAfter=2024-05-29T15:04:05+07:00 Filter results where request and response times to return entries after parameter value, expected to be an RFC3339 timestamp string. You can use any time zone setting. Talon.One will convert to UTC internally. |
cursor | string <byte> Example: cursor=U3dhZ2dlciByb2Nrcw== A specific unique value in the database. If this value is not given, the server fetches results starting with the first record. |
period | string Enum: "15m" "30m" "1h" "4h" "1d" "2d" Example: period=15m Filter results by time period. Choose between the available relative time frames. |
isSuccessful | boolean Indicates whether to return log entries with either successful or unsuccessful HTTP response codes. When set to |
applicationId | number Example: applicationId=19 Filter results by Application ID. |
campaignId | number Example: campaignId=49 Filter results by campaign ID. |
loyaltyProgramId | integer Example: loyaltyProgramId=40 Identifier of the loyalty program. |
responseCode | integer Example: responseCode=200 Filter results by response status code. |
webhookIDs | string Example: webhookIDs=23,46 Filter results by webhook ID (include up to 30 values, separated by a comma). |
{- "nextCursor": "SmJlNERRMHdyNWFsTmRDZDVYU0c=",
- "data": [
- {
- "id": "123e4567-e89b-12d3-a456-426614174000",
- "service": "NotificationService",
- "changeType": "Update",
- "notificationId": 101,
- "notificationName": "My campaign notification",
- "webhookId": 101,
- "webhookName": "My webhook",
- "request": {
- "createdAt": "2021-07-20T21:59:00Z",
- "request": "SGVsbG8sIHdvcmxkIQ=="
}, - "response": {
- "createdAt": "2021-07-20T22:00:50Z",
- "response": "UmVzcG9uc2UgY29udGVudA==",
- "status": 200
}, - "createdAt": "2021-07-20T22:00:00Z",
- "entityType": "loyalty_program",
- "url": "www.my-company.com/my-endpoint-name",
- "applicationId": 5,
- "loyaltyProgramId": 2,
- "campaignId": 2
}
]
}
Retrieve the audit logs displayed in Accounts > Audit logs.
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
applicationId | number Example: applicationId=19 Filter results by Application ID. |
entityPath | string Example: entityPath=example/url/path Filter results on a case insensitive matching of the url path of the entity |
userId | integer Example: userId=34 Filter results by user ID. |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the change creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
createdAfter | string <date-time> Example: createdAfter=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the change creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
withTotalResultSize | boolean When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.
|
managementKeyId | integer Example: managementKeyId=16 Filter results that match the given management key ID. |
includeOld | boolean When this flag is set to false, the state without the change will not be returned. The default value is true. |
{- "totalResultSize": 1,
- "hasMore": true,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "userId": 388,
- "applicationId": 359,
- "entity": "/v1/applications/359/campaigns/6727",
- "old": { },
- "new": {
- "applicationId"": 359,
- "attributes"": { },
- "campaignGroups"": [ ],
- "created"": "2022-07-08T13:04:02.972762328Z",
- "description"": "",
- "features"": [
- "referrals",
- "loyalty"
], - "id": 6727
}, - "managementKeyId": 3
}
]
}
List all past exports
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
applicationId | number Example: applicationId=19 Filter results by Application ID. |
campaignId | integer Example: campaignId=8 Filter by the campaign ID on which the limit counters are used. |
entity | string Enum: "Coupon" "Referral" "Effect" "CustomerSession" "LoyaltyLedger" "LoyaltyLedgerLog" "Collection" "AudienceMembership" Example: entity=Coupon The name of the entity type that was exported. |
{- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "userId": 388,
- "entity": "Coupon",
- "filter": { }
}
]
}
Represents loyalty programs or concepts related to them.
Loyalty programs can be profile-based or card-based, depending on whether loyalty points are linked to customer profiles or loyalty cards.
See the Product docs for more information.
List the loyalty programs of the account.
{- "totalResultSize": 1,
- "data": [
- {
- "id": 139,
- "created": "2020-06-10T09:05:27.993483Z",
- "title": "Point collection",
- "description": "Customers collect 10 points per 1$ spent",
- "subscribedApplications": [
- 132,
- 97
], - "defaultValidity": "2W_U",
- "defaultPending": "immediate",
- "allowSubledger": false,
- "usersPerCardLimit": 111,
- "sandbox": true,
- "programJoinPolicy": "not_join",
- "tiersExpirationPolicy": "tier_start_date",
- "tierCycleStartDate": "2021-09-12T10:12:42Z",
- "tiersExpireIn": "27W_U",
- "tiersDowngradePolicy": "one_down",
- "cardCodeSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "returnPolicy": "only_pending",
- "accountID": 1,
- "name": "my_program",
- "tiers": [
- {
- "name": "Gold",
- "minPoints": 300,
- "id": 3,
- "created": "2021-06-10T09:05:27.993483Z",
- "programID": 139
}, - {
- "name": "Silver",
- "minPoints": 200,
- "id": 2,
- "created": "2021-06-10T09:04:59.355258Z",
- "programID": 139
}, - {
- "name": "Bronze",
- "minPoints": 100,
- "id": 1,
- "created": "2021-06-10T09:04:39.355258Z",
- "programID": 139
}
], - "timezone": "Europe/Berlin",
- "cardBased": true,
- "canUpdateTiers": true,
- "canUpdateJoinPolicy": true,
- "canUpdateTierExpirationPolicy": true,
- "canUpgradeToAdvancedTiers": true,
- "canUpdateSubledgers": true
}
]
}
Get the specified loyalty program. To list all loyalty programs in your Application, use List loyalty programs.
To list the loyalty programs that a customer profile is part of, use the List customer data
loyaltyProgramId required | integer Example: 8 Identifier of the loyalty program. You can get the ID with the List loyalty programs endpoint. |
{- "id": 139,
- "created": "2020-06-10T09:05:27.993483Z",
- "title": "Point collection",
- "description": "Customers collect 10 points per 1$ spent",
- "subscribedApplications": [
- 132,
- 97
], - "defaultValidity": "2W_U",
- "defaultPending": "immediate",
- "allowSubledger": false,
- "usersPerCardLimit": 111,
- "sandbox": true,
- "programJoinPolicy": "not_join",
- "tiersExpirationPolicy": "tier_start_date",
- "tierCycleStartDate": "2021-09-12T10:12:42Z",
- "tiersExpireIn": "27W_U",
- "tiersDowngradePolicy": "one_down",
- "cardCodeSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}, - "returnPolicy": "only_pending",
- "accountID": 1,
- "name": "my_program",
- "tiers": [
- {
- "name": "Gold",
- "minPoints": 300,
- "id": 3,
- "created": "2021-06-10T09:05:27.993483Z",
- "programID": 139
}, - {
- "name": "Silver",
- "minPoints": 200,
- "id": 2,
- "created": "2021-06-10T09:04:59.355258Z",
- "programID": 139
}, - {
- "name": "Bronze",
- "minPoints": 100,
- "id": 1,
- "created": "2021-06-10T09:04:39.355258Z",
- "programID": 139
}
], - "timezone": "Europe/Berlin",
- "cardBased": true,
- "canUpdateTiers": true,
- "canUpdateJoinPolicy": true,
- "canUpdateTierExpirationPolicy": true,
- "canUpgradeToAdvancedTiers": true,
- "canUpdateSubledgers": true
}
Retrieve the statistics displayed on the specified loyalty program's dashboard, such as the total active points, pending points, spent points, and expired points.
Important: The returned data does not include the current day. All statistics are updated daily at 11:59 PM in the loyalty program time zone.
loyaltyProgramId required | integer Example: 8 Identifier of the loyalty program. You can get the ID with the List loyalty programs endpoint. |
rangeStart required | string <date-time> Example: rangeStart=2024-05-29T15:04:05+07:00 Only return results from after this timestamp. Note:
|
rangeEnd required | string <date-time> Example: rangeEnd=2024-05-29T15:04:05+07:00 Only return results from before this timestamp. Note:
|
subledgerId | string Example: subledgerId=subledger1 The ID of the subledger by which we filter the data. |
{- "totalResultSize": 1,
- "data": [
- {
- "date": "2019-08-24T14:15:22Z",
- "totalActivePoints": 9756,
- "totalPendingPoints": 548,
- "totalSpentPoints": 25668,
- "totalExpiredPoints": 1156,
- "totalMembers": 2582,
- "newMembers": 3,
- "spentPoints": {
- "createdManually": 125,
- "createdViaRuleEngine": 9631
}, - "earnedPoints": {
- "createdManually": 125,
- "createdViaRuleEngine": 9631
}
}
]
}
Upload a CSV file containing the loyalty points you want to import into a given loyalty program. Send the file as multipart data.
Depending on the type of loyalty program, you can import points into a given customer profile or loyalty card.
The CSV file contains the following columns:
customerprofileid
(optional): For profile-based loyalty programs, the integration ID of the customer profile where the loyalty points are imported.
Note: If the customer profile does not exist, it will be created. The profile will not be visible in any Application until a session or profile update is received for that profile.
identifier
(optional): For card-based loyalty programs, the identifier of the loyalty card where the loyalty points are imported.
amount
: The amount of points to award to the customer profile.
startdate
(optional): The earliest date when the points can be redeemed. The points are active
from this date until the expiration date.
Note: It must be an RFC3339 timestamp string or string immediate
. Empty or missing values are considered immediate
.
expirydate
(optional): The latest date when the points can be redeemed. The points are expired
after this date.
Note: It must be an RFC3339 timestamp string or string unlimited
. Empty or missing values are considered unlimited
.
subledgerid
(optional): The ID of the subledger that should received the points.
reason
(optional): The reason why these points are awarded.
You can use the time zone of your choice. It is converted to UTC internally by Talon.One.
Note: For existing customer profiles and loyalty cards, the imported points are added to any previous active or pending points, depending on the
value provided for startdate
. If startdate
matches the current date, the imported points are active. If it is later, the points are pending until
the date provided for startdate
is reached.
Note: We recommend limiting your file size to 500MB.
Example for profile-based programs:
customerprofileid,amount,startdate,expirydate,subledgerid,reason
URNGV8294NV,100,2009-11-10T23:00:00Z,2009-11-11T23:00:00Z,subledger1,appeasement
Example for card-based programs:
identifier,amount,startdate,expirydate,subledgerid,reason
summer-loyalty-card-0543,100,2009-11-10T23:00:00Z,2009-11-11T23:00:00Z,subledger1,appeasement
loyaltyProgramId required | integer Example: 8 Identifier of the loyalty program. You can get the ID with the List loyalty programs endpoint. |
notificationsEnabled | boolean Example: notificationsEnabled=true Indicates whether the points import triggers notifications about its effects. For example, a notification is sent if the import upgrades a customer's tier or offsets their negative points balance. This parameter is optional and defaults to |
upFile | string <csv> The file containing the data that is being imported. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "userId": 388,
- "entity": "AttributeAllowedList",
- "amount": 10
}
Upload a CSV file containing existing customers to be assigned to existing tiers. Send the file as multipart data.
Important: This endpoint only works with loyalty programs with advanced tiers (with expiration and downgrade policy) feature enabled.
The CSV file should contain the following columns:
subledgerid
(optional): The ID of the subledger. If this field is empty, the main ledger will be used.customerprofileid
: The integration ID of the customer profile to whom the tier should be assigned.tiername
: The name of an existing tier to assign to the customer.expirydate
: The expiration date of the tier when the tier is reevaluated. It should be a future date.About customer assignment to a tier:
Note: We recommend not using this endpoint to update the tier of a customer. To update a customer's tier, you can add or deduct their loyalty points.
You can use the time zone of your choice. It is converted to UTC internally by Talon.One.
Note: We recommend limiting your file size to 500MB.
Example:
subledgerid,customerprofileid,tiername,expirydate
SUB1,alexa,Gold,2024-03-21T07:32:14Z
,george,Silver,2025-04-16T21:12:37Z
SUB2,avocado,Bronze,2026-05-03T11:47:01Z
loyaltyProgramId required | integer Example: 8 Identifier of the loyalty program. You can get the ID with the List loyalty programs endpoint. |
upFile | string <csv> The file containing the data that is being imported. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "userId": 388,
- "entity": "AttributeAllowedList",
- "amount": 10
}
Get the loyalty ledger for this profile integration ID.
To get the integrationId
of the profile from a sessionId
, use the
Update customer session endpoint.
Important: To get loyalty transaction logs for a given Integration ID in a loyalty program, we recommend using the Integration API's Get customer's loyalty logs.
loyaltyProgramId required | string Example: 45 The identifier for the loyalty program. |
integrationId required | string Example: customer1 The integration identifier for this customer profile. Must be:
Once set, you cannot update this identifier. |
{- "ledger": {
- "total": 0,
- "totalActivePoints": 0,
- "totalPendingPoints": 0,
- "totalSpentPoints": 0,
- "totalExpiredPoints": 0,
- "totalNegativePoints": 0,
- "transactions": [
- {
- "created": "2021-07-20T22:00:00Z",
- "programID": 5,
- "customerProfileID": "URNGV8294NV",
- "cardID": 241,
- "customerSessionID": "t2gy5s-47274",
- "eventID": 5,
- "type": "addition",
- "amount": 100,
- "startDate": "2021-07-20T22:00:00Z",
- "expiryDate": "2022-07-20T22:00:00Z",
- "name": "Add points on purchase",
- "subLedgerID": "mysubledger",
- "userID": 499,
- "archived": false,
- "flags": {
- "createsNegativeBalance": true
}
}
], - "expiringPoints": [
- {
- "created": "2021-07-20T22:00:00Z",
- "programID": 5,
- "customerProfileID": "URNGV8294NV",
- "cardID": 241,
- "customerSessionID": "t2gy5s-47274",
- "eventID": 5,
- "type": "addition",
- "amount": 100,
- "startDate": "2021-07-20T22:00:00Z",
- "expiryDate": "2022-07-20T22:00:00Z",
- "name": "Add points on purchase",
- "subLedgerID": "mysubledger",
- "userID": 499,
- "archived": false,
- "flags": {
- "createsNegativeBalance": true
}
}
], - "activePoints": [
- {
- "created": "2021-07-20T22:00:00Z",
- "programID": 5,
- "customerProfileID": "URNGV8294NV",
- "cardID": 241,
- "customerSessionID": "t2gy5s-47274",
- "eventID": 5,
- "type": "addition",
- "amount": 100,
- "startDate": "2021-07-20T22:00:00Z",
- "expiryDate": "2022-07-20T22:00:00Z",
- "name": "Add points on purchase",
- "subLedgerID": "mysubledger",
- "userID": 499,
- "archived": false,
- "flags": {
- "createsNegativeBalance": true
}
}
], - "pendingPoints": [
- {
- "created": "2021-07-20T22:00:00Z",
- "programID": 5,
- "customerProfileID": "URNGV8294NV",
- "cardID": 241,
- "customerSessionID": "t2gy5s-47274",
- "eventID": 5,
- "type": "addition",
- "amount": 100,
- "startDate": "2021-07-20T22:00:00Z",
- "expiryDate": "2022-07-20T22:00:00Z",
- "name": "Add points on purchase",
- "subLedgerID": "mysubledger",
- "userID": 499,
- "archived": false,
- "flags": {
- "createsNegativeBalance": true
}
}
], - "expiredPoints": [
- {
- "created": "2021-07-20T22:00:00Z",
- "programID": 5,
- "customerProfileID": "URNGV8294NV",
- "cardID": 241,
- "customerSessionID": "t2gy5s-47274",
- "eventID": 5,
- "type": "addition",
- "amount": 100,
- "startDate": "2021-07-20T22:00:00Z",
- "expiryDate": "2022-07-20T22:00:00Z",
- "name": "Add points on purchase",
- "subLedgerID": "mysubledger",
- "userID": 499,
- "archived": false,
- "flags": {
- "createsNegativeBalance": true
}
}
], - "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}
}, - "subLedgers": {
- "mysubledger": {
- "total": 0,
- "totalActivePoints": 286,
- "totalPendingPoints": 50,
- "totalSpentPoints": 150,
- "totalExpiredPoints": 25,
- "totalNegativePoints": 0
}
}
}
Add points in the specified loyalty program for the given customer.
To get the integrationId
of the profile from a sessionId
, use the
Update customer session endpoint.
loyaltyProgramId required | string Example: 45 The identifier for the loyalty program. |
integrationId required | string Example: customer1 The integration identifier for this customer profile. Must be:
Once set, you cannot update this identifier. |
body
points required | number ( 0 .. 999999999999.99 ] Amount of loyalty points. |
name | string Name / reason for the point addition. |
validityDuration | string The time format is either:
Examples: Available units:
You can round certain units up or down:
If passed, |
validUntil | string <date-time> Date and time when points should expire. The value should be provided in RFC 3339 format.
If passed, |
pendingDuration | string The amount of time before the points are considered valid. The time format is either:
Examples: Available units:
You can round certain units up or down:
|
pendingUntil | string <date-time> Date and time after the points are considered valid. The value should be provided in RFC 3339 format.
If passed, |
subledgerId | string ID of the subledger the points are added to. If there is no existing subledger with this ID, the subledger is created automatically. |
applicationId | integer ID of the Application that is connected to the loyalty program. It is displayed in your Talon.One deployment URL. |
{- "points": 300,
- "name": "Compensation",
- "validityDuration": "5D",
- "validUntil": "2021-07-20T22:00:00Z",
- "pendingDuration": "12h",
- "pendingUntil": "2021-07-20T22:00:00Z",
- "subledgerId": "sub-123",
- "applicationId": 322
}
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
Deduct points from the specified loyalty program and specified customer profile.
Important:
To get the integrationId
of the profile from a sessionId
, use the
Update customer session endpoint.
loyaltyProgramId required | string Example: 45 The identifier for the loyalty program. |
integrationId required | string Example: customer1 The integration identifier for this customer profile. Must be:
Once set, you cannot update this identifier. |
body
points required | number ( 0 .. 999999999999.99 ] Amount of loyalty points. |
name | string Name / reason for the point deduction. |
subledgerId | string ID of the subledger the points are deducted from. |
applicationId | integer ID of the Application that is connected to the loyalty program. |
{- "points": 300,
- "name": "Penalty",
- "subledgerId": "sub-123",
- "applicationId": 322
}
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
Download a CSV file containing a customer's transaction logs in the loyalty program.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
The generated file can contain the following columns:
customerprofileid
: The ID of the profile.customersessionid
: The ID of the customer session.rulesetid
: The ID of the rule set.rulename
: The name of the rule.programid
: The ID of the loyalty program.type
: The transaction type, such as addition
or subtraction
.name
: The reason for the transaction.subledgerid
: The ID of the subledger, when applicable.startdate
: The start date of the program.expirydate
: The expiration date of the program.id
: The ID of the transaction.created
: The timestamp of the creation of the loyalty program.amount
: The number of points in that transaction.archived
: Whether the session related to the transaction is archived.campaignid
: The ID of the campaign.flags
: The flags of the transaction, when applicable. The createsNegativeBalance
flag indicates whether the transaction results in a negative balance.loyaltyProgramId required | string Example: 45 The identifier for the loyalty program. |
integrationId required | string Example: customer1 The integration identifier for this customer profile. Must be:
Once set, you cannot update this identifier. |
rangeStart required | string <date-time> Example: rangeStart=2024-05-29T15:04:05+07:00 Only return results from after this timestamp. Note:
|
rangeEnd required | string <date-time> Example: rangeEnd=2024-05-29T15:04:05+07:00 Only return results from before this timestamp. Note:
|
dateFormat | string Enum: "excel" "ISO8601" Example: dateFormat=excel Determines the format of dates in the export document. |
customerprofileid,customersessionid,rulesetid,rulename,programid,type,name,subledgerid,startdate,expirydate,id,created,amount,archived,campaignid,flags 8NHOS78H,06b0fafb-ccbf-42c7-b44b-d858e8b525022,1691,test,37,subtraction,10% of current total,,immediate,unlimited,60803,2022-11-29 16:16:10,100.00,false,5, EB780RDN,06b0fafb-ccbf-42c7-b44b-d858e8b525022,1691,test,37,addition,Reimbursed loyalty points,,immediate,unlimited,60804,2022-11-29 16:16:23,100.00,false,5,createsNegativeBalance
Download a CSV file containing the tier information for customers of the specified loyalty program.
The generated file contains the following columns:
programid
: The identifier of the loyalty program. It is displayed in your Talon.One deployment URL.subledgerid
: The ID of the subledger associated with the loyalty program. This column is empty if the loyalty program has no subledger. In this case, refer to the export file name to get the ID of the loyalty program.customerprofileid
: The ID used to integrate customer profiles with the loyalty program.tiername
: The name of the tier.startdate
: The tier start date in RFC3339.expirydate
: The tier expiry date in RFC3339.You can filter the results by providing the following optional input parameters:
subledgerIds
(optional): Filter results by an array of subledger IDs. If no value is provided, all subledger data for the specified loyalty program will be exported.tierNames
(optional): Filter results by an array of tier names. If no value is provided, all tier data for the specified loyalty program will be exported.loyaltyProgramId required | string Example: 45 The identifier for the loyalty program. |
subledgerIds | Array of strings Example: subledgerIds=subledger1,subledger2 An array of subledgers IDs to filter the export by. |
tierNames | Array of strings Example: tierNames=tier1,tier2 An array of tier names to filter the export by. |
programid,subledgerid,customerprofileid,tiername,startdate,expirydate 1,SUB1,Dinesh,Golden,2023-08-02T15:04:05Z07:00,2024-08-02T15:04:05Z07:00 1,SUB2,Gilfoyle,Silver,2023-03-21T03:45:12Z05:00,2026-03-21T03:45:12Z05:00
⚠️ Deprecation notice: Support for requests to this endpoint will end soon. To retrieve statistics for a loyalty program, use the Get statistics for loyalty dashboard endpoint.
Retrieve the statistics of the specified loyalty program, such as the total active points, pending points, spent points, and expired points.
loyaltyProgramId required | integer Example: 8 Identifier of the loyalty program. You can get the ID with the List loyalty programs endpoint. |
{- "date": "2019-08-24T14:15:22Z",
- "totalActivePoints": 9756,
- "totalPendingPoints": 548,
- "totalSpentPoints": 25668,
- "totalExpiredPoints": 1156,
- "totalMembers": 2582,
- "newMembers": 3,
- "spentPoints": {
- "createdManually": 125,
- "createdViaRuleEngine": 9631
}, - "earnedPoints": {
- "createdManually": 125,
- "createdViaRuleEngine": 9631
}
}
Download a CSV file containing the balance of each customer in the loyalty program.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
The generated file can contain the following columns:
loyaltyProgramID
: The ID of the loyalty program.loyaltySubledger
: The name of the subdleger, when applicatble.profileIntegrationID
: The integration ID of the customer profile.currentBalance
: The current point balance.pendingBalance
: The number of pending points.expiredBalance
: The number of expired points.spentBalance
: The number of spent points.currentTier
: The tier that the customer is in at the time of the export.loyaltyProgramId required | string Example: 45 The identifier for the loyalty program. |
endDate | string <date-time> Example: endDate=2024-05-29T15:04:05+07:00 Used to return expired, active, and pending loyalty balances before this timestamp. You can enter any past, present, or future timestamp value. Note:
|
loyaltyProgramID,loyaltySubledger,profileIntegrationID,currentBalance,pendingBalance,expiredBalance,spentBalance,currentTier 40,,8786NTHSAO8,10.00,0.00,0.00,0.00,First 40,,2735HATHOH8,20.00,0.00,0.00,0.00,First
⚠️ Deprecation notice: Support for requests to this endpoint will end soon. To export customer loyalty balances to CSV, use the Export customer loyalty balances to CSV endpoint.
Download a CSV file containing the balance of each customer in the loyalty program.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
loyaltyProgramId required | string Example: 45 The identifier for the loyalty program. |
endDate | string <date-time> Example: endDate=2024-05-29T15:04:05+07:00 Used to return expired, active, and pending loyalty balances before this timestamp. You can enter any past, present, or future timestamp value. Note:
|
Retrieve loyalty program transaction logs in a given loyalty program with filtering options applied. Manual and imported transactions are also included. Note: If no filters are applied, the last 50 loyalty transactions for the given loyalty program are returned.
Important: To get loyalty transaction logs for a given Integration ID in a loyalty program, we recommend using the Integration API's Get customer's loyalty logs.
loyaltyProgramId required | integer Example: 8 Identifier of the loyalty program. You can get the ID with the List loyalty programs endpoint. |
loyaltyTransactionType | string Enum: "manual" "session" "import" Example: loyaltyTransactionType=manual Filter results by loyalty transaction type:
|
subledgerId | string Example: subledgerId=subledger1 The ID of the subledger by which we filter the data. |
startDate | string <date-time> Example: startDate=2024-05-29T15:04:05+07:00 Date and time from which results are returned. Results are filtered by transaction creation date. Note:
|
endDate | string <date-time> Example: endDate=2024-05-29T15:04:05+07:00 Date and time by which results are returned. Results are filtered by transaction creation date. Note:
|
pageSize | integer [ 1 .. 50 ] Default: 50 Example: pageSize=50 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
{- "hasMore": true,
- "data": [
- {
- "id": 123,
- "programId": 324,
- "campaignId": 324,
- "created": "2022-01-02T15:04:05Z07:00",
- "type": "addition",
- "amount": 10.25,
- "name": "Reward 50 points for each $500 purchase",
- "startDate": "2022-01-02T15:04:05Z07:00",
- "expiryDate": "2022-01-02T15:04:05Z07:00",
- "customerProfileId": "kda0fajs0-fad9f-fd9dfsa9-fd9dasjf9",
- "cardIdentifier": "summer-loyalty-card-0543",
- "subledgerId": "sub-123",
- "customerSessionId": "05c2da0d-48fa-4aa1-b629-898f58f1584d",
- "importId": 4,
- "userId": 5,
- "userEmail": "john.doe@example.com",
- "rulesetId": 11,
- "ruleName": "10 points for every $100 spent",
- "flags": {
- "createsNegativeBalance": true
}
}
]
}
Represents loyalty cards.
Loyalty cards allow your customers to collect and spend loyalty points within a card-based loyalty program.
Upload a CSV file containing the loyalty cards that you want to use in your card-based loyalty program. Send the file as multipart data.
It contains the following columns for each card:
identifier
(required): The alphanumeric identifier of the loyalty card.state
(required): The state of the loyalty card. It can be active
or inactive
.customerprofileids
(optional): An array of strings representing the identifiers of the customer profiles linked to the loyalty card. The identifiers should be separated with a semicolon (;).Note: We recommend limiting your file size to 500MB.
Example:
identifier,state,customerprofileids
123-456-789AT,active,Alexa001;UserA
loyaltyProgramId required | integer Example: 33 Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint. |
upFile | string <csv> The file containing the data that is being imported. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "userId": 388,
- "entity": "AttributeAllowedList",
- "amount": 10
}
Create a batch of loyalty cards in a specified card-based loyalty program.
Customers can use loyalty cards to collect and spend loyalty points.
Important:
400
status code.loyaltyProgramId required | integer Example: 33 Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint. |
body
numberOfCards required | integer Number of loyalty cards in the batch. | ||||
batchId | string [ 4 .. 20 ] characters ^[A-Za-z0-9_-]*$ ID of the loyalty card batch. | ||||
status | string Default: "active" Enum: "active" "inactive" Status of the loyalty cards in the batch. | ||||
object | |||||
|
{- "numberOfCards": 5000,
- "batchId": "hwernpjz",
- "status": "active",
- "cardCodeSettings": {
- "validCharacters": [
- "A",
- "B",
- "C",
- "D",
- "E",
- "F",
- "G",
- "H",
- "I",
- "J",
- "K",
- "L",
- "M",
- "N",
- "O",
- "P",
- "Q",
- "R",
- "S",
- "T",
- "U",
- "V",
- "W",
- "X",
- "Y",
- "Z",
- "0",
- "1",
- "2",
- "3",
- "4",
- "5",
- "6",
- "7",
- "8",
- "9"
], - "couponPattern": "SUMMER-####-####"
}
}
{- "numberOfCardsGenerated": 5000,
- "batchId": "hwernpjz"
}
Download a CSV file containing the balances of all cards in the loyalty program.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
The CSV file contains the following columns:
loyaltyProgramID
: The ID of the loyalty program.loyaltySubledger
: The name of the subdleger, when applicatble.cardIdentifier
: The alphanumeric identifier of the loyalty card.cardState
:The state of the loyalty card. It can be active
or inactive
.currentBalance
: The current point balance.pendingBalance
: The number of pending points.expiredBalance
: The number of expired points.spentBalance
: The number of spent points.loyaltyProgramId required | integer Example: 33 Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint. |
endDate | string <date-time> Example: endDate=2024-05-29T15:04:05+07:00 Used to return expired, active, and pending loyalty balances before this timestamp. You can enter any past, present, or future timestamp value. Note:
|
loyaltyProgramID,loyaltySubledger,cardIdentifier,cardState,currentBalance,pendingBalance,expiredBalance,spentBalance 40,,111,active,10,0,0,0,5
For the given card-based loyalty program, list the loyalty cards that match your filter criteria.
loyaltyProgramId required | integer Example: 33 Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
identifier | string >= 4 characters Example: identifier=summer-loyalty-card-054 The card code by which to filter loyalty cards in the response. |
profileId | integer >= 1 Example: profileId=44 Filter results by customer profile ID. |
batchId | string Example: batchId=UY83CTT4 Filter results by loyalty card batch ID. |
{- "hasMore": true,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "programID": 125,
- "programName": "Loyalty_program",
- "programTitle": "Loyalty program",
- "status": "active",
- "blockReason": "Current card lost. Customer needs a new card.",
- "identifier": "summer-loyalty-card-0543",
- "usersPerCardLimit": 111,
- "profiles": [
- {
- "integrationId": "R195412",
- "timestamp": "2021-09-12T10:12:42Z"
}
], - "ledger": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "negativeBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "tentativeNegativeBalance": 100,
- "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}, - "pointsToNextTier": 20
}, - "subledgers": {
- "property1": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "negativeBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "tentativeNegativeBalance": 100,
- "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}, - "pointsToNextTier": 20
}, - "property2": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "negativeBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "tentativeNegativeBalance": 100,
- "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}, - "pointsToNextTier": 20
}
}, - "modified": "2021-09-12T10:12:42Z",
- "oldCardIdentifier": "summer-loyalty-card-0543",
- "newCardIdentifier": "summer-loyalty-card-0543",
- "batchId": "wdefpov"
}
]
}
Download a CSV file containing the loyalty cards from a specified loyalty program.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
The CSV file contains the following columns:
identifier
: The unique identifier of the loyalty card.created
: The date and time the loyalty card was created.status
: The status of the loyalty card.userpercardlimit
: The maximum number of customer profiles that can be linked to the card.customerprofileids
: Integration IDs of the customer profiles linked to the card.blockreason
: The reason for transferring and blocking the loyalty card.generated
: An indicator of whether the loyalty card was generated.batchid
: The ID of the batch the loyalty card is in.loyaltyProgramId required | integer Example: 33 Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint. |
batchId | string Example: batchId=UY83CTT4 Filter results by loyalty card batch ID. |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Only return loyalty cards created before this timestamp. Note:
|
createdAfter | string <date-time> Example: createdAfter=2024-04-15T15:04:05+07:00 Only return loyalty cards created after this timestamp. Note:
|
dateFormat | string Enum: "excel" "ISO8601" Example: dateFormat=excel Determines the format of dates in the export document. |
identifier,created,status,userpercardlimit,customerprofileids,blockreason,generated,batchid CARD-1234,2020-06-10T09:05:27.993483Z,active,3,['profile1'],card limit reached,false,gwedcbfp
Delete the given loyalty card.
loyaltyProgramId required | integer Example: 33 Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint. |
loyaltyCardId required | string <= 108 characters Example: summer-loyalty-card-0543 Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint. |
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
Update the status of the given loyalty card. A card can be active or inactive.
loyaltyProgramId required | integer Example: 33 Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint. |
loyaltyCardId required | string <= 108 characters Example: summer-loyalty-card-0543 Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint. |
body
status required | string Status of the loyalty card. Can be |
blockReason | string Reason for transferring and blocking the loyalty card. |
{- "status": "active",
- "blockReason": "Current card lost. Customer needs a new card."
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "programID": 125,
- "programName": "Loyalty_program",
- "programTitle": "Loyalty program",
- "status": "active",
- "blockReason": "Current card lost. Customer needs a new card.",
- "identifier": "summer-loyalty-card-0543",
- "usersPerCardLimit": 111,
- "profiles": [
- {
- "integrationId": "R195412",
- "timestamp": "2021-09-12T10:12:42Z"
}
], - "ledger": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "negativeBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "tentativeNegativeBalance": 100,
- "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}, - "pointsToNextTier": 20
}, - "subledgers": {
- "property1": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "negativeBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "tentativeNegativeBalance": 100,
- "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}, - "pointsToNextTier": 20
}, - "property2": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "negativeBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "tentativeNegativeBalance": 100,
- "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}, - "pointsToNextTier": 20
}
}, - "modified": "2021-09-12T10:12:42Z",
- "oldCardIdentifier": "summer-loyalty-card-0543",
- "newCardIdentifier": "summer-loyalty-card-0543",
- "batchId": "wdefpov"
}
Get the given loyalty card.
loyaltyProgramId required | integer Example: 33 Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint. |
loyaltyCardId required | string <= 108 characters Example: summer-loyalty-card-0543 Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "programID": 125,
- "programName": "Loyalty_program",
- "programTitle": "Loyalty program",
- "status": "active",
- "blockReason": "Current card lost. Customer needs a new card.",
- "identifier": "summer-loyalty-card-0543",
- "usersPerCardLimit": 111,
- "profiles": [
- {
- "integrationId": "R195412",
- "timestamp": "2021-09-12T10:12:42Z"
}
], - "ledger": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "negativeBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "tentativeNegativeBalance": 100,
- "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}, - "pointsToNextTier": 20
}, - "subledgers": {
- "property1": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "negativeBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "tentativeNegativeBalance": 100,
- "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}, - "pointsToNextTier": 20
}, - "property2": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "negativeBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "tentativeNegativeBalance": 100,
- "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}, - "pointsToNextTier": 20
}
}, - "modified": "2021-09-12T10:12:42Z",
- "oldCardIdentifier": "summer-loyalty-card-0543",
- "newCardIdentifier": "summer-loyalty-card-0543",
- "batchId": "wdefpov"
}
Add points to the given loyalty card in the specified card-based loyalty program.
loyaltyProgramId required | integer Example: 33 Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint. |
loyaltyCardId required | string <= 108 characters Example: summer-loyalty-card-0543 Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint. |
body
points required | number ( 0 .. 999999999999.99 ] Amount of loyalty points. |
name | string Name / reason for the point addition. |
validityDuration | string The time format is either:
Examples: Available units:
You can round certain units up or down:
If passed, |
validUntil | string <date-time> Date and time when points should expire. The value should be provided in RFC 3339 format.
If passed, |
pendingDuration | string The amount of time before the points are considered valid. The time format is either:
Examples: Available units:
You can round certain units up or down:
|
pendingUntil | string <date-time> Date and time after the points are considered valid. The value should be provided in RFC 3339 format.
If passed, |
subledgerId | string ID of the subledger the points are added to. If there is no existing subledger with this ID, the subledger is created automatically. |
applicationId | integer ID of the Application that is connected to the loyalty program. It is displayed in your Talon.One deployment URL. |
{- "points": 300,
- "name": "Compensation",
- "validityDuration": "5D",
- "validUntil": "2021-07-20T22:00:00Z",
- "pendingDuration": "12h",
- "pendingUntil": "2021-07-20T22:00:00Z",
- "subledgerId": "sub-123",
- "applicationId": 322
}
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
Deduct points from the given loyalty card in the specified card-based loyalty program.
loyaltyProgramId required | integer Example: 33 Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint. |
loyaltyCardId required | string <= 108 characters Example: summer-loyalty-card-0543 Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint. |
body
points required | number ( 0 .. 999999999999.99 ] Amount of loyalty points. |
name | string Name / reason for the point deduction. |
subledgerId | string ID of the subledger the points are deducted from. |
applicationId | integer ID of the Application that is connected to the loyalty program. |
{- "points": 300,
- "name": "Penalty",
- "subledgerId": "sub-123",
- "applicationId": 322
}
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
Download a CSV file containing a loyalty card ledger log of the loyalty program.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
loyaltyProgramId required | integer Example: 33 Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint. |
loyaltyCardId required | string <= 108 characters Example: summer-loyalty-card-0543 Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint. |
rangeStart required | string <date-time> Example: rangeStart=2024-05-29T15:04:05+07:00 Only return results from after this timestamp. Note:
|
rangeEnd required | string <date-time> Example: rangeEnd=2024-05-29T15:04:05+07:00 Only return results from before this timestamp. Note:
|
dateFormat | string Enum: "excel" "ISO8601" Example: dateFormat=excel Determines the format of dates in the export document. |
Retrieve the transaction logs for the given loyalty card within the specified card-based loyalty program with filtering options applied. If no filtering options are applied, the last 50 loyalty transactions for the given loyalty card are returned.
loyaltyProgramId required | integer Example: 33 Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint. |
loyaltyCardId required | string <= 108 characters Example: summer-loyalty-card-0543 Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint. |
startDate | string <date-time> Example: startDate=2024-05-29T15:04:05+07:00 Date and time from which results are returned. Results are filtered by transaction creation date. Note:
|
endDate | string <date-time> Example: endDate=2024-05-29T15:04:05+07:00 Date and time by which results are returned. Results are filtered by transaction creation date. Note:
|
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
subledgerId | string Example: subledgerId=subledger1 The ID of the subledger by which we filter the data. |
{- "hasMore": true,
- "data": [
- {
- "created": "2022-01-02T15:04:05Z07:00",
- "programId": 324,
- "cardIdentifier": "summer-loyalty-card-0543",
- "applicationId": 322,
- "sessionId": 233,
- "customerSessionId": "05c2da0d-48fa-4aa1-b629-898f58f1584d",
- "type": "addition",
- "name": "Reward 10% points of a purchase's current total",
- "startDate": "2022-01-02T15:04:05Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "subledgerId": "sub-123",
- "amount": 10.25,
- "id": 123
}
]
}
Transfer loyalty card data, such as linked customers, loyalty balances and transactions, from a given loyalty card to a new, automatically created loyalty card.
Important:
loyaltyProgramId required | integer Example: 33 Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the List loyalty programs endpoint. |
loyaltyCardId required | string <= 108 characters Example: summer-loyalty-card-0543 Identifier of the loyalty card. You can get the identifier with the List loyalty cards endpoint. |
body
newCardIdentifier required | string <= 108 characters ^[A-Za-z0-9_-]*$ The alphanumeric identifier of the loyalty card. |
blockReason | string Reason for transferring and blocking the loyalty card. |
{- "newCardIdentifier": "summer-loyalty-card-0543",
- "blockReason": "Current card lost. Customer needs a new card."
}
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
A referral is a code shared between a customer and a prospect.
A referral is defined by:
See the docs.
Delete the specified referral.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
referralId required | string Example: 2154 The ID of the referral code. |
Update the specified referral.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
referralId required | string Example: 2154 The ID of the referral code. |
body
friendProfileIntegrationId | string <= 1000 characters An optional Integration ID of the Friend's Profile. |
startDate | string <date-time> Timestamp at which point the referral code becomes valid. |
expiryDate | string <date-time> Expiration date of the referral code. Referral never expires if this is omitted. |
usageLimit | integer [ 0 .. 999999 ] The number of times a referral code can be used. This can be set to 0 for no limit, but any campaign usage limits will still apply. |
attributes | object Arbitrary properties associated with this item. |
{- "friendProfileIntegrationId": "BZGGC2454PA",
- "startDate": "2020-11-10T23:00:00Z",
- "expiryDate": "2021-11-10T23:00:00Z",
- "usageLimit": 1,
- "attributes": { }
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "startDate": "2020-11-10T23:00:00Z",
- "expiryDate": "2021-11-10T23:00:00Z",
- "usageLimit": 1,
- "campaignId": 78,
- "advocateProfileIntegrationId": "URNGV8294NV",
- "friendProfileIntegrationId": "BZGGC2454PA",
- "attributes": {
- "channel": "web"
}, - "importId": 4,
- "code": "27G47Y54VH9L",
- "usageCounter": 1,
- "batchId": "tqyrgahe"
}
List all referrals of the specified campaign.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
code | string Example: code=JVM8JH8F Filter results performing case-insensitive matching against the referral code. Both the code and the query are folded to remove all non-alpha-numeric characters. |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the referral creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
createdAfter | string <date-time> Example: createdAfter=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the referral creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
valid | string Enum: "expired" "validNow" "validFuture" Example: valid=validNow Either "expired", "validNow", or "validFuture". The first option matches referrals in which the expiration date is set and in the past. The second matches referrals in which start date is null or in the past and expiration date is null or in the future, the third matches referrals in which start date is set and in the future. |
usable | string Enum: "true" "false" Example: usable=false Either "true" or "false". If "true", only referrals where |
advocate | string Example: advocate=customer1 Filter results by match with a profile ID specified in the referral's AdvocateProfileIntegrationId field. |
{- "hasMore": true,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "startDate": "2020-11-10T23:00:00Z",
- "expiryDate": "2021-11-10T23:00:00Z",
- "usageLimit": 1,
- "campaignId": 78,
- "advocateProfileIntegrationId": "URNGV8294NV",
- "friendProfileIntegrationId": "BZGGC2454PA",
- "attributes": {
- "channel": "web"
}, - "importId": 4,
- "code": "27G47Y54VH9L",
- "usageCounter": 1,
- "batchId": "tqyrgahe"
}
]
}
List the friends referred by the specified customer profile in this Application.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
integrationId required | string Example: advocate1 The Integration ID of the Advocate's Profile. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
withTotalResultSize | boolean When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.
|
{- "hasMore": true,
- "totalResultSize": 1,
- "data": [
- {
- "applicationId": 322,
- "sessionId": "string",
- "advocateIntegrationId": "string",
- "friendIntegrationId": "string",
- "code": "string",
- "created": "2019-08-24T14:15:22Z"
}
]
}
Download a CSV file containing the referrals that match the given parameters.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
The CSV file contains the following columns:
code
: The referral code.advocateprofileintegrationid
: The profile ID of the advocate.startdate
: The start date in RFC3339 of the code redemption period.expirydate
: The end date in RFC3339 of the code redemption period.limitval
: The maximum number of redemptions of this code. Defaults to 1
when left blank.attributes
: A json object describing custom referral attribute names and their values.applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId | number Example: campaignId=49 Filter results by campaign ID. |
createdBefore | string <date-time> Example: createdBefore=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the referral creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
createdAfter | string <date-time> Example: createdAfter=2024-05-29T15:04:05+07:00 Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the referral creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally. |
valid | string Enum: "expired" "validNow" "validFuture" Example: valid=validNow
|
usable | string Enum: "true" "false" Example: usable=true
|
batchId | string Example: batchId=nfinccze Filter results by batches of referrals |
dateFormat | string Enum: "excel" "ISO8601" Example: dateFormat=excel Determines the format of dates in the export document. |
id,created,campaignid,advocateprofileintegrationid,friendprofileintegrationid,startdate,expirydate,code,importid,attributes,batchid,counter,limitval 687,2021-09-10 09:21:06,3882,UGAV4628K,,,,3LFC-4BPC,,"{}",pimcxobg,0,9999
Upload a CSV file containing the referrals that should be created. The file should be sent as multipart data.
The CSV file contains the following columns:
code
(required): The referral code.
advocateprofileintegrationid
(required): The profile ID of the advocate.
startdate
: The start date in RFC3339 of the code redemption period.
expirydate
: The end date in RFC3339 of the code redemption period.
limitval
: The maximum number of redemptions of this code. Defaults to 1
when left blank.
attributes
: A JSON object describing custom referral attribute names and their values, enclosed with double quotation marks.
For example, if you created a custom attribute
called category
associated with the referral entity, the object in the CSV file, when opened in a text editor, must be: "{"category": "10_off"}"
.
You can use the time zone of your choice. It is converted to UTC internally by Talon.One.
Important: When you import a CSV file with referrals, a customer profile
is not automatically created for each advocateprofileintegrationid
column value. Use the Update customer profile
endpoint or the Update multiple customer profiles
endpoint to create the customer profiles.
Note: We recommend limiting your file size to 500MB.
Example:
code,startdate,expirydate,advocateprofileintegrationid,limitval,attributes
REFERRAL_CODE1,2020-11-10T23:00:00Z,2021-11-11T23:00:00Z,integid_4,1,"{""my_attribute"": ""10_off""}"
REFERRAL_CODE2,2020-11-10T23:00:00Z,2021-11-11T23:00:00Z,integid1,1,"{""my_attribute"": ""20_off""}"
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
upFile | string <csv> The file containing the data that is being imported. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "userId": 388,
- "entity": "AttributeAllowedList",
- "amount": 10
}
Represents a set of permissions assigned to a user.
See the docs.
List all roles.
{- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "modified": "2021-09-12T10:12:42Z",
- "accountId": 3886,
- "name": "Campaign and campaign access group manager",
- "description": "Allows you to create and edit campaigns for specific Applications, delete specific campaign access groups, and view loyalty programs.",
- "permissions": {
- "permissionSets": [
- {
- "name": "Application permission set",
- "logicalOperations": [
- "getApplicationOperations",
- "editApplicationOperations"
]
}, - {
- "name": "Campaign manager permission set",
- "logicalOperations": [
- "getCampaignOperations",
- "createCampaignOperations",
- "updateCampaignOperations"
]
}, - {
- "name": "Campaign read-only permission set",
- "logicalOperations": [
- "getCampaignOperations"
]
}, - {
- "name": "Loyalty program read-only permission set",
- "logicalOperations": [
- "getLoyaltyProgramOperations"
]
}, - {
- "name": "Campaign access group manager permission set",
- "logicalOperations": [
- "getCampaignAccessGroupOperations",
- "updateCampaignAccessGroupOperations",
- "deleteCampaignAccessGroupOperations"
]
}
], - "roles": {
- "applications": {
- "1": {
- "application": "Application permission set"
}, - "3": {
- "campaign": "Campaign manager permission set"
}, - "4": {
- "draftCampaign": "Campaign read-only permission set"
}, - "5": {
- "tools": "Tools permission set"
}
}, - "loyaltyPrograms": {
- "10": "Loyalty program manager permission set"
}, - "campaignAccessGroups": {
- "5": "Campaign access group manager permission set"
}
}
}, - "members": [
- 10,
- 12
]
}
]
}
Get the details of a specific role. To see all the roles, use the List roles endpoint.
roleId required |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "modified": "2021-09-12T10:12:42Z",
- "accountId": 3886,
- "name": "Campaign and campaign access group manager",
- "description": "Allows you to create and edit campaigns for specific Applications, delete specific campaign access groups, and view loyalty programs.",
- "permissions": {
- "permissionSets": [
- {
- "name": "Application permission set",
- "logicalOperations": [
- "getApplicationOperations",
- "editApplicationOperations"
]
}, - {
- "name": "Campaign manager permission set",
- "logicalOperations": [
- "getCampaignOperations",
- "createCampaignOperations",
- "updateCampaignOperations"
]
}, - {
- "name": "Campaign read-only permission set",
- "logicalOperations": [
- "getCampaignOperations"
]
}, - {
- "name": "Loyalty program read-only permission set",
- "logicalOperations": [
- "getLoyaltyProgramOperations"
]
}, - {
- "name": "Campaign access group manager permission set",
- "logicalOperations": [
- "getCampaignAccessGroupOperations",
- "updateCampaignAccessGroupOperations",
- "deleteCampaignAccessGroupOperations"
]
}
], - "roles": {
- "applications": {
- "1": {
- "application": "Application permission set"
}, - "3": {
- "campaign": "Campaign manager permission set"
}, - "4": {
- "draftCampaign": "Campaign read-only permission set"
}, - "5": {
- "tools": "Tools permission set"
}
}, - "loyaltyPrograms": {
- "10": "Loyalty program manager permission set"
}, - "campaignAccessGroups": {
- "5": "Campaign access group manager permission set"
}
}
}, - "members": [
- 10,
- 12
]
}
Update a specific role.
roleId required |
body
name | string Name of the role. | ||||||||||||||||||||||||||||||||||||||||
description | string Description of the role. | ||||||||||||||||||||||||||||||||||||||||
object The permissions that this role gives. | |||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||
members | Array of integers A list of user IDs the role is assigned to. |
{- "name": "Campaign and campaign access group manager",
- "description": "Allows you to create and edit campaigns for specific Applications, delete specific campaign access groups, and view loyalty programs.",
- "permissions": {
- "permissionSets": [
- {
- "name": "Application permission set",
- "logicalOperations": [
- "getApplicationOperations",
- "editApplicationOperations"
]
}, - {
- "name": "Campaign manager permission set",
- "logicalOperations": [
- "getCampaignOperations",
- "createCampaignOperations",
- "updateCampaignOperations"
]
}, - {
- "name": "Campaign read-only permission set",
- "logicalOperations": [
- "getCampaignOperations"
]
}, - {
- "name": "Loyalty program read-only permission set",
- "logicalOperations": [
- "getLoyaltyProgramOperations"
]
}, - {
- "name": "Campaign access group manager permission set",
- "logicalOperations": [
- "getCampaignAccessGroupOperations",
- "updateCampaignAccessGroupOperations",
- "deleteCampaignAccessGroupOperations"
]
}
], - "roles": {
- "applications": {
- "1": {
- "application": "Application permission set"
}, - "3": {
- "campaign": "Campaign manager permission set"
}, - "4": {
- "draftCampaign": "Campaign read-only permission set"
}, - "5": {
- "tools": "Tools permission set"
}
}, - "loyaltyPrograms": {
- "10": "Loyalty program manager permission set"
}, - "campaignAccessGroups": {
- "5": "Campaign access group manager permission set"
}
}
}, - "members": [
- 10,
- 12
]
}
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "modified": "2021-09-12T10:12:42Z",
- "accountId": 3886,
- "name": "Campaign and campaign access group manager",
- "description": "Allows you to create and edit campaigns for specific Applications, delete specific campaign access groups, and view loyalty programs.",
- "permissions": {
- "permissionSets": [
- {
- "name": "Application permission set",
- "logicalOperations": [
- "getApplicationOperations",
- "editApplicationOperations"
]
}, - {
- "name": "Campaign manager permission set",
- "logicalOperations": [
- "getCampaignOperations",
- "createCampaignOperations",
- "updateCampaignOperations"
]
}, - {
- "name": "Campaign read-only permission set",
- "logicalOperations": [
- "getCampaignOperations"
]
}, - {
- "name": "Loyalty program read-only permission set",
- "logicalOperations": [
- "getLoyaltyProgramOperations"
]
}, - {
- "name": "Campaign access group manager permission set",
- "logicalOperations": [
- "getCampaignAccessGroupOperations",
- "updateCampaignAccessGroupOperations",
- "deleteCampaignAccessGroupOperations"
]
}
], - "roles": {
- "applications": {
- "1": {
- "application": "Application permission set"
}, - "3": {
- "campaign": "Campaign manager permission set"
}, - "4": {
- "draftCampaign": "Campaign read-only permission set"
}, - "5": {
- "tools": "Tools permission set"
}
}, - "loyaltyPrograms": {
- "10": "Loyalty program manager permission set"
}, - "campaignAccessGroups": {
- "5": "Campaign access group manager permission set"
}
}
}, - "members": [
- 10,
- 12
]
}
Represents a session used for authentication purposes. Create one with the Create session endpoint.
Create a session to use the Management API endpoints.
Use the value of the token
property provided in the response as bearer token in other API calls.
A token is valid for 3 months. In accordance with best pratices, use your generated token for all your API requests. Do not regenerate a token for each request.
This endpoint has a rate limit of 3 to 6 requests per second per account, depending on your setup.
Granular API key
Instead of using a session, you can also use the Management API key feature in the Campaign Manager to decide which endpoints can be used with a given key.body
email required | string <email> The email address associated with the user profile. |
password required | string The password for your account. |
{- "email": "john.doe@example.com",
- "password": "admin123456"
}
{- "userId": 109,
- "token": "dy_Fa_lQ4iDAnqldJFvVEmnsN8xDTxej19l0LZDBJhQ",
- "created": "2021-07-20T22:00:00Z"
}
Represents store budgets. You can set a store budget to limit the total amount an individual store can spend in a campaign.
Create a new store budget for a given campaign.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
body
action required | string Value: "setDiscount" | ||||
required | Array of objects The set of budget limits for stores linked to the campaign. | ||||
Array
| |||||
period | string Enum: "daily" "weekly" "monthly" "yearly" |
{- "action": "setDiscount",
- "storeLimits": [
- {
- "storeId": 17,
- "limit": 1000
}
], - "period": "daily"
}
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
]
}
Return the store budget limits for a given campaign.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
action | string Value: "setDiscount" Example: action=setDiscount The action that this budget is limiting. |
period | string Enum: "overall" "daily" "weekly" "monthly" "yearly" Example: period=weekly The period to which the limit applies. Note: For budgets with no period, set this to |
{- "data": [
- {
- "store": {
- "id": 0,
- "integrationId": "string",
- "name": "string"
}, - "limit": 0,
- "action": "string",
- "period": "string"
}
]
}
Delete the store budgets for a given campaign.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
action | string Value: "setDiscount" Example: action=setDiscount The action that this budget is limiting. |
period | string Enum: "overall" "daily" "weekly" "monthly" "yearly" Example: period=weekly The period to which the limit applies. Note: For budgets with no period, set this to |
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
]
}
Fetch a summary of all store budget information for a given campaign.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
{- "data": [
- {
- "action": "redeemCoupon",
- "period": "overall",
- "storeCount": 0,
- "imported": true
}
]
}
Upload a CSV file containing store budgets for a given campaign.
Send the file as multipart data.
The CSV file must only contain the following columns:
store_integration_id
: The identifier of the store.limit
: The budget limit for the store.The import replaces the previous list of store budgets.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
action | string Value: "setDiscount" Example: action=setDiscount The action that this budget is limiting. |
period | string Enum: "overall" "daily" "weekly" "monthly" "yearly" Example: period=weekly The period to which the limit applies. Note: For budgets with no period, set this to |
upFile | string <csv> The file containing the data that is being imported. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "userId": 388,
- "entity": "AttributeAllowedList",
- "amount": 10
}
Download a CSV file containing the store budgets for a given campaign.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
The CSV file contains the following columns:
store_integration_id
: The identifier of the store.limit
: The budget limit for the store.applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
action | string Value: "setDiscount" Example: action=setDiscount The action that this budget is limiting. |
period | string Enum: "overall" "daily" "weekly" "monthly" "yearly" Example: period=weekly The period to which the limit applies. Note: For budgets with no period, set this to |
store_integration_id,limit STORE-001,10 STORE-002,20 STORE-003,30
List all stores for a specific Application.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
withTotalResultSize | boolean When this flag is set, the result includes the total size of the result, across all pages. This might decrease performance on large data sets.
|
campaignId | number Example: campaignId=49 Filter results by campaign ID. |
name | string Example: name=store1 The name of the store. |
integrationId | string Example: integrationId=storeId1 The integration ID of the store. |
query | string Example: query=name Filter results by |
{- "hasMore": true,
- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "name": "South US store",
- "description": "This is the description of the store in south US.",
- "attributes": {
- "country": "USA",
- "code": 1234
}, - "integrationId": "STORE-001",
- "applicationId": 322,
- "updated": "2021-09-23T10:12:42Z",
- "linkedCampaignIds": [
- 4,
- 6,
- 8
]
}
]
}
Create a new store in a specific Application.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
body
name required | string [ 1 .. 200 ] characters The name of the store. |
description required | string The description of the store. |
integrationId required | string <string> [ 1 .. 1000 ] characters The integration ID of the store. You choose this ID when you create a store. Note: You cannot edit the |
attributes | object The attributes of the store. |
{- "name": "South US store",
- "description": "This is the description of the store in south US.",
- "attributes": {
- "country": "USA",
- "code": 1234
}, - "integrationId": "STORE-001"
}
{- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "name": "South US store",
- "description": "This is the description of the store in south US.",
- "attributes": {
- "country": "USA",
- "code": 1234
}, - "integrationId": "STORE-001",
- "applicationId": 322,
- "updated": "2021-09-23T10:12:42Z",
- "linkedCampaignIds": [
- 4,
- 6,
- 8
]
}
Get store details for a specific store ID.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
storeId required |
{- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "name": "South US store",
- "description": "This is the description of the store in south US.",
- "attributes": {
- "country": "USA",
- "code": 1234
}, - "integrationId": "STORE-001",
- "applicationId": 322,
- "updated": "2021-09-23T10:12:42Z",
- "linkedCampaignIds": [
- 4,
- 6,
- 8
]
}
Update store details for a specific store ID.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
storeId required |
body
name required | string [ 1 .. 200 ] characters The name of the store. |
description required | string The description of the store. |
integrationId required | string <string> [ 1 .. 1000 ] characters The integration ID of the store. You choose this ID when you create a store. Note: You cannot edit the |
attributes | object The attributes of the store. |
{- "name": "South US store",
- "description": "This is the description of the store in south US.",
- "attributes": {
- "country": "USA",
- "code": 1234
}, - "integrationId": "STORE-001"
}
{- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "name": "South US store",
- "description": "This is the description of the store in south US.",
- "attributes": {
- "country": "USA",
- "code": 1234
}, - "integrationId": "STORE-001",
- "applicationId": 322,
- "updated": "2021-09-23T10:12:42Z",
- "linkedCampaignIds": [
- 4,
- 6,
- 8
]
}
Delete the specified store.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
storeId required |
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
Download a CSV file containing the stores linked to a specific campaign.
Tip: If the exported CSV file is too large to view, you can split it into multiple files.
The CSV file contains the following column:
store_integration_id
: The identifier of the store.applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
store_integration_id STORE-001 STORE-002 STORE-003
Disconnect the stores linked to a specific campaign.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
]
}
Upload a CSV file containing the stores you want to link to a specific campaign.
Send the file as multipart data.
The CSV file must only contain the following column:
store_integration_id
: The identifier of the store.The import replaces the previous list of stores linked to the campaign.
applicationId required | integer Example: 42 The ID of the Application. It is displayed in your Talon.One deployment URL. |
campaignId required | integer Example: 18 The ID of the campaign. It is displayed in your Talon.One deployment URL. |
upFile | string <csv> The file containing the data that is being imported. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "userId": 388,
- "entity": "AttributeAllowedList",
- "amount": 10
}
A way to send information from Talon.One to the URI of your choice.
See the docs.
List all webhooks.
applicationIds | string Example: applicationIds=33 Checks if the given catalog or its attributes are referenced in the specified Application ID. Note: If no Application ID is provided, we check for all connected Applications. |
sort | string Example: sort=name The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with Note: You may not be able to use all fields for sorting. This is due to performance limitations. |
pageSize | integer [ 1 .. 1000 ] Default: 1000 Example: pageSize=1000 The number of items in the response. |
skip | integer Example: skip=100 The number of items to skip when paging through large result sets. |
creationType | string Enum: "templateWebhooks" "webhooks" Example: creationType=webhooks Filter results by creation type. |
visibility | string Enum: "visible" "hidden" Example: visibility=visible Filter results by visibility. |
outgoingIntegrationsTypeId | integer Example: outgoingIntegrationsTypeId=15 Filter results by outgoing integration type ID. |
title | string Example: title=title1 Filter results performing case-insensitive matching against the webhook title. |
{- "totalResultSize": 1,
- "data": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "modified": "2021-09-12T10:12:42Z",
- "applicationIds": [
- 0
], - "title": "Send message",
- "description": "A webhook to send a coupon to the user.",
- "draft": false,
- "verb": "POST",
- "url": "www.my-company.com/my-endpoint-name",
- "headers": [
- "{\"Authorization\": \"Basic bmF2ZWVua3VtYXIU=\"}",
- "{\"Content-Type\": \"application/json\"}"
], - "payload": "{\n\t\"message\": \"${message}\"\n}",
- "params": [ ],
- "enabled": true,
- "authenticationId": 1,
- "outgoingIntegrationTemplateId": 1,
- "outgoingIntegrationTypeId": 1,
- "outgoingIntegrationTypeName": "Braze"
}
]
}
Returns a webhook by its id.
webhookId required | integer Example: 11 The ID of the webhook. You can find the ID in the Campaign Manager's URL when you display the details of the webhook in Account > Webhooks. |
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "modified": "2021-09-12T10:12:42Z",
- "applicationIds": [
- 0
], - "title": "Send message",
- "description": "A webhook to send a coupon to the user.",
- "draft": false,
- "verb": "POST",
- "url": "www.my-company.com/my-endpoint-name",
- "headers": [
- "{\"Authorization\": \"Basic bmF2ZWVua3VtYXIU=\"}",
- "{\"Content-Type\": \"application/json\"}"
], - "payload": "{\n\t\"message\": \"${message}\"\n}",
- "params": [ ],
- "enabled": true,
- "authenticationId": 1
}