Integration API
Download OpenAPI specification:Download
Use the Integration API to push data to and retrieve data from Talon.One in real time. For more background information about this API, see Integration API overview
For example, use this API to share shopping cart information as a session with Talon.One and evaluate promotion rules. You can also create custom events to track specific actions that do not fit into the session data model.
Ensure you authenticate to make requests to the API.
Are you looking for a different API?
If you need the API to:
- Interact with the Campaign Manager for backoffice operations, see the Management API reference docs.
- Integrate with Talon.One from a CEP or CDP platform, see the Third-party API reference docs.
api_key_v1
To authenticate with the Integration API, generate an API key in the Campaign Manager
and prefix it with ApiKey-v1
.
To generate an API key:
- Sign in to the Campaign Manager and open the Application of your choice, or create one.
- Click Settings > Integration API Keys.
- Click Create API Key and give it a name and an expiration date, then click Create API Key.
You can now use the API key in the HTTP header, prefixing it with ApiKey-v1
:
Authorization: ApiKey-v1 dbc644d33aa74d582bd9479c59e16f970fe13bf3
Or use it inside an SDK, for example, with the JAVA SDK:
iApi.getApiClient().setApiKeyPrefix("ApiKey-v1");
iApi.getApiClient().setApiKey("dbc644d33aa74d582bd9479c59e16f970fe13bf3");
Authorization
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.
Create audience
Create an audience. The audience can be created directly from scratch or can come from third party platforms.
Note: Audiences can also be created from scratch via the Campaign Manager. See the docs.
To create an audience from an existing audience from a technology partner:
- Set the
integration
property tomparticle
,segment
etc., depending on a third-party platform. - Set
integrationId
to the ID of this audience in a third-party platform.
To create an audience from an existing audience in another platform:
- Do not use the
integration
property. - Set
integrationId
to the ID of this audience in the 3rd-party platform.
To create an audience from scratch:
- Only set the
name
property.
Once you create your first audience, audience-specific rule conditions are enabled in the Rule Builder.
Authorizations:
Request Body schema: application/jsonrequired
body
name required | string non-empty The human-friendly display name for this audience. |
sandbox | boolean Indicates if this is a live or sandbox Application. |
description | string A description of the audience. |
integration | string The Talon.One-supported 3rd-party platform that this audience was created in. For example, Note: If you do not integrate with any of these platforms, do not use this property. |
integrationId | string [ 1 .. 1000 ] characters The ID of this audience in the third-party integration. Note: To create an audience that doesn't come from a 3rd party platform, do not use this property. |
createdIn3rdParty | boolean Determines if this audience is a 3rd party audience or not. |
lastUpdate | string <date-time> The last time that the audience memberships changed. |
Responses
Request samples
- Payload
{- "name": "Travel audience",
- "sandbox": true,
- "description": "Travel audience 18-27",
- "integration": "mparticle",
- "integrationId": "382370BKDB946",
- "createdIn3rdParty": false,
- "lastUpdate": "2022-04-26T11:02:38Z"
}
Response samples
- 201
- 400
- 401
- 409
{- "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"
}
Delete audience
Delete an audience created by a third-party integration.
Warning: This endpoint also removes any associations recorded between a customer profile and this audience.
Note: Audiences can also be deleted via the Campaign Manager. See the docs.
Authorizations:
path Parameters
audienceId required | integer Example: 10 The ID of the audience. |
Responses
Response samples
- 400
- 401
- 404
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
Update audience name
Update the name of the given audience created by a third-party integration. Sending a request to this endpoint does not trigger the Rule Engine.
To update the audience's members, use the Update customer profile endpoint.
Authorizations:
path Parameters
audienceId required | integer Example: 10 The ID of the audience. |
Request Body schema: application/jsonrequired
body
name required | string non-empty The human-friendly display name for this audience. |
Responses
Request samples
- Payload
{- "name": "Travel audience"
}
Response samples
- 200
- 401
- 404
{- "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"
}
Delete audience memberships
Remove all members from this audience.
Authorizations:
path Parameters
audienceId required | integer Example: 10 The ID of the audience. |
Responses
Response samples
- 401
- 404
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
Update multiple customer profiles' audiences
Add customer profiles to or remove them from an audience.
The endpoint supports 1000 audience actions (add
or remove
) per request.
Note: You can also do this using the Update audience effect.
Authorizations:
Request Body schema: application/jsonrequired
body
Array of objects | |||||||
Array
|
Responses
Request samples
- Payload
{- "data": [
- {
- "action": "add",
- "profileIntegrationId": "R195412",
- "audienceId": 748
}
]
}
Response samples
- 400
- 401
- 404
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
Update profile attributes for all customers in audience
Update the specified profile attributes to the provided values for all customers in the specified audience.
Authorizations:
path Parameters
audienceId required | integer Example: 10 The ID of the audience. |
Request Body schema: application/jsonrequired
body
Object representing a set of of attributes and their respective values.
Responses
Request samples
- Payload
{- "my_attribute_1": "some value",
- "my_attribute_2": "some other value",
- "my_attribute_3": "some other value"
}
Response samples
- 401
- 404
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
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.
Sync cart item catalog
Perform the following actions for a given cart item catalog:
- Add an item to the catalog.
- Add multiple items to the catalog.
- Update the attributes of an item in the catalog.
- Update the attributes of multiple items in the catalog.
- Remove an item from the catalog.
- Remove multiple items from the catalog.
You can either add, update, or delete up to 1000 cart items in a single request. Each item synced to a catalog must have a unique SKU
.
Important: You can perform only one type of action in a single sync request. Syncing items with duplicate SKU
values in a single request returns an error message with a 400
status code.
For more information, read managing cart item catalogs.
Filtering cart items
Use cart item attributes to filter items and select the ones you want to edit or delete when editing or deleting more than one item at a time.
The filters
array contains an object with the following properties:
attr
: A cart item attribute connected to the catalog. It is applied to all items in the catalog.op
: The filtering operator indicating the relationship between the value of each cart item in the catalog and the value of thevalue
property for the attribute selected inattr
.The value of
op
can be one of the following:EQ
: Equal tovalue
LT
: Less thanvalue
LE
: Less than or equal tovalue
GT
: Greater thanvalue
GE
: Greater than or equal tovalue
IN
: One of the comma-separated values thatvalue
is set to.
Note:
GE
,LE
,GT
,LT
are for numeric values only.value
: The value of the attribute selected inattr
.
Payload examples
Synchronization actions are sent as PUT
requests. See the structure for each action:
Adding an item to the catalog
{
"actions": [
{
"payload": {
"attributes": {
"color": "Navy blue",
"type": "shoes"
},
"replaceIfExists": true,
"sku": "SKU1241028",
"price": 100,
"product": {
"name": "sneakers"
}
},
"type": "ADD"
}
]
}
Adding multiple items to the catalog
{
"actions": [
{
"payload": {
"attributes": {
"color": "Navy blue",
"type": "shoes"
},
"replaceIfExists": true,
"sku": "SKU1241027",
"price": 100,
"product": {
"name": "sneakers"
}
},
"type": "ADD"
},
{
"payload": {
"attributes": {
"color": "Navy blue",
"type": "shoes"
},
"replaceIfExists": true,
"sku": "SKU1241028",
"price": 100,
"product": {
"name": "sneakers"
}
},
"type": "ADD"
}
]
}
Updating the attributes of an item in the catalog
{
"actions": [
{
"payload": {
"attributes": {
"age": 11,
"origin": "germany"
},
"createIfNotExists": false,
"sku": "SKU1241028",
"product": {
"name": "sneakers"
}
},
"type": "PATCH"
}
]
}
Updating the attributes of multiple items in the catalog
{
"actions": [
{
"payload": {
"attributes": {
"color": "red"
},
"filters": [
{
"attr": "color",
"op": "EQ",
"value": "blue"
}
]
},
"type": "PATCH_MANY"
}
]
}
Removing an item from the catalog
{
"actions": [
{
"payload": {
"sku": "SKU1241028"
},
"type": "REMOVE"
}
]
}
Removing multiple items from the catalog
{
"actions": [
{
"payload": {
"filters": [
{
"attr": "color",
"op": "EQ",
"value": "blue"
}
]
},
"type": "REMOVE_MANY"
}
]
}
Removing shoes of sizes above 45 from the catalog
Let's imagine that we have a shoe store and we have decided to stop selling shoes larger than size 45. We can remove from the catalog all the shoes of sizes above 45 with a single action:
{
"actions": [
{
"payload": {
"filters": [
{
"attr": "size",
"op": "GT",
"value": "45"
}
]
},
"type": "REMOVE_MANY"
}
]
}
Authorizations:
path Parameters
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. |
Request Body schema: application/jsonrequired
body
required | Array of objects [ 1 .. 1000 ] items |
version | integer >= 1 The version number of the catalog to apply the actions on. |
Responses
Request samples
- Payload
{- "actions": [
- {
- "type": "ADD",
- "payload": {
- "sku": "SKU1241028",
- "price": 99.99,
- "attributes": {
- "origin": "germany",
- "color": "blue"
}, - "product": {
- "name": "sample_product"
}, - "replaceIfExists": false
}
}
], - "version": 244
}
Response samples
- 200
- 400
- 401
- 404
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "accountId": 3886,
- "modified": "2021-09-12T10:12:42Z",
- "name": "seafood",
- "description": "seafood catalog",
- "subscribedApplicationsIds": [
- 1,
- 2,
- 3
], - "version": 6,
- "createdBy": 6
}
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 coupon reservation
Create a coupon reservation for the specified customer profiles on the specified coupon. You can also create a reservation via the Campaign Manager using the Create coupon code reservation effect.
- If the Reservation mandatory option was selected when creating the specified coupon, the endpoint creates a hard reservation, meaning only users who have this coupon code reserved can redeem it. Otherwise, the endpoint creates a soft reservation, meaning the coupon will be associated with the specified customer profiles (they show up when using the List customer data endpoint), but any user can redeem it. This can be useful, for example, to display a coupon wallet for customers when they visit your store.
- If the Coupon visibility option was selected when creating the specified coupon, the coupon code is implicitly soft-reserved for all customers, and the code will be returned for all customer profiles in the List customer data endpoint.
To delete a reservation, use the Delete reservation endpoint.
Authorizations:
path Parameters
couponValue required | string Example: SUMMER10 The code of the coupon. |
Request Body schema: application/jsonrequired
body
integrationIDs required | Array of strings <= 1000 items List of customer integration IDs. |
Responses
Request samples
- Payload
{- "integrationIDs": [
- "URNGV8294NV",
- "BZGGC2454PA"
]
}
Response samples
- 201
- 400
- 401
- 404
{- "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 coupon reservations
Remove all the coupon reservations from the provided customer profile integration IDs and the provided coupon code.
Authorizations:
path Parameters
couponValue required | string Example: SUMMER10 The code of the coupon. |
Request Body schema: application/jsonrequired
body
integrationIDs required | Array of strings <= 1000 items List of customer integration IDs. |
Responses
Request samples
- Payload
{- "integrationIDs": [
- "URNGV8294NV",
- "BZGGC2454PA"
]
}
Response samples
- 400
- 401
- 404
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
List customers that have this coupon reserved
Return all customers that have this coupon marked as reserved. This includes hard and soft reservations.
Authorizations:
path Parameters
couponValue required | string Example: SUMMER10 The code of the coupon. |
Responses
Response samples
- 200
- 400
- 401
- 404
{- "totalResultSize": 1,
- "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
}
]
}
Update customer profile
Update or create a Customer Profile. This endpoint triggers the Rule Builder.
You can use this endpoint to:
- Set attributes on the given customer profile. Ensure you create the attributes in the Campaign Manager, first.
- Modify the audience the customer profile is a member of.
Performance tips
- Updating a customer profile returns a response with the requested integration state.
- You can use the
responseContent
property to save yourself extra API calls. For example, you can get the customer profile details directly without extra requests. - We recommend sending requests sequentially. See Managing parallel requests.
Authorizations:
path Parameters
integrationId required | string Example: customer1 The integration identifier for this customer profile. Must be:
Once set, you cannot update this identifier. |
query Parameters
runRuleEngine | boolean Default: false Indicates whether to run the Rule Engine. If
If
|
dry | boolean (Only works when When set to |
Request Body schema: application/jsonrequired
body
attributes | object Arbitrary properties associated with this item. |
evaluableCampaignIds | Array of integers When using the These campaigns will be evaluated, even if they are disabled, allowing you to test specific campaigns before activating them. |
object | |
responseContent | Array of strings Items Enum: "customerProfile" "triggeredCampaigns" "loyalty" "event" "awardedGiveaways" "ruleFailureReasons" Extends the response with the chosen data entities. Use this property to get as much data as you need in one Update customer profile request instead of sending extra requests to other endpoints. |
Responses
Request samples
- Payload
{- "attributes": {
- "Language": "english",
- "ShippingCountry": "DE"
}, - "evaluableCampaignIds": [
- 10,
- 12
], - "audiencesChanges": {
- "adds": [
- 2,
- 4
], - "deletes": [
- 7
]
}, - "responseContent": [
- "triggeredCampaigns",
- "customerProfile"
]
}
Response samples
- 200
- 400
- 401
- 409
{- "customerProfile": {
- "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
}, - "event": {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "applicationId": 322,
- "profileId": "URNGV8294NV",
- "storeIntegrationId": "STORE-001",
- "type": "pageViewed",
- "attributes": {
- "myAttribute": "myValue"
}, - "sessionId": "175KJPS947296",
- "effects": [
- [
- null
]
], - "ledgerEntries": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "profileId": "URNGV8294NV",
- "accountId": 0,
- "loyaltyProgramId": 323414846,
- "eventId": 3,
- "amount": 100,
- "reason": "Customer appeasement.",
- "expiryDate": "2022-04-26T11:02:38Z",
- "referenceId": 0
}
], - "meta": {
- "campaigns": { },
- "coupons": { },
- "couponRejectionReason": {
- "campaignId": 244,
- "couponId": 4928,
- "reason": "CouponNotFound"
}, - "referralRejectionReason": {
- "campaignId": 0,
- "referralId": 0,
- "reason": "ReferralNotFound"
}, - "warnings": { }
}
}, - "loyalty": {
- "cards": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "programID": 125,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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"
}
], - "programs": {
- "property1": {
- "id": 5,
- "title": "My loyalty program",
- "name": "program1",
- "joinDate": "2024-04-30T15:04:05Z07:00",
- "ledger": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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": {
- "id": 5,
- "title": "My loyalty program",
- "name": "program1",
- "joinDate": "2024-04-30T15:04:05Z07:00",
- "ledger": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}, - "pointsToNextTier": 20
}
}
}
}
}, - "triggeredCampaigns": [
- {
- "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,
- "revisionFrontendState": "revised",
- "activeRevisionId": 6,
- "activeRevisionVersionId": 6,
- "version": 6,
- "currentRevisionId": 6,
- "currentRevisionVersionId": 6,
- "stageRevision": false
}
], - "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"
}
], - "awardedGiveaways": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "code": "GIVEAWAY1",
- "poolId": 1,
- "startDate": "2022-01-02T15:04:05Z07:00",
- "endDate": "2023-01-02T15:04:05Z07:00",
- "attributes": { },
- "used": true,
- "importId": 4,
- "profileIntegrationId": "R195412",
- "profileId": 1
}
], - "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,
- "props": {
- "value": "string"
}
}
], - "createdCoupons": [
- {
- "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
}
], - "createdReferrals": [
- {
- "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"
}
]
}
Update multiple customer profiles
Update (or create) up to 1000 customer profiles in 1 request.
The integrationId
must be any identifier that remains stable for
the customer. Do not use an ID that the customer can update
themselves. For example, you can use a database ID.
A customer profile can be linked to one or more sessions.
Note: This endpoint does not trigger the Rule Engine. To trigger the Rule Engine for customer profile updates, use the Update customer profile endpoint.
Authorizations:
query Parameters
silent | string Default: "yes" Example: silent=yes Possible values:
|
Request Body schema: application/jsonrequired
body
Array of objects | |||||
Array
|
Responses
Request samples
- Payload
{- "customerProfiles": [
- {
- "attributes": {
- "Language": "english",
- "ShippingCountry": "DE"
}, - "integrationId": "R195412"
}
]
}
Response samples
- 200
- 400
- 401
{- "integrationStates": [
- {
- "customerProfile": {
- "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
}
}
]
}
Delete customer's personal data
Delete all attributes on the customer profile and on entities that reference this customer profile.
Important:
- Customer data is deleted from all Applications in the environment that the API key belongs to. For example, if you use this endpoint with an API key that belongs to a sandbox Application, customer data will be deleted from all sandbox Applications. This is because customer data is shared between Applications from the same environment.
- To preserve performance, we recommend avoiding deleting customer data during peak-traffic hours.
Authorizations:
path Parameters
integrationId required | string Example: customer1 The integration ID of the customer profile. You can get the
|
Responses
Response samples
- 401
- 404
{- "message": "string",
- "errors": [
- {
- "title": "string",
- "details": "string",
- "source": {
- "pointer": "string",
- "parameter": "string",
- "line": "string",
- "resource": "string"
}
}
], - "StatusCode": 0
}
List customer data
Return the customer inventory regarding entities referencing this customer profile's integrationId
.
Typical entities returned are: customer profile information, referral codes, loyalty points, loyalty cards and reserved coupons. Reserved coupons also include redeemed coupons.
Authorizations:
path Parameters
integrationId required | string Example: customer1 The integration ID of the customer profile. You can get the
|
query Parameters
profile | boolean Set to |
referrals | boolean Set to |
coupons | boolean Set to |
loyalty | boolean Set to |
giveaways | boolean Set to |
achievements | boolean Set to |
Responses
Response samples
- 200
- 401
- 404
{- "profile": {
- "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
}, - "loyalty": {
- "cards": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "programID": 125,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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"
}
], - "programs": {
- "property1": {
- "id": 5,
- "title": "My loyalty program",
- "name": "program1",
- "joinDate": "2024-04-30T15:04:05Z07:00",
- "ledger": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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": {
- "id": 5,
- "title": "My loyalty program",
- "name": "program1",
- "joinDate": "2024-04-30T15:04:05Z07:00",
- "ledger": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}, - "pointsToNextTier": 20
}
}
}
}
}, - "referrals": [
- {
- "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",
- "referredCustomers": [
- "string"
]
}
], - "coupons": [
- {
- "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,
- "profileRedemptionCount": 5,
- "state": "active"
}
], - "giveaways": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "code": "GIVEAWAY1",
- "poolId": 1,
- "startDate": "2022-01-02T15:04:05Z07:00",
- "endDate": "2023-01-02T15:04:05Z07:00",
- "attributes": { },
- "used": true,
- "importId": 4,
- "profileIntegrationId": "R195412",
- "profileId": 1
}
], - "achievements": [
- {
- "achievementId": 3,
- "name": "FreeCoffee10Orders",
- "title": "50% off on 50th purchase.",
- "description": "50% off for every 50th purchase in a year.",
- "campaignId": 3,
- "status": "completed",
- "target": 10,
- "progress": 10,
- "startDate": "2024-01-01T15:04:05Z07:00",
- "completionDate": "2024-01-15T15:04:05Z07:00",
- "endDate": "2024-02-01T15:04:05Z07:00"
}
]
}
Represents the data related to a customer session. Typically, a customer session is the value and content of the customer's cart.
Sessions can be anonymous or linked to a customer profile and they have a life cycle from open
to closed
.
In general, a session is closed when the customer completes the checkout step.
Sessions are a key concept of Talon.One. We strongly recommend you read the documentation about customer sessions.
Update customer session
Update or create a customer session. The endpoint responds with the potential promotion rule effects that match the current cart. For example, use this endpoint to share the contents of a customer's cart with Talon.One.
Note: The currency for the session and the cart items in the session is the currency set for the Application that owns this session.
Session management
To use this endpoint, start by learning about customer sessions
and their states and refer to the state
parameter documentation the request body schema docs below.
Sessions and customer profiles
- To link a session to a customer profile, set the
profileId
parameter in the request body to a customer profile'sintegrationId
. - While you can create an anonymous session with
profileId=""
, we recommend you use a guest ID instead. - A profile can be linked to simultaneous sessions in different Applications. Either:
- Use unique session integration IDs or,
- Use the same session integration ID across all of the Applications.
Note: If the specified profile does not exist, an empty profile is created automatically. You can update it with Update customer profile.
Performance tips
- Updating a customer session returns a response with the new integration state. Use the
responseContent
property to save yourself extra API calls. For example, you can get the customer profile details directly without extra requests. - We recommend sending requests sequentially. See Managing parallel requests.
For more information, see:
- The introductory video in Getting started.
- The integration tutorial.
Authorizations:
path Parameters
customerSessionId required | string Example: session1 The You can see existing customer session integration IDs in the Campaign Manager's Sessions menu, or via the List Application session endpoint. |
query Parameters
dry | boolean Indicates whether to persist the changes. Changes are ignored when When set to
|
now | string <date-time> Example: now=2024-05-29T15:04:05Z07:00 A timestamp value of a future date that acts as a current date when included in the query. Use this parameter, for example, to test campaigns that would be evaluated for this customer session in the future (say, scheduled campaigns). Note:
|
Request Body schema: application/jsonrequired
body
required | object The representation of the customer session. |
responseContent | Array of strings Items Enum: "customerSession" "customerProfile" "coupons" "triggeredCampaigns" "referral" "loyalty" "event" "awardedGiveaways" "ruleFailureReasons" "previousReturns" Extends the response with the chosen data entities. Use this property to get as much data as you need in one Update customer session request instead of sending extra requests to other endpoints. Note: To retrieve loyalty card details, your request must include a loyalty card ID. |
Responses
Request samples
- Payload
{- "customerSession": {
- "profileId": "URNGV8294NV",
- "storeIntegrationId": "STORE-001",
- "evaluableCampaignIds": [
- 10,
- 12
], - "couponCodes": [
- "XMAS-20-2021"
], - "referralCode": "NT2K54D9",
- "loyaltyCards": [
- "loyalty-card-1"
], - "state": "open",
- "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
}
], - "additionalCosts": {
- "shipping": {
- "price": 9
}
}, - "identifiers": [
- "d41306257915f83fe01e54092ae470f631161ea16fcf4415842eed41470386ea"
], - "attributes": {
- "ShippingCity": "Berlin"
}
}, - "responseContent": [
- "customerSession",
- "customerProfile"
]
}
Response samples
- 200
- 400
- 401
- 409
{- "customerSession": {
- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "integrationId": "URNGV8294NV",
- "applicationId": 322,
- "profileId": "URNGV8294NV",
- "storeIntegrationId": "STORE-001",
- "evaluableCampaignIds": [
- 10,
- 12
], - "couponCodes": [
- "XMAS-20-2021"
], - "referralCode": "NT2K54D9",
- "loyaltyCards": [
- "loyalty-card-1"
], - "state": "open",
- "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
}
], - "additionalCosts": {
- "shipping": {
- "price": 9
}
}, - "identifiers": [
- "d41306257915f83fe01e54092ae470f631161ea16fcf4415842eed41470386ea"
], - "attributes": {
- "ShippingCity": "Berlin"
}, - "firstSession": true,
- "total": 119.99,
- "cartItemTotal": 99.99,
- "additionalCostTotal": 20,
- "updated": "2020-02-08T14:15:22Z"
}, - "customerProfile": {
- "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
}, - "event": {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "applicationId": 322,
- "profileId": "URNGV8294NV",
- "storeIntegrationId": "STORE-001",
- "type": "pageViewed",
- "attributes": {
- "myAttribute": "myValue"
}, - "sessionId": "175KJPS947296",
- "effects": [
- [
- null
]
], - "ledgerEntries": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "profileId": "URNGV8294NV",
- "accountId": 0,
- "loyaltyProgramId": 323414846,
- "eventId": 3,
- "amount": 100,
- "reason": "Customer appeasement.",
- "expiryDate": "2022-04-26T11:02:38Z",
- "referenceId": 0
}
], - "meta": {
- "campaigns": { },
- "coupons": { },
- "couponRejectionReason": {
- "campaignId": 244,
- "couponId": 4928,
- "reason": "CouponNotFound"
}, - "referralRejectionReason": {
- "campaignId": 0,
- "referralId": 0,
- "reason": "ReferralNotFound"
}, - "warnings": { }
}
}, - "loyalty": {
- "cards": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "programID": 125,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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"
}
], - "programs": {
- "property1": {
- "id": 5,
- "title": "My loyalty program",
- "name": "program1",
- "joinDate": "2024-04-30T15:04:05Z07:00",
- "ledger": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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": {
- "id": 5,
- "title": "My loyalty program",
- "name": "program1",
- "joinDate": "2024-04-30T15:04:05Z07:00",
- "ledger": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}, - "pointsToNextTier": 20
}
}
}
}
}, - "referral": {
- "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",
- "referredCustomers": [
- "string"
]
}, - "coupons": [
- {
- "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,
- "profileRedemptionCount": 5
}
], - "triggeredCampaigns": [
- {
- "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,
- "revisionFrontendState": "revised",
- "activeRevisionId": 6,
- "activeRevisionVersionId": 6,
- "version": 6,
- "currentRevisionId": 6,
- "currentRevisionVersionId": 6,
- "stageRevision": false
}
], - "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,
- "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"
}
], - "createdCoupons": [
- {
- "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
}
], - "createdReferrals": [
- {
- "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"
}
], - "awardedGiveaways": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "code": "GIVEAWAY1",
- "poolId": 1,
- "startDate": "2022-01-02T15:04:05Z07:00",
- "endDate": "2023-01-02T15:04:05Z07:00",
- "attributes": { },
- "used": true,
- "importId": 4,
- "profileIntegrationId": "R195412",
- "profileId": 1
}
], - "return": {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "applicationId": 322,
- "accountId": 3886,
- "returnedCartItems": [
- {
- "position": 2,
- "quantity": 1
}
], - "eventId": 123,
- "sessionId": 123,
- "sessionIntegrationId": "0c0e0207-eb30-4e06-a56c-2b7c8a64953c",
- "profileId": 123,
- "profileIntegrationId": "0c0e0207-eb30-4e06-a56c-2b7c8a64953c",
- "createdBy": 123
}, - "previousReturns": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "applicationId": 322,
- "accountId": 3886,
- "returnedCartItems": [
- {
- "position": 2,
- "quantity": 1
}
], - "eventId": 123,
- "sessionId": 123,
- "sessionIntegrationId": "0c0e0207-eb30-4e06-a56c-2b7c8a64953c",
- "profileId": 123,
- "profileIntegrationId": "0c0e0207-eb30-4e06-a56c-2b7c8a64953c",
- "createdBy": 123
}
]
}
Get customer session
Get the details of the given customer session.
You can get the same data via other endpoints that also apply changes, which can help you save requests and increase performance. See:
Authorizations:
path Parameters
customerSessionId required | string Example: session1 The You can see existing customer session integration IDs in the Campaign Manager's Sessions menu, or via the List Application session endpoint. |
Responses
Response samples
- 200
- 400
- 401
{- "customerSession": {
- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "integrationId": "URNGV8294NV",
- "applicationId": 322,
- "profileId": "URNGV8294NV",
- "storeIntegrationId": "STORE-001",
- "evaluableCampaignIds": [
- 10,
- 12
], - "couponCodes": [
- "XMAS-20-2021"
], - "referralCode": "NT2K54D9",
- "loyaltyCards": [
- "loyalty-card-1"
], - "state": "open",
- "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
}
], - "additionalCosts": {
- "shipping": {
- "price": 9
}
}, - "identifiers": [
- "d41306257915f83fe01e54092ae470f631161ea16fcf4415842eed41470386ea"
], - "attributes": {
- "ShippingCity": "Berlin"
}, - "firstSession": true,
- "total": 119.99,
- "cartItemTotal": 99.99,
- "additionalCostTotal": 20,
- "updated": "2020-02-08T14:15:22Z"
}, - "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,
- "props": {
- "value": "string"
}
}
]
}
Return cart items
Create a new return request for the specified cart items.
This endpoint automatically changes the session state from closed
to partially_returned
.
Note: This will roll back any effects associated with these cart items. For more information, see our documentation on session states and this tutorial.
Authorizations:
path Parameters
customerSessionId required | string Example: session1 The You can see existing customer session integration IDs in the Campaign Manager's Sessions menu, or via the List Application session endpoint. |
query Parameters
dry | boolean Indicates whether to persist the changes. Changes are ignored when |
Request Body schema: application/jsonrequired
body
required | object |
responseContent | Array of strings Items Enum: "customerSession" "customerProfile" "coupons" "triggeredCampaigns" "referral" "loyalty" "event" "previousReturns" Extends the response with the chosen data entities. Use this property to get as much data as you need in one Update customer session request instead of sending extra requests to other endpoints. |
Responses
Request samples
- Payload
{- "return": {
- "returnedCartItems": [
- {
- "position": 2,
- "quantity": 1
}
]
}, - "responseContent": [
- "customerSession",
- "customerProfile"
]
}
Response samples
- 200
- 400
- 401
{- "customerSession": {
- "id": 6,
- "created": "2020-02-07T08:15:22Z",
- "integrationId": "URNGV8294NV",
- "applicationId": 322,
- "profileId": "URNGV8294NV",
- "storeIntegrationId": "STORE-001",
- "evaluableCampaignIds": [
- 10,
- 12
], - "couponCodes": [
- "XMAS-20-2021"
], - "referralCode": "NT2K54D9",
- "loyaltyCards": [
- "loyalty-card-1"
], - "state": "open",
- "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
}
], - "additionalCosts": {
- "shipping": {
- "price": 9
}
}, - "identifiers": [
- "d41306257915f83fe01e54092ae470f631161ea16fcf4415842eed41470386ea"
], - "attributes": {
- "ShippingCity": "Berlin"
}, - "firstSession": true,
- "total": 119.99,
- "cartItemTotal": 99.99,
- "additionalCostTotal": 20,
- "updated": "2020-02-08T14:15:22Z"
}, - "customerProfile": {
- "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
}, - "event": {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "applicationId": 322,
- "profileId": "URNGV8294NV",
- "storeIntegrationId": "STORE-001",
- "type": "pageViewed",
- "attributes": {
- "myAttribute": "myValue"
}, - "sessionId": "175KJPS947296",
- "effects": [
- [
- null
]
], - "ledgerEntries": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "profileId": "URNGV8294NV",
- "accountId": 0,
- "loyaltyProgramId": 323414846,
- "eventId": 3,
- "amount": 100,
- "reason": "Customer appeasement.",
- "expiryDate": "2022-04-26T11:02:38Z",
- "referenceId": 0
}
], - "meta": {
- "campaigns": { },
- "coupons": { },
- "couponRejectionReason": {
- "campaignId": 244,
- "couponId": 4928,
- "reason": "CouponNotFound"
}, - "referralRejectionReason": {
- "campaignId": 0,
- "referralId": 0,
- "reason": "ReferralNotFound"
}, - "warnings": { }
}
}, - "loyalty": {
- "cards": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "programID": 125,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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"
}
], - "programs": {
- "property1": {
- "id": 5,
- "title": "My loyalty program",
- "name": "program1",
- "joinDate": "2024-04-30T15:04:05Z07:00",
- "ledger": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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": {
- "id": 5,
- "title": "My loyalty program",
- "name": "program1",
- "joinDate": "2024-04-30T15:04:05Z07:00",
- "ledger": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}, - "pointsToNextTier": 20
}
}
}
}
}, - "referral": {
- "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",
- "referredCustomers": [
- "string"
]
}, - "coupons": [
- {
- "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,
- "profileRedemptionCount": 5
}
], - "triggeredCampaigns": [
- {
- "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,
- "revisionFrontendState": "revised",
- "activeRevisionId": 6,
- "activeRevisionVersionId": 6,
- "version": 6,
- "currentRevisionId": 6,
- "currentRevisionVersionId": 6,
- "stageRevision": false
}
], - "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,
- "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"
}
], - "createdCoupons": [
- {
- "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
}
], - "createdReferrals": [
- {
- "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"
}
], - "awardedGiveaways": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "code": "GIVEAWAY1",
- "poolId": 1,
- "startDate": "2022-01-02T15:04:05Z07:00",
- "endDate": "2023-01-02T15:04:05Z07:00",
- "attributes": { },
- "used": true,
- "importId": 4,
- "profileIntegrationId": "R195412",
- "profileId": 1
}
], - "return": {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "applicationId": 322,
- "accountId": 3886,
- "returnedCartItems": [
- {
- "position": 2,
- "quantity": 1
}
], - "eventId": 123,
- "sessionId": 123,
- "sessionIntegrationId": "0c0e0207-eb30-4e06-a56c-2b7c8a64953c",
- "profileId": 123,
- "profileIntegrationId": "0c0e0207-eb30-4e06-a56c-2b7c8a64953c",
- "createdBy": 123
}, - "previousReturns": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "applicationId": 322,
- "accountId": 3886,
- "returnedCartItems": [
- {
- "position": 2,
- "quantity": 1
}
], - "eventId": 123,
- "sessionId": 123,
- "sessionIntegrationId": "0c0e0207-eb30-4e06-a56c-2b7c8a64953c",
- "profileId": 123,
- "profileIntegrationId": "0c0e0207-eb30-4e06-a56c-2b7c8a64953c",
- "createdBy": 123
}
]
}
Reopen customer session
Reopen a closed customer session. For example, if a session has been completed but still needs to be edited, you can reopen it with this endpoint. A reopen session is treated like a standard open session.
When reopening a session:
- The
talon_session_reopened
event is triggered. You can see it in the Events view in the Campaign Manager. - The session state is updated to
open
. - Modified budgets and triggered effects when the session was closed are rolled back except for the list below.
Effects and budgets unimpacted by a session reopening
The following effects and budgets are left the way they were once the session was originally closed:
- Add free item effect
- Any non-pending loyalty points
- Award giveaway
- Coupon and referral creation
- Coupon reservation
- Custom effect
- Update attribute value
- Update cart item attribute value
To see an example of roll back, see the Cancelling a session with campaign budgets tutorial.
Note: If your order workflow requires you to create a new session instead of reopening a session, use the Update customer session endpoint to cancel a closed session and create a new one.
Authorizations:
path Parameters
customerSessionId required | string Example: session1 The You can see existing customer session integration IDs in the Campaign Manager's Sessions menu, or via the List Application session endpoint. |
Responses
Response samples
- 200
- 400
- 401
{- "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,
- "props": {
- "value": "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:
- Built-in events: They are triggered by various endpoints, such as the Update customer session endpoint. Learn more.
- Custom events: They are triggered by the Track event endpoint.
Track event
Triggers a custom event.
To use this endpoint:
- Define a custom event in the Campaign Manager.
- Update or create a rule to check for this event.
- Trigger the event with this endpoint. After you have successfully sent an event to Talon.One, you can list the received events in the Events view in the Campaign Manager.
Talon.One also offers a set of built-in events. Ensure you do not create a custom event when you can use a built-in event.
For example, use this endpoint to trigger an event when a customer shares a link to a product. See the tutorial.
Important
profileId
is required even though the schema does not say it.- If the customer profile ID is new, a new profile is automatically created but the
customer_profile_created
built-in event is not triggered. - We recommend sending requests sequentially. See Managing parallel requests.
Authorizations:
query Parameters
silent | string Default: "yes" Example: silent=yes Possible values:
|
dry | boolean Indicates whether to persist the changes. Changes are ignored when |
Request Body schema: application/jsonrequired
body
type required | string non-empty A string representing the event name. Must not be a reserved event name. You create this value when you create an attribute of type |
profileId | string ID of the customer profile set by your integration layer. Note: If the customer does not yet have a known |
storeIntegrationId | string [ 1 .. 1000 ] characters The integration ID of the store. You choose this ID when you create a store. |
evaluableCampaignIds | Array of integers When using the These campaigns will be evaluated, even if they are disabled, allowing you to test specific campaigns before activating them. |
attributes | object Arbitrary additional JSON properties associated with the event. They must be created in the Campaign Manager before setting them with this property. See creating custom attributes. |
responseContent | Array of strings Items Enum: "customerProfile" "triggeredCampaigns" "loyalty" "event" "awardedGiveaways" "ruleFailureReasons" Optional list of requested information to be present on the response related to the tracking custom event. |
Responses
Request samples
- Payload
{- "profileId": "URNGV8294NV",
- "storeIntegrationId": "STORE-001",
- "evaluableCampaignIds": [
- 10,
- 12
], - "type": "pageViewed",
- "attributes": {
- "myAttribute": "myValue"
}, - "responseContent": [
- "triggeredCampaigns",
- "customerProfile"
]
}
Response samples
- 200
- 400
- 401
- 409
{- "customerProfile": {
- "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
}, - "event": {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "applicationId": 322,
- "profileId": "URNGV8294NV",
- "storeIntegrationId": "STORE-001",
- "type": "pageViewed",
- "attributes": {
- "myAttribute": "myValue"
}, - "sessionId": "175KJPS947296",
- "effects": [
- [
- null
]
], - "ledgerEntries": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "profileId": "URNGV8294NV",
- "accountId": 0,
- "loyaltyProgramId": 323414846,
- "eventId": 3,
- "amount": 100,
- "reason": "Customer appeasement.",
- "expiryDate": "2022-04-26T11:02:38Z",
- "referenceId": 0
}
], - "meta": {
- "campaigns": { },
- "coupons": { },
- "couponRejectionReason": {
- "campaignId": 244,
- "couponId": 4928,
- "reason": "CouponNotFound"
}, - "referralRejectionReason": {
- "campaignId": 0,
- "referralId": 0,
- "reason": "ReferralNotFound"
}, - "warnings": { }
}
}, - "loyalty": {
- "cards": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "programID": 125,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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"
}
], - "programs": {
- "property1": {
- "id": 5,
- "title": "My loyalty program",
- "name": "program1",
- "joinDate": "2024-04-30T15:04:05Z07:00",
- "ledger": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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": {
- "id": 5,
- "title": "My loyalty program",
- "name": "program1",
- "joinDate": "2024-04-30T15:04:05Z07:00",
- "ledger": {
- "currentBalance": 100,
- "pendingBalance": 10,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}, - "pointsToNextTier": 20
}
}
}
}
}, - "triggeredCampaigns": [
- {
- "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,
- "revisionFrontendState": "revised",
- "activeRevisionId": 6,
- "activeRevisionVersionId": 6,
- "version": 6,
- "currentRevisionId": 6,
- "currentRevisionVersionId": 6,
- "stageRevision": false
}
], - "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"
}
], - "awardedGiveaways": [
- {
- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "code": "GIVEAWAY1",
- "poolId": 1,
- "startDate": "2022-01-02T15:04:05Z07:00",
- "endDate": "2023-01-02T15:04:05Z07:00",
- "attributes": { },
- "used": true,
- "importId": 4,
- "profileIntegrationId": "R195412",
- "profileId": 1
}
], - "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,
- "props": {
- "value": "string"
}
}
], - "createdCoupons": [
- {
- "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
}
], - "createdReferrals": [
- {
- "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"
}
]
}
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.
Get customer's loyalty balances
Retrieve loyalty ledger balances for the given Integration ID in the specified loyalty program. You can filter balances by date and subledger ID, and include tier-related information in the response.
Note: If no filtering options are applied, you retrieve all loyalty balances on the current date for the given integration ID.
Loyalty balances are calculated when Talon.One receives your request using the points stored in our database, so retrieving a large number of balances at once can impact performance.
For more information, see:
Authorizations:
path Parameters
loyaltyProgramId required | integer Example: 33 Identifier of the profile-based loyalty program. You can get the ID with the List loyalty programs endpoint. |
integrationId required | string Example: customer1 The integration identifier for this customer profile. Must be:
Once set, you cannot update this identifier. |
query Parameters
endDate | string <date-time> Example: endDate=2024-05-29T15:04:05Z07:00 Used to return expired, active, and pending loyalty balances before this timestamp. You can enter any past, present, or future timestamp value. Note:
|
subledgerId | string Example: subledgerId=subledger1 The ID of the subledger by which we filter the data. |
includeTiers | boolean Default: false Indicates whether tier information is included in the response. When set to |
includeProjectedTier | boolean Default: false Indicates whether the customer's projected tier information is included in the response. When set to Note We recommend filtering by |
Responses
Response samples
- 200
- 400
- 401
- 404
{- "balance": {
- "activePoints": 286,
- "pendingPoints": 50,
- "spentPoints": 150,
- "expiredPoints": 286,
- "currentTier": {
- "id": 11,
- "name": "bronze",
- "startDate": "2021-05-03T12:32:00Z07:00",
- "expiryDate": "2022-08-02T15:04:05Z07:00",
- "downgradePolicy": "one_down"
}, - "projectedTier": {
- "projectedActivePoints": 198,
- "stayInTierPoints": 2,
- "projectedTierName": "Tier 1"
}, - "pointsToNextTier": 20,
- "nextTierName": "silver"
}, - "subledgerBalances": {
- "mysubledger": {
- "activePoints": 286,
- "pendingPoints": 50,
- "spentPoints": 150,
- "expiredPoints": 25
}
}
}
List customer's loyalty transactions
Retrieve paginated results of loyalty transaction logs for the given Integration ID in the specified loyalty program.
You can filter transactions by date. If no filters are applied, the last 50 loyalty transactions for the given integration ID are returned.
Note: To retrieve all loyalty program transaction logs in a given loyalty program, use the List loyalty program transactions endpoint.
Authorizations:
path Parameters
loyaltyProgramId required | integer Example: 33 Identifier of the profile-based loyalty program. You can get the ID with the List loyalty programs endpoint. |
integrationId required | string Example: customer1 The integration identifier for this customer profile. Must be:
Once set, you cannot update this identifier. |
query Parameters
subledgerId | string Example: subledgerId=subledger1 The ID of the subledger by which we filter the data. |
loyaltyTransactionType | string Enum: "manual" "session" "import" Example: loyaltyTransactionType=manual Filter results by loyalty transaction type:
|
startDate | string <date-time> Example: startDate=2024-05-29T15:04:05Z07: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:05Z07: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. |
Responses
Response samples
- 200
- 400
- 401
- 404
{- "hasMore": true,
- "data": [
- {
- "created": "2022-01-02T15:04:05Z07:00",
- "programId": 324,
- "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,
- "rulesetId": 11,
- "ruleName": "Add 2 points"
}
]
}
List customer's unused loyalty points
Get paginated results of loyalty points for a given Integration ID in the specified profile-based loyalty program. This endpoint returns only the balances of unused points linked to a customer profile.
You can filter points by status:
active
: Points ready to be redeemed.pending
: Points with a start date in the future.expired
: Points with an expiration date in the past.
Authorizations:
path Parameters
loyaltyProgramId required | integer Example: 33 Identifier of the profile-based loyalty program. You can get the ID with the List loyalty programs endpoint. |
integrationId required | string Example: customer1 The integration identifier for this customer profile. Must be:
Once set, you cannot update this identifier. |
query Parameters
status | string Default: "active" Enum: "active" "pending" "expired" Example: status=active Filter points based on their status. |
subledgerId | string Example: subledgerId=subledger1 The ID of the subledger by which we filter the data. |
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. |
Responses
Response samples
- 200
- 400
- 401
- 404
{- "hasMore": true,
- "data": [
- {
- "id": 123,
- "created": "2022-01-02T15:04:05Z07:00",
- "programId": 324,
- "customerSessionId": "05c2da0d-48fa-4aa1-b629-898f58f1584d",
- "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
}
]
}
Represents loyalty cards.
Loyalty cards allow your customers to collect and spend loyalty points within a card-based loyalty program.
Link customer profile to card
Loyalty cards allow customers to collect and spend loyalty points within a card-based loyalty program. They are useful to gamify loyalty programs and can be used with or without customer profiles linked to them.
Link a customer profile to a given loyalty card for the card to be set as Registered. This affects how it can be used. See the docs.
Note: You can link as many customer profiles to a given loyalty card as the card user limit allows.
Authorizations:
path Parameters
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. |
Request Body schema: application/jsonrequired
body
integrationId required | string The integrationId of the customer profile. |
Responses
Request samples
- Payload
{- "integrationId": "R195412"
}
Response samples
- 200
- 400
- 401
- 404
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "programID": 125,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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 card's point balances
Retrieve loyalty balances for the given loyalty card in the specified loyalty program with filtering options applied. If no filtering options are applied, all loyalty balances for the given loyalty card are returned.
Authorizations:
path Parameters
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. |
query Parameters
endDate | string <date-time> Example: endDate=2024-05-29T15:04:05Z07:00 Used to return expired, active, and pending loyalty balances before this timestamp. You can enter any past, present, or future timestamp value. Note:
|
subledgerId | Array of strings Example: subledgerId=subledger1&subledgerId=subledger2 Filter results by one or more subledger IDs. Must be exact match. |
Responses
Response samples
- 200
- 400
- 401
- 404
{- "balance": {
- "activePoints": 286,
- "pendingPoints": 50,
- "spentPoints": 150,
- "expiredPoints": 286
}, - "subledgerBalances": {
- "mysubledger": {
- "activePoints": 286,
- "pendingPoints": 50,
- "spentPoints": 150,
- "expiredPoints": 25
}
}, - "profiles": [
- {
- "integrationId": "R195412",
- "timestamp": "2021-09-12T10:12:42Z"
}
]
}
List card's transactions
Retrieve loyalty transaction logs for the given loyalty card in the specified loyalty program with filtering options applied. If no filtering options are applied, the last 50 loyalty transactions for the given loyalty card are returned.
Authorizations:
path Parameters
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. |
query Parameters
subledgerId | Array of strings Example: subledgerId=subledger1&subledgerId=subledger2 Filter results by one or more subledger IDs. Must be exact match. |
loyaltyTransactionType | string Enum: "manual" "session" "import" Example: loyaltyTransactionType=manual Filter results by loyalty transaction type:
|
startDate | string <date-time> Example: startDate=2024-05-29T15:04:05Z07: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:05Z07: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. |
Responses
Response samples
- 200
- 400
- 401
- 404
{- "hasMore": true,
- "data": [
- {
- "created": "2022-01-02T15:04:05Z07:00",
- "programId": 324,
- "cardIdentifier": "summer-loyalty-card-0543",
- "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,
- "rulesetId": 11,
- "ruleName": "Add 2 points"
}
]
}
List card's unused loyalty points
Get paginated results of loyalty points for a given loyalty card identifier in a card-based loyalty program. This endpoint returns only the balances of unused points on a loyalty card.
You can filter points by status:
active
: Points ready to be redeemed.pending
: Points with a start date in the future.expired
: Points with an expiration date in the past.
Authorizations:
path Parameters
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. |
query Parameters
status | string Default: "active" Enum: "active" "pending" "expired" Example: status=active Filter points based on their status. |
subledgerId | Array of strings Example: subledgerId=subledger1&subledgerId=subledger2 Filter results by one or more subledger IDs. Must be exact match. |
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. |
Responses
Response samples
- 200
- 400
- 401
- 404
{- "hasMore": true,
- "data": [
- {
- "id": 123,
- "created": "2022-01-02T15:04:05Z07:00",
- "programId": 324,
- "customerProfileID": "URNGV8294NV",
- "customerSessionId": "05c2da0d-48fa-4aa1-b629-898f58f1584d",
- "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
}
]
}
Generate loyalty card
Generate a loyalty card in a specified card-based loyalty program.
To link the card to one or more customer profiles, use the customerProfileIds
parameter in the request body.
Note:
- The number of customer profiles linked to the loyalty card cannot exceed the loyalty program's
usersPerCardLimit
. To find the program's limit, use the Get loyalty program endpoint. - If the loyalty program has a defined code format, it will be used for the loyalty card identifier.
Authorizations:
path Parameters
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. |
Request Body schema: application/jsonrequired
body
status | string Default: "active" Enum: "active" "inactive" Status of the loyalty card. |
customerProfileIds | Array of strings Integration IDs of the customer profiles linked to the card. |
cardIdentifier | string <= 108 characters ^[A-Za-z0-9_-]*$ The alphanumeric identifier of the loyalty card. |
Responses
Request samples
- Payload
{- "status": "inactive",
- "customerProfileIds": [
- "R195412",
- "G244519"
], - "cardIdentifier": "summer-loyalty-card-0543"
}
Response samples
- 200
- 400
- 401
{- "id": 6,
- "created": "2020-06-10T09:05:27.993483Z",
- "programID": 125,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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,
- "expiredBalance": 0,
- "spentBalance": 0,
- "tentativeCurrentBalance": 100,
- "tentativePendingBalance": 20,
- "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"
}
A referral is a code shared between a customer and a prospect.
A referral is defined by:
- an advocate: person who invited their friend via referral program.
- a friend: person who receives the invite from an advocate.
- a referral code: code to be redeemed by the advocate(s) once they referred their friend.
See the docs.
Create referral code for an advocate
Creates a referral code for an advocate. The code will be valid for the referral campaign for which is created, indicated in the campaignId
parameter, and will be associated with the profile specified in the advocateProfileIntegrationId
parameter as the advocate's profile.
Authorizations:
Request Body schema: application/jsonrequired
body
campaignId required | integer ID of the campaign from which the referral received the referral code. |
advocateProfileIntegrationId required | string <= 1000 characters The Integration ID of the Advocate'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. |
friendProfileIntegrationId | string An optional Integration ID of the Friend's Profile. |
attributes | object Arbitrary properties associated with this item. |
Responses
Request samples
- Payload
{- "startDate": "2020-11-10T23:00:00Z",
- "expiryDate": "2021-11-10T23:00:00Z",
- "usageLimit": 1,
- "campaignId": 78,
- "advocateProfileIntegrationId": "URNGV8294NV",
- "friendProfileIntegrationId": "BZGGC2454PA",
- "attributes": {
- "channel": "web"
}
}
Response samples
- 201
- 400
- 401
{- "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"
}
Create referral codes for multiple advocates
Creates unique referral codes for multiple advocates. The code will be valid for the referral campaign for which it is created, indicated in the campaignId
parameter, and one referral code will be associated with one advocate using the profile specified in the advocateProfileIntegrationId
parameter as the advocate's profile.
Authorizations:
query Parameters
silent | string Default: "yes" Example: silent=yes Possible values:
|
Request Body schema: application/jsonrequired
body
campaignId required | integer The ID of the campaign from which the referral received the referral code. |
advocateProfileIntegrationIds required | Array of strings [ 1 .. 1000 ] items An array containing all the respective advocate profiles. |
usageLimit required | integer [ 0 .. 999999 ] The number of times a referral code can be used. |
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. |
attributes | object Arbitrary properties associated with this referral code. |
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 |
referralPattern | string [ 3 .. 100 ] characters The pattern used to generate referrals. The character |