Skip to main content
API docs by Redocly

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:

Authentication

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:

  1. Sign in to the Campaign Manager and open the Application of your choice, or create one.
  2. Click Settings > Integration API Keys.
  3. 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");
Security Scheme Type: API Key
Header parameter name: Authorization

Achievements

Achievements allow you to reward a customer profile for performing a number of specific actions or reaching a transactional milestone within a defined period.

For example, you can use achievements to award your customers when they purchase five cups of coffee in one week or when they purchase items worth $3000 in three months.

List customer's available achievements

Retrieve all the achievements available to a given customer and their progress in them.

Authorizations:
api_key_v1
path Parameters
integrationId
required
string
Example: customer1

The integration identifier for this customer profile. Must be:

  • Unique within the deployment.
  • Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.

Once set, you cannot update this identifier.

query Parameters
campaignIds
Array of strings
Example: campaignIds=11,20

Filter by one or more Campaign IDs, separated by a comma.

Note: If no campaigns are specified, data for all the campaigns in the Application is returned.

achievementIds
Array of strings
Example: achievementIds=11,20

Filter by one or more Achievement IDs, separated by a comma.

Note: If no achievements are specified, data for all the achievements in the Application is returned.

achievementStatus
Array of strings
Items Enum: "active" "scheduled"
Example: achievementStatus=active,scheduled

Filter by status of the achievement.

Note: If the achievement status is not specified, only data for all active achievements in the Application is returned.

currentProgressStatus
Array of strings
Items Enum: "inprogress" "completed" "not_started"
Example: currentProgressStatus=inprogress,completed

Filter by customer progress status in the achievement.

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

Content type
application/json
{
  • "totalResultSize": 1,
  • "data": [
    ]
}

List customer's achievement history

Retrieve all progress history of a given customer in the given achievement.

Authorizations:
api_key_v1
path Parameters
integrationId
required
string
Example: customer1

The integration identifier for this customer profile. Must be:

  • Unique within the deployment.
  • Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.

Once set, you cannot update this identifier.

achievementId
required
integer
Example: 321

The achievement identifier.

query Parameters
progressStatus
Array of strings
Items Enum: "inprogress" "completed" "expired"
Example: progressStatus=inprogress,completed

Filter by customer progress status in the achievement.

startDate
string <date-time>
Example: startDate=2024-05-29T15:04:05+07:00

Timestamp that filters the results to only contain achievements created on or after the start date.

endDate
string <date-time>
Example: endDate=2024-05-29T15:04:05+07:00

Timestamp that filters the results to only contain achievements created before or on the end date.

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

Content type
application/json
{
  • "totalResultSize": 1,
  • "data": [
    ]
}

Audiences

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:

  1. Set the integration property to mparticle, segment etc., depending on a third-party platform.
  2. Set integrationId to the ID of this audience in a third-party platform.

To create an audience from an existing audience in another platform:

  1. Do not use the integration property.
  2. Set integrationId to the ID of this audience in the 3rd-party platform.

To create an audience from scratch:

  1. Only set the name property.

Once you create your first audience, audience-specific rule conditions are enabled in the Rule Builder.

Authorizations:
api_key_v1
Request Body schema: application/json
required

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, mParticle, Segment, Shopify, Braze, or Iterable.

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

Content type
application/json
{
  • "name": "Travel audience",
  • "sandbox": true,
  • "description": "Travel audience 18-27",
  • "integration": "mparticle",
  • "integrationId": "382370BKDB946",
  • "createdIn3rdParty": false,
  • "lastUpdate": "2022-04-26T11:02:38Z"
}

Response samples

Content type
application/json
{
  • "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:
api_key_v1
path Parameters
audienceId
required
integer
Example: 10

The ID of the audience.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ],
  • "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:
api_key_v1
path Parameters
audienceId
required
integer
Example: 10

The ID of the audience.

Request Body schema: application/json
required

body

name
required
string non-empty

The human-friendly display name for this audience.

Responses

Request samples

Content type
application/json
{
  • "name": "Travel audience"
}

Response samples

Content type
application/json
{
  • "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:
api_key_v1
path Parameters
audienceId
required
integer
Example: 10

The ID of the audience.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ],
  • "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:
api_key_v1
Request Body schema: application/json
required

body

Array of objects
Array
action
required
string
Enum: "add" "delete"

Defines the action to perform:

  • add: Adds the customer profile to the audience.

    Note: If the customer profile does not exist, it will be created. The profile will not be visible in any Application until a session or profile update is received for that profile.

  • delete: Removes the customer profile from the audience.

profileIntegrationId
required
string <= 1000 characters

The ID of this customer profile in the third-party integration.

audienceId
required
integer

The ID of the audience. You get it via the id property when creating an audience.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ],
  • "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:
api_key_v1
path Parameters
audienceId
required
integer
Example: 10

The ID of the audience.

Request Body schema: application/json
required

body

object

Object representing a set of of attributes and their respective values.

Responses

Request samples

Content type
application/json
{
  • "my_attribute_1": "some value",
  • "my_attribute_2": "some other value",
  • "my_attribute_3": "some other value"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ],
  • "StatusCode": 0
}

Catalogs

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 the value property for the attribute selected in attr.

    The value of op can be one of the following:

    • EQ: Equal to value
    • LT: Less than value
    • LE: Less than or equal to value
    • GT: Greater than value
    • GE: Greater than or equal to value
    • IN: One of the comma-separated values that value is set to.

    Note: GE, LE, GT, LT are for numeric values only.

  • value: The value of the attribute selected in attr.

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:
api_key_v1
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/json
required

body

required
Array of objects [ 1 .. 1000 ] items
Array ([ 1 .. 1000 ] items)
type
required
string
Enum: "ADD" "PATCH" "PATCH_MANY" "REMOVE" "REMOVE_MANY" "ADD_PRICE_ADJUSTMENT"

The type of sync action.

required
AddItemCatalogAction (object) or PatchItemCatalogAction (object) or PatchManyItemsCatalogAction (object) or RemoveItemCatalogAction (object) or RemoveManyItemsCatalogAction (object) or AddPriceAdjustmentCatalogAction (object)
One of
sku
required
string

The unique SKU of the item to add.

price
number

Price of the item.

attributes
object

The attributes of the item to add.

object

The specific properties of the product this item belongs to, if available.

name
required
string

The product the item belongs to.

replaceIfExists
boolean
Default: false

Indicates whether to replace the attributes of the item if the same SKU exists.

Note: When set to true:

  • If you do not provide a new price value, the existing price value is retained.
  • If you do not provide a new product value, the product value is set to null.
version
integer >= 1

The version number of the catalog to apply the actions on.

Responses

Request samples

Content type
application/json
{
  • "actions": [
    ],
  • "version": 244
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "accountId": 3886,
  • "modified": "2021-09-12T10:12:42Z",
  • "name": "seafood",
  • "description": "seafood catalog",
  • "subscribedApplicationsIds": [
    ],
  • "version": 6,
  • "createdBy": 6
}

Coupons

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.

Note:

  • 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 is 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.

  • This endpoint overrides the coupon reservation limit set when the coupon is created. To ensure that coupons cannot be reserved after the reservation limit is reached, use the Create coupon code reservation effect in the Rule Builder and the Update customer session endpoint.

To delete a reservation, use the Delete reservation endpoint.

Authorizations:
api_key_v1
path Parameters
couponValue
required
string
Example: SUMMER10

The code of the coupon.

Request Body schema: application/json
required

body

integrationIDs
required
Array of strings <= 1000 items

List of customer integration IDs.

Responses

Request samples

Content type
application/json
{
  • "integrationIDs": [
    ]
}

Response samples

Content type
application/json
{
  • "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": [
    ],
  • "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:
api_key_v1
path Parameters
couponValue
required
string
Example: SUMMER10

The code of the coupon.

Request Body schema: application/json
required

body

integrationIDs
required
Array of strings <= 1000 items

List of customer integration IDs.

Responses

Request samples

Content type
application/json
{
  • "integrationIDs": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ],
  • "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:
api_key_v1
path Parameters
couponValue
required
string
Example: SUMMER10

The code of the coupon.

Responses

Response samples

Content type
application/json
{
  • "totalResultSize": 1,
  • "data": [
    ]
}

Customer profiles

Represents the customer's information. For instance, their contact information.

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. Note: Archived campaigns are not considered in rule evaluation when runRuleEngine is true.

    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:
api_key_v1
path Parameters
integrationId
required
string
Example: customer1

The integration identifier for this customer profile. Must be:

  • Unique within the deployment.
  • Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.

Once set, you cannot update this identifier.

query Parameters
runRuleEngine
boolean
Default: false

Indicates whether to run the Rule Engine.

If true, the response includes:

  • The effects generated by the triggered campaigns are returned in the effects property.
  • The created coupons and referral objects.

If false:

  • The rules are not executed and the effects property is always empty.
  • The response time improves.
  • You cannot use responseContent in the body.
dry
boolean

(Only works when runRuleEngine=true) Indicates whether to persist the changes. Changes are ignored when dry=true.

When set to true, you can use the evaluableCampaignIds body property to select specific campaigns to run.

Request Body schema: application/json
required

body

attributes
object

Arbitrary properties associated with this item.

evaluableCampaignIds
Array of integers

When using the dry query parameter, use this property to list the campaign to be evaluated by the Rule Engine.

These campaigns will be evaluated, even if they are disabled, allowing you to test specific campaigns before activating them.

object
adds
required
Array of integers

The IDs of the audiences for the customer to join.

deletes
required
Array of integers

The IDs of the audiences for the customer to leave.

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

Content type
application/json
{
  • "attributes": {
    },
  • "evaluableCampaignIds": [
    ],
  • "audiencesChanges": {
    },
  • "responseContent": [
    ]
}

Response samples

Content type
application/json
{
  • "customerProfile": {
    },
  • "event": {
    },
  • "loyalty": {
    },
  • "triggeredCampaigns": [
    ],
  • "ruleFailureReasons": [
    ],
  • "awardedGiveaways": [
    ],
  • "effects": [
    ],
  • "createdCoupons": [
    ],
  • "createdReferrals": [
    ]
}

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:
api_key_v1
query Parameters
silent
string
Default: "yes"
Example: silent=yes

Possible values: yes or no.

  • yes: Increases the performance of the API call by returning a 204 response.
  • no: Returns a 200 response that contains the updated customer profiles.
Request Body schema: application/json
required

body

Array of objects
Array
integrationId
required
string <= 1000 characters

The identifier of this profile, set by your integration layer. It must be unique within the account.

To get the integrationId of the profile from a sessionId, use the Update customer session.

attributes
object

Arbitrary properties associated with this item.

Responses

Request samples

Content type
application/json
{
  • "customerProfiles": [
    ]
}

Response samples

Content type
application/json
{
  • "integrationStates": [
    ]
}

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:
api_key_v1
path Parameters
integrationId
required
string
Example: customer1

The integration ID of the customer profile. You can get the integrationId of a profile using:

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ],
  • "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:
api_key_v1
path Parameters
integrationId
required
string
Example: customer1

The integration ID of the customer profile. You can get the integrationId of a profile using:

query Parameters
profile
boolean

Set to true to include customer profile information in the response.

referrals
boolean

Set to true to include referral information in the response.

coupons
boolean

Set to true to include coupon information in the response.

loyalty
boolean

Set to true to include loyalty information in the response.

giveaways
boolean

Set to true to include giveaways information in the response.

achievements
boolean

Set to true to include achievement information in the response.

Responses

Response samples

Content type
application/json
{
  • "profile": {
    },
  • "loyalty": {
    },
  • "referrals": [
    ],
  • "coupons": [
    ],
  • "giveaways": [
    ],
  • "achievements": [
    ]
}

Customer sessions

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 it is the currency set for the Application linked to this session. - Archived campaigns are not considered for rule evaluation.

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's integrationId.
  • 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:

Authorizations:
api_key_v1
path Parameters
customerSessionId
required
string
Example: session1

The integration ID of the customer session. You set this ID when you create a customer session.

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 dry=true.

When set to true:

  • The endpoint considers only the payload that you pass when closing the session. When you do not use the dry parameter, the endpoint behaves as a typical PUT endpoint. Each update builds upon the previous ones.
  • You can use the evaluableCampaignIds body property to select specific campaigns to run.

See the docs.

now
string <date-time>
Example: now=2024-05-29T15:04:05+07: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:

  • It must be an RFC3339 timestamp string.
  • It can only be a date in the future.
  • It can only be used if the dry parameter in the query is set to true.
Request Body schema: application/json
required

body

required
object

The representation of the customer session.

profileId
string

ID of the customer profile set by your integration layer.

Note: If the customer does not yet have a known profileId, we recommend you use a guest profileId.

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 dry query parameter, use this property to list the campaign to be evaluated by the Rule Engine.

These campaigns will be evaluated, even if they are disabled, allowing you to test specific campaigns before activating them.

couponCodes
Array of strings[ items <= 100 characters ]

Any coupon codes entered.

Important - for requests only:

  • If you create a coupon budget for your campaign, ensure the session contains a coupon code by the time you close it.
  • In requests where dry=false, providing an empty array discards any previous coupons. To avoid this, omit the parameter entirely.
referralCode
string <= 100 characters

Any referral code entered.

Important - for requests only:

  • If you create a referral budget for your campaign, ensure the session contains a referral code by the time you close it.
  • In requests where dry=false, providing an empty value discards the previous referral code. To avoid this, omit the parameter entirely.
loyaltyCards
Array of strings <= 1 items

Identifier of a loyalty card.

state
string
Default: "open"
Enum: "open" "closed" "partially_returned" "cancelled"

Indicates the current state of the session. Sessions can be created as open or closed. The state transitions are:

  1. open → closed
  2. open → cancelled
  3. Either:
  4. partially_returned → cancelled

For more information, see Customer session states.

Array of objects

The items to add to this session. Do not exceed 1000 items and ensure the sum of all cart item's quantity does not exceed 10.000 per request.

Array
sku
required
string non-empty

Stock keeping unit of item.

quantity
required
integer >= 1

Number of units of this item. Due to cart item flattening, if you provide a quantity greater than 1, the item will be split in as many items as the provided quantity. This will impact the number of per-item effects triggered from your campaigns.

name
string

Name of item.

returnedQuantity
integer

Number of returned items, calculated internally based on returns of this item.

remainingQuantity
integer

Remaining quantity of the item, calculated internally based on returns of this item.

price
number

Price of the item in the currency defined by your Application. This field is required if this item is not part of a catalog. If it is part of a catalog, setting a price here overrides the price from the catalog.

category
string

Type, group or model of the item.

object

The specific properties of the product this item belongs to, if available.

name
required
string

The product the item belongs to.

weight
number

Weight of item in grams.

height
number

Height of item in mm.

width
number

Width of item in mm.

length
number

Length of item in mm.

position
number

Position of the Cart Item in the Cart (calculated internally).

attributes
object

Use this property to set a value for the attributes of your choice. Attributes represent any information to attach to this cart item.

Custom cart item attributes must be created in the Campaign Manager before you set them with this property.

Note: Any previously defined attributes that you do not include in the array will be removed.

object

Use this property to set a value for the additional costs of this item, such as a shipping cost. They must be created in the Campaign Manager before you set them with this property. See Managing additional costs.

additional property
object
price
required
number
catalogItemID
integer

The catalog item ID.

object

Use this property to set a value for the additional costs of this session, such as a shipping cost.

They must be created in the Campaign Manager before you set them with this property. See Managing additional costs.

additional property
object
price
required
number
identifiers
Array of strings <= 5 items

Session custom identifiers that you can set limits on or use inside your rules.

For example, you can use IP addresses as identifiers to potentially identify devices and limit discounts abuse in case of customers creating multiple accounts. See the tutorial.

Important: Ensure the session contains an identifier by the time you close it if:

attributes
object

Use this property to set a value for the attributes of your choice. Attributes represent any information to attach to your session, like the shipping city.

You can use built-in attributes or custom ones. Custom attributes must be created in the Campaign Manager before you set them with this property.

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

Content type
application/json
{
  • "customerSession": {
    },
  • "responseContent": [
    ]
}

Response samples

Content type
application/json
{
  • "customerSession": {
    },
  • "customerProfile": {
    },
  • "event": {
    },
  • "loyalty": {
    },
  • "referral": {
    },
  • "coupons": [
    ],
  • "triggeredCampaigns": [
    ],
  • "effects": [
    ],
  • "ruleFailureReasons": [
    ],
  • "createdCoupons": [
    ],
  • "createdReferrals": [
    ],
  • "awardedGiveaways": [
    ],
  • "return": {
    },
  • "previousReturns": [
    ]
}

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:
api_key_v1
path Parameters
customerSessionId
required
string
Example: session1

The integration ID of the customer session. You set this ID when you create a customer session.

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

Content type
application/json
{
  • "customerSession": {
    },
  • "effects": [
    ]
}

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:
api_key_v1
path Parameters
customerSessionId
required
string
Example: session1

The integration ID of the customer session. You set this ID when you create a customer session.

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 dry=true.

Request Body schema: application/json
required

body

required
object
required
Array of objects

List of cart items to be returned.

Array
position
required
integer

The index of the cart item in the provided customer session's cartItems property.

quantity
integer

Number of cart items to return.

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

Content type
application/json
{
  • "return": {
    },
  • "responseContent": [
    ]
}

Response samples

Content type
application/json
{
  • "customerSession": {
    },
  • "customerProfile": {
    },
  • "event": {
    },
  • "loyalty": {
    },
  • "referral": {
    },
  • "coupons": [
    ],
  • "triggeredCampaigns": [
    ],
  • "effects": [
    ],
  • "ruleFailureReasons": [
    ],
  • "createdCoupons": [
    ],
  • "createdReferrals": [
    ],
  • "awardedGiveaways": [
    ],
  • "return": {
    },
  • "previousReturns": [
    ]
}

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:
api_key_v1
path Parameters
customerSessionId
required
string
Example: session1

The integration ID of the customer session. You set this ID when you create a customer session.

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

Content type
application/json
{
  • "effects": [
    ]
}

Events

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:

Track event

Triggers a custom event.

To use this endpoint:

  1. Define a custom event in the Campaign Manager.
  2. Update or create a rule to check for this event.
  3. 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

  1. profileId is required even though the schema does not specify it.
  2. If the customer profile ID is new, a new profile is automatically created but the customer_profile_created built-in event is not triggered.
  3. We recommend sending requests sequentially. See Managing parallel requests.
  4. Archived campaigns are not considered in rule evaluation.
Authorizations:
api_key_v1
query Parameters
silent
string
Default: "yes"
Example: silent=yes

Possible values: yes or no.

  • yes: Increases the performance of the API call by returning a 204 response.
  • no: Returns a 200 response that contains the updated customer profiles.
dry
boolean

Indicates whether to persist the changes. Changes are ignored when dry=true.

forceCompleteEvaluation
boolean
Default: false

Forces evaluation for all matching campaigns regardless of the campaign evaluation mode. Requires dry=true.

Request Body schema: application/json
required

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 event in the Campaign Manager.

profileId
string

ID of the customer profile set by your integration layer.

Note: If the customer does not yet have a known profileId, we recommend you use a guest profileId.

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 dry query parameter, use this property to list the campaign to be evaluated by the Rule Engine.

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.

loyaltyCards
Array of strings <= 1 items

Identifier of the loyalty card used during this event.

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

Content type
application/json
{
  • "profileId": "URNGV8294NV",
  • "storeIntegrationId": "STORE-001",
  • "evaluableCampaignIds": [
    ],
  • "type": "pageViewed",
  • "attributes": {
    },
  • "loyaltyCards": [
    ],
  • "responseContent": [
    ]
}

Response samples

Content type
application/json
{
  • "customerProfile": {
    },
  • "event": {
    },
  • "loyalty": {
    },
  • "triggeredCampaigns": [
    ],
  • "ruleFailureReasons": [
    ],
  • "awardedGiveaways": [
    ],
  • "effects": [
    ],
  • "createdCoupons": [
    ],
  • "createdReferrals": [
    ]
}

Loyalty

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:
api_key_v1
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:

  • Unique within the deployment.
  • Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.

Once set, you cannot update this identifier.

query Parameters
endDate
string <date-time>
Example: endDate=2024-05-29T15:04:05+07:00

Used to return expired, active, and pending loyalty balances before this timestamp. You can enter any past, present, or future timestamp value.

Note:

  • It must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
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 true, the response includes information about the current tier and the number of points required to move to next tier.

includeProjectedTier
boolean
Default: false

Indicates whether the customer's projected tier information is included in the response.

When set to true, the response includes information about the customer's active points and the name of the projected tier.

Note We recommend filtering by subledgerId for better performance.

Responses

Response samples

Content type
application/json
{
  • "balance": {
    },
  • "subledgerBalances": {
    }
}

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:
api_key_v1
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:

  • Unique within the deployment.
  • Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.

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:

  • manual: Loyalty transaction that was done manually.
  • session: Loyalty transaction that resulted from a customer session.
  • import: Loyalty transaction that was imported from a CSV file.
startDate
string <date-time>
Example: startDate=2024-05-29T15:04:05+07:00

Date and time from which results are returned. Results are filtered by transaction creation date.

Note:

  • It must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
endDate
string <date-time>
Example: endDate=2024-05-29T15:04:05+07:00

Date and time by which results are returned. Results are filtered by transaction creation date.

Note:

  • It must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
pageSize
integer [ 1 .. 1000 ]
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

Content type
application/json
{
  • "hasMore": true,
  • "data": [
    ]
}

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:
api_key_v1
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:

  • Unique within the deployment.
  • Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID.

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 .. 1000 ]
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

Content type
application/json
{
  • "hasMore": true,
  • "data": [
    ]
}

Loyalty cards

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:
api_key_v1
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/json
required

body

integrationId
required
string

The integrationId of the customer profile.

Responses

Request samples

Content type
application/json
{
  • "integrationId": "R195412"
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "programID": 125,
  • "programName": "Loyalty_program",
  • "programTitle": "Loyalty program",
  • "status": "active",
  • "blockReason": "Current card lost. Customer needs a new card.",
  • "identifier": "summer-loyalty-card-0543",
  • "usersPerCardLimit": 111,
  • "profiles": [
    ],
  • "ledger": {
    },
  • "subledgers": {
    },
  • "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:
api_key_v1
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:05+07:00

Used to return expired, active, and pending loyalty balances before this timestamp. You can enter any past, present, or future timestamp value.

Note:

  • It must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
subledgerId
Array of strings
Example: subledgerId=subledger1&subledgerId=subledger2

Filter results by one or more subledger IDs. Must be exact match.

Responses

Response samples

Content type
application/json
{
  • "balance": {
    },
  • "subledgerBalances": {
    },
  • "profiles": [
    ]
}

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:
api_key_v1
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:

  • manual: Loyalty transaction that was done manually.
  • session: Loyalty transaction that resulted from a customer session.
  • import: Loyalty transaction that was imported from a CSV file.
startDate
string <date-time>
Example: startDate=2024-05-29T15:04:05+07:00

Date and time from which results are returned. Results are filtered by transaction creation date.

Note:

  • It must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
endDate
string <date-time>
Example: endDate=2024-05-29T15:04:05+07:00

Date and time by which results are returned. Results are filtered by transaction creation date.

Note:

  • It must be an RFC3339 timestamp string.
  • You can include a time component in your string, for example, T23:59:59 to specify the end of the day. The time zone setting considered is UTC. If you do not include a time component, a default time value of T00:00:00 (midnight) in UTC is considered.
pageSize
integer [ 1 .. 1000 ]
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

Content type
application/json
{
  • "hasMore": true,
  • "data": [
    ]
}

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:
api_key_v1
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 .. 1000 ]
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

Content type
application/json
{
  • "hasMore": true,
  • "data": [
    ]
}

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:
api_key_v1
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/json
required

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

Content type
application/json
{
  • "status": "inactive",
  • "customerProfileIds": [
    ],
  • "cardIdentifier": "summer-loyalty-card-0543"
}

Response samples

Content type
application/json
{
  • "id": 6,
  • "created": "2020-06-10T09:05:27.993483Z",
  • "programID": 125,
  • "programName": "Loyalty_program",
  • "programTitle": "Loyalty program",
  • "status": "active",
  • "blockReason": "Current card lost. Customer needs a new card.",
  • "identifier": "summer-loyalty-card-0543",
  • "usersPerCardLimit": 111,
  • "profiles": [
    ],
  • "ledger": {
    },
  • "subledgers": {
    },
  • "modified": "2021-09-12T10:12:42Z",
  • "oldCardIdentifier": "summer-loyalty-card-0543",
  • "newCardIdentifier": "summer-loyalty-card-0543",
  • "batchId": "wdefpov"
}

Referrals

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.

Note: Any referral limits set are ignored when you use this endpoint.

Authorizations:
api_key_v1
Request Body schema: application/json
required

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. 0 means no limit but any campaign usage limits will still apply.

friendProfileIntegrationId
string

An optional Integration ID of the Friend's Profile.

attributes
object

Arbitrary properties associated with this item.

Responses

Request samples

Content type
application/json
{
  • "startDate": "2020-11-10T23:00:00Z",
  • "expiryDate": "2021-11-10T23:00:00Z",
  • "usageLimit": 1,
  • "campaignId": 78,
  • "advocateProfileIntegrationId": "URNGV8294NV",
  • "friendProfileIntegrationId": "BZGGC2454PA",
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "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.

Note: Any referral limits set are ignored when you use this endpoint.

Authorizations:
api_key_v1
query Parameters
silent
string
Default: "yes"
Example: silent=yes

Possible values: yes or no.

  • yes: Increases the performance of the API call by returning a 204 response.
  • no: Returns a 200 response that contains the updated customer profiles.
Request Body schema: application/json
required

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. 0 means no limit but any campaign usage limits will still apply.

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 [A-Z, 0-9] regular expression.

referralPattern
string [ 3 .. 100 ] characters

The pattern used to generate referrals. The character # is a placeholder and is replaced by a random character from the validCharacters set.

Responses

Request samples

Content type
application/json
{
  • "startDate": "2020-11-10T23:00:00Z",
  • "expiryDate": "2021-11-10T23:00:00Z",
  • "usageLimit": 1,
  • "campaignId": 45,
  • "advocateProfileIntegrationIds": [
    ],
  • "attributes": {
    },
  • "validCharacters": [
    ],
  • "referralPattern": "REF-###-###"
}

Response samples

Content type
application/json
{
  • "totalResultSize": 1,
  • "data": [
    ]
}