swagger: '2.0'
info:
title: Management API reference docs
version: ''
description: >
The Management API allows you to programmatically do what the Campaign
Manager does.
For example, use it for management purposes and backoffice systems.
For more background information about this API, see [Management API
overview](https://docs.talon.one/docs/dev/management-api/overview)
Ensure you [authenticate](#section/Authentication) to make requests to the
API.
**Warnings:**
- This API is not meant to be used in real-time integrations that directly
serve your end users.
- This API supports a maximum of **3 requests per second** for each of these
endpoints.
Are you looking for a different API?
If you need the API to:
- Integrate with Talon.One directly and send real-time data, see [the Integration API reference docs](https://docs.talon.one/integration-api).
- Integrate with Talon.One from a CEP or CDP platform, see [the Third-party API reference docs](https://docs.talon.one/third-party-api).
# Authentication
host: yourbaseurl.talon.one
schemes:
- https
produces:
- application/json
consumes:
- application/json
securityDefinitions:
manager_auth:
type: apiKey
name: Authorization
in: header
description: >
This authentication scheme relies on a bearer token that you can use to
access all the endpoints of the Management API.
To create the token:
1. Get a bearer token by calling the
[createSession](#operation/createSession) endpoint.
1. Use the `token` property of the response in the HTTP header of your
next queries:
`Authorization: Bearer $TOKEN`.
A token is valid for 3 months. In accordance with best pratices, use your
generated token
for all your API requests. Do **not** regenerate a token for each request.
**Note:** We recommend that you use a [Management API
key](https://docs.talon.one/management-api#section/Authentication/management_key)
instead of a bearer token.
management_key:
type: apiKey
name: Authorization
in: header
description: >
The API key authentication gives you access to the endpoints selected by
the admin who created the key.
Using an API key is the recommended authentication method.
The key must be generated by an admin and given to the developer that
requires it:
1. Log into the Campaign Manager and click **Account** > **Management API
keys**.
1. Click **Create Key** and give it a name.
1. Set an expiration date.
1. Choose the endpoints the key should give access to.
1. Click **Create Key**.
1. Share it with your developer.
The developer can now use the API key in the HTTP header, prefixing it
with `ManagementKey-v1`:
```
Authorization: ManagementKey-v1 bd9479c59e16f9dbc644d33aa74d58270fe13bf3
```
security:
- manager_auth: []
- management_key: []
tags:
- name: Accounts and users
description: >
Operations for updating account information such as billing email
addresses, inviting users, etc.
- name: Additional costs
description: >
An extra fee applied to the cart. For example, shipping fees or processing
fees.
See the
[docs](https://docs.talon.one/docs/product/account/dev-tools/managing-additional-costs).
- name: Analytics
description: >
Analytics are used to retrieve statistical data about the performance of
campaigns within an Application.
- name: Applications
description: >
Represents an Application in the Campaign Manager.
An Application is the target of every Integration API request to
Talon.One.
One Application can hold various API keys used for Integration API
requests.
You may have multiple Applications within one account,
for example staging and production, or different international markets.
See the [docs](https://docs.talon.one/docs/product/applications/overview).
- name: Attributes
description: >
Represents a piece of information related to one of the entities avaialbe
in the Campaign Manager. Use
them to create highly customized rules.
See the
[docs](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes).
- name: Audiences
description: >
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](https://docs.talon.one/docs/product/audiences/overview).
- name: Campaign templates
description: |
Represents templates used to generate campaigns from.
- name: Campaigns
description: >
Represents the primary resource used to control the behavior of the
Talon.One Rule Engine.
They combine rulesets, coupons, and limits into a single unit.
See the [docs](https://docs.talon.one/docs/product/campaigns/overview).
- name: Catalogs
description: >
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](https://docs.talon.one/docs/product/account/dev-tools/managing-cart-item-catalogs).
- name: Collections
description: >
Represents a collection of arbitrary values that you can use inside rules.
For example, a list of SKUs.
See the
[docs](https://docs.talon.one/docs/product/campaigns/managing-collections).
- name: Coupons
description: >
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](https://docs.talon.one/docs/product/campaigns/coupons/coupon-page-overview).
- name: Customer data
description: >
Represents the data of a customer, including sessions and events used for
reporting and debugging in the Campaign Manager.
- name: Events
description: >
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](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
endpoint. [Learn
more](https://docs.talon.one/docs/dev/concepts/entities/events).
- **Custom events:** They are triggered by the [Track
event](https://docs.talon.one/integration-api#tag/Events/operation/trackEventV2)
endpoint.
- name: Giveaways
description: >
Represents a program that rewards customers with giveaways, such as free
gift cards.
See the [docs](https://docs.talon.one/docs/product/giveaways/overview).
- name: Logs
description: >
Operations to query the Talon.One logs. They contain all incoming and
outgoing requests.
- name: Loyalty
description: >
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](https://docs.talon.one/docs/product/applications/displaying-customer-profiles)
or [loyalty
cards](https://docs.talon.one/docs/product/loyalty-programs/card-based/card-based-overview).
See [the Product
docs](https://docs.talon.one/docs/product/loyalty-programs/overview) for
more information.
- name: Loyalty cards
description: >
Represents loyalty cards.
[Loyalty
cards](https://docs.talon.one/docs/product/loyalty-programs/card-based/card-based-overview)
allow your customers to collect and spend loyalty points within a
card-based loyalty program.
- name: Notifications
description: >
Represents the notifications that customers can create about various
events. See [Managing
notifications](https://docs.talon.one/docs/product/applications/outbound-notifications).
- name: Referrals
description: >
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](https://docs.talon.one/docs/product/campaigns/referrals/referral-overview).
- name: Roles
description: >
Represents a set of permissions assigned to a user.
See the
[docs](https://docs.talon.one/docs/product/account/account-settings/managing-roles).
- name: Sessions
description: |
Represents a session used for authentication purposes.
Create one with the [Create session](#operation/createSession) endpoint.
- name: Stores
description: |
Represents physical or digital stores, branches, and franchises.
- name: Webhooks
description: |
A way to send information from Talon.One to the URI of your choice.
See the [docs](https://docs.talon.one/docs/dev/getting-started/webhooks).
paths:
/v1/applications:
get:
operationId: getApplications
summary: List Applications
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List all applications in the current account.
tags:
- Applications
parameters:
- &ref_0
name: pageSize
in: query
required: false
type: integer
minimum: 1
maximum: 1000
default: 1000
description: The number of items in this response.
- &ref_1
name: skip
in: query
required: false
type: integer
description: The number of items to skip when paging through large result sets.
- &ref_2
name: sort
in: query
required: false
type: string
description: >
The field by which results should be sorted. By default, results are
sorted in ascending order. To sort them in descending order, prefix
the field name with `-`.
**Note:** This parameter works only with numeric fields.
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/Application'
'/v1/applications/{applicationId}':
get:
operationId: getApplication
summary: Get Application
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Get the application specified by the ID.
tags:
- Applications
parameters:
- &ref_3
name: applicationId
in: path
required: true
type: integer
description: >-
The ID of the Application. It is displayed in your Talon.One
deployment URL.
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Application'
'/v1/applications/{applicationId}/campaigns':
get:
operationId: getCampaigns
summary: List campaigns
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List the campaigns of the specified application that match your filter
criteria.
tags:
- Campaigns
parameters:
- *ref_0
- *ref_1
- *ref_2
- *ref_3
- &ref_6
name: campaignState
in: query
description: >
Filter results by the state of the campaign.
- `enabled`: Campaigns that are scheduled, running (activated), or
expired.
- `running`: Campaigns that are running (activated).
- `disabled`: Campaigns that are disabled.
- `expired`: Campaigns that are expired.
- `archived`: Campaigns that are archived.
- `draft`: Campaigns that are drafts.
required: false
type: string
enum:
- enabled
- disabled
- archived
- draft
- scheduled
- running
- expired
- name: name
in: query
description: >-
Filter results performing case-insensitive matching against the name
of the campaign.
required: false
type: string
- name: tags
in: query
description: >
Filter results performing case-insensitive matching against the tags
of the campaign. When used in conjunction with the "name" query
parameter, a logical OR will be performed to search both tags and
name for the provided values
required: false
type: string
- name: createdBefore
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the campaign creation timestamp. You
can use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: createdAfter
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the campaign creation timestamp. You
can use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: campaignGroupId
in: query
description: >-
Filter results to campaigns owned by the specified campaign access
group ID.
required: false
type: integer
- name: templateId
in: query
type: integer
description: The ID of the Campaign Template this Campaign was created from.
- name: storeId
in: query
description: Filter results to campaigns linked to the specified store ID.
required: false
type: integer
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/Campaign'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/applications/{applicationId}/campaigns/{campaignId}':
get:
operationId: getCampaign
summary: Get campaign
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve the given campaign.
tags:
- Campaigns
parameters:
- *ref_3
- &ref_4
name: campaignId
in: path
description: >-
The ID of the campaign. It is displayed in your Talon.One deployment
URL.
required: true
type: integer
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Campaign'
put:
operationId: updateCampaign
summary: Update campaign
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Update the given campaign.
tags:
- Campaigns
parameters:
- *ref_3
- *ref_4
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/UpdateCampaign'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Campaign'
delete:
operationId: deleteCampaign
summary: Delete campaign
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Delete the given campaign.
tags:
- Campaigns
parameters:
- *ref_3
- *ref_4
responses:
'204':
description: No Content
'/v1/applications/{applicationId}/campaigns/{campaignId}/copy':
post:
operationId: copyCampaignToApplications
summary: Copy the campaign into the specified Application
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Copy the campaign into all specified Applications.
tags:
- Campaigns
parameters:
- *ref_3
- *ref_4
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/CampaignCopy'
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/Campaign'
'/v1/notifications/{notificationId}/activation':
put:
operationId: notificationActivation
summary: Activate or deactivate notification
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Activate or deactivate the given notification.
When `enabled` is false, updates will no longer be sent for the given
notification.
tags:
- Notifications
parameters:
- name: notificationId
in: path
required: true
type: integer
description: >-
The ID of the notification. Get it with the appropriate _List
notifications_ endpoint.
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NotificationActivation'
responses:
'204':
description: No Content
'/v1/loyalty_programs/{loyaltyProgramId}/notifications/added_deducted_points':
post:
operationId: postAddedDeductedPointsNotification
summary: Create notification about added or deducted loyalty points
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Create a notification about added or deducted loyalty points in a given
profile-based loyalty program.
A notification for added or deducted loyalty points is different from
regular webhooks
in that it is loyalty program-scoped and has a predefined payload.
For more information, see [Managing loyalty
notifications](https://docs.talon.one/docs/product/loyalty-programs/profile-based/managing-loyalty-notifications).
tags:
- Notifications
parameters:
- &ref_5
name: loyaltyProgramId
in: path
type: integer
required: true
description: >
Identifier of the profile-based loyalty program. You can get the ID
with
the [List loyalty
programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms)
endpoint.
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewBaseNotification'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/BaseNotification'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/loyalty_programs/{loyaltyProgramId}/notifications/pending_points':
post:
operationId: postPendingPointsNotification
summary: Create notification about pending loyalty points
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Create a notification about pending loyalty points for a given
profile-based loyalty program. For more information, see [Managing
loyalty
notifications](https://docs.talon.one/docs/product/loyalty-programs/profile-based/managing-loyalty-notifications).
tags:
- Notifications
parameters:
- *ref_5
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewBaseNotification'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/BaseNotification'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/applications/{applicationId}/catalogs/notifications/strikethrough':
post:
operationId: postCatalogsStrikethroughNotification
summary: Create strikethrough notification
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Create a notification for the in the given Application.
For more information, see [Managing
notifications](https://docs.talon.one/docs/product/applications/outbound-notifications).
See the [payload](https://docs.talon.one/outbound-notifications) you
will receive.
tags:
- Notifications
parameters:
- *ref_3
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewBaseNotification'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/BaseNotification'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/applications/{applicationId}/campaigns_search':
post:
operationId: getCampaignByAttributes
summary: List campaigns that match the given attributes
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Get a list of all the campaigns that match a set of attributes.
tags:
- Campaigns
parameters:
- *ref_0
- *ref_1
- *ref_2
- *ref_3
- *ref_6
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/CampaignSearch'
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/Campaign'
'/v1/applications/{applicationId}/campaigns/{campaignId}/rulesets':
get:
operationId: getRulesets
summary: List campaign rulesets
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List all rulesets of this campaign. A ruleset is a revision of the rules
of a campaign.
**Important:** The response also includes deleted rules.
You should only consider the latest revision of the returned rulesets.
tags:
- Campaigns
parameters:
- *ref_0
- *ref_1
- *ref_2
- *ref_3
- *ref_4
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/Ruleset'
'/v1/applications/{applicationId}/campaigns/{campaignId}/rulesets/{rulesetId}':
get:
operationId: getRuleset
summary: Get ruleset
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve the specified ruleset.
tags:
- Campaigns
parameters:
- *ref_3
- *ref_4
- name: rulesetId
in: path
description: The ID of the ruleset.
required: true
type: integer
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Ruleset'
'/v1/applications/{applicationId}/campaigns/{campaignId}/coupons':
post:
operationId: createCoupons
summary: Create coupons
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Create coupons according to some pattern. Up to 20.000 coupons can be
created without a unique prefix. When a unique prefix is provided, up to
200.000 coupons can be created.
tags:
- Coupons
parameters:
- &ref_7
name: silent
in: query
default: 'yes'
description: >
Possible values: `yes` or `no`.
- `yes`: Increases the perfomance of the API call by returning a 204
response.
- `no`: Returns a 200 response that contains the updated customer
profiles.
required: false
type: string
- *ref_3
- *ref_4
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewCoupons'
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/Coupon'
'204':
description: No Content
put:
operationId: updateCouponBatch
summary: Update coupons
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Update all coupons, or a specific batch of coupons in the given
campaign.
You can find the `batchId` in the **Coupons** view of your Application
in the Campaign Manager, or you can use [List
coupons](#operation/getCouponsWithoutTotalCount).
Important
- Only send sequential requests to this endpoint.
- Requests to this endpoint timeout after 30 minutes. If you hit a timeout, reach out to our support team.
To update a specific coupon, use [Update
coupon](#operation/updateCoupon).
tags:
- Coupons
parameters:
- *ref_3
- *ref_4
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/UpdateCouponBatch'
responses:
'204':
description: No Content
delete:
operationId: deleteCoupons
summary: Delete coupons
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Deletes all the coupons matching the specified criteria.
tags:
- Coupons
parameters:
- *ref_3
- *ref_4
- name: value
in: query
description: >-
Filter results performing case-insensitive matching against the
coupon code. Both the code and the query are folded to remove all
non-alpha-numeric characters.
required: false
type: string
- name: createdBefore
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: createdAfter
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: startsAfter
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: startsBefore
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: expiresAfter
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: expiresBefore
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: valid
in: query
enum:
- expired
- validNow
- validFuture
description: >
- `expired`: Matches coupons in which the expiration date is set and
in the past.
- `validNow`: Matches coupons in which start date is null or in the
past and expiration date is null or in the future.
- `validFuture`: Matches coupons in which start date is set and in
the future.
required: false
type: string
- &ref_9
name: batchId
in: query
description: Filter results by batches of coupons
required: false
type: string
- name: usable
in: query
enum:
- 'true'
- 'false'
description: >
- `true`: only coupons where `usageCounter < usageLimit` will be
returned.
- `false`: only coupons where `usageCounter >= usageLimit` will be
returned.
type: string
- &ref_8
name: referralId
in: query
description: >-
Filter the results by matching them with the ID of a referral. This
filter shows the coupons created by redeeming a referral code.
required: false
type: integer
- name: recipientIntegrationId
in: query
description: >
Filter results by match with a profile id specified in the coupon's
`RecipientIntegrationId` field.
required: false
type: string
- name: exactMatch
in: query
description: >-
Filter results to an exact case-insensitive matching against the
coupon code
required: false
type: boolean
default: false
responses:
'204':
description: No Content
'/v1/applications/{applicationId}/campaigns/{campaignId}/coupons_with_recipients':
post:
operationId: createCouponsForMultipleRecipients
summary: Create coupons for multiple recipients
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Create coupons according to some pattern for up to 1000 recipients.
tags:
- Coupons
parameters:
- *ref_7
- *ref_3
- *ref_4
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewCouponsForMultipleRecipients'
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/Coupon'
'204':
description: No Content
'/v1/applications/{applicationId}/campaigns/{campaignId}/coupons_async':
post:
operationId: createCouponsAsync
summary: Create coupons asynchronously
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Create up to 5,000,000 coupons asynchronously. You should typically use
this enpdoint when you create at least 20,001 coupons. You receive an
email when the creation is complete.
If you want to create less than 20,001 coupons, you can use the [Create
coupons](https://docs.talon.one/management-api#tag/Coupons/operation/createCoupons)
endpoint.
tags:
- Coupons
parameters:
- *ref_3
- *ref_4
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewCouponCreationJob'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/AsyncCouponCreationResponse'
'/v1/applications/{applicationId}/campaigns/{campaignId}/coupons/no_total':
get:
operationId: getCouponsWithoutTotalCount
summary: List coupons
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List all the coupons matching the specified criteria.
tags:
- Coupons
parameters:
- *ref_0
- *ref_1
- *ref_2
- *ref_3
- *ref_4
- name: value
in: query
description: >-
Filter results performing case-insensitive matching against the
coupon code. Both the code and the query are folded to remove all
non-alpha-numeric characters.
required: false
type: string
- name: createdBefore
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: createdAfter
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: valid
in: query
enum:
- expired
- validNow
- validFuture
description: >
Either "expired", "validNow", or "validFuture". The first option
matches coupons in which the expiration date is set and in the past.
The second matches coupons in which start date is null or in the
past and expiration date is null or in the future, the third matches
coupons in which start date is set and in the future.
required: false
type: string
- name: usable
in: query
enum:
- 'true'
- 'false'
description: >
Either "true" or "false". If "true", only coupons where
`usageCounter < usageLimit` will be returned, "false" will return
only coupons where `usageCounter >= usageLimit`.
type: string
- *ref_8
- name: recipientIntegrationId
in: query
description: >-
Filter results by match with a profile id specified in the coupon's
RecipientIntegrationId field
required: false
type: string
- *ref_9
- name: exactMatch
in: query
description: >-
Filter results to an exact case-insensitive matching against the
coupon code
required: false
type: boolean
default: false
responses:
'200':
description: OK
schema:
type: object
required:
- hasMore
- data
properties:
hasMore:
type: boolean
example: true
data:
type: array
items:
$ref: '#/definitions/Coupon'
'/v1/applications/{applicationId}/campaigns/{campaignId}/coupons/{couponId}':
put:
operationId: updateCoupon
summary: Update coupon
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Update the specified coupon.
Important
With this PUT endpoint only, any property you do not explicitly set in your request
will be set to null
.
tags:
- Coupons
parameters:
- *ref_3
- *ref_4
- &ref_10
name: couponId
in: path
description: >
The internal ID of the coupon code. You can find this value in the
`id` property from the
[List
coupons](https://docs.talon.one/management-api#tag/Coupons/operation/getCouponsWithoutTotalCount)
endpoint response.
required: true
type: string
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/UpdateCoupon'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Coupon'
delete:
operationId: deleteCoupon
summary: Delete coupon
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Delete the specified coupon.
tags:
- Coupons
parameters:
- *ref_3
- *ref_4
- *ref_10
responses:
'204':
description: No Content
'/v1/applications/{applicationId}/campaigns/{campaignId}/coupons_search_advanced/no_total':
post:
operationId: searchCouponsAdvancedWithoutTotalCount
summary: >-
List coupons that match the given attributes in campaign (without total
count)
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List the coupons whose attributes match the query criteria
in the given campaign.
The match is successful if all the attributes of the request are found
in a coupon,
even if the coupon has more attributes that are not present on the
request.
**Note:** The total count is not included in the response.
tags:
- Coupons
parameters:
- *ref_0
- *ref_1
- *ref_2
- *ref_3
- *ref_4
- name: value
in: query
description: >-
Filter results performing case-insensitive matching against the
coupon code. Both the code and the query are folded to remove all
non-alpha-numeric characters.
required: false
type: string
- name: createdBefore
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: createdAfter
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: valid
in: query
enum:
- expired
- validNow
- validFuture
description: >
Either "expired", "validNow", or "validFuture". The first option
matches coupons in which the expiration date is set and in the past.
The second matches coupons in which start date is null or in the
past and expiration date is null or in the future, the third matches
coupons in which start date is set and in the future.
required: false
type: string
- name: usable
in: query
enum:
- 'true'
- 'false'
description: >
Either "true" or "false". If "true", only coupons where
`usageCounter < usageLimit` will be returned, "false" will return
only coupons where `usageCounter >= usageLimit`.
type: string
- *ref_8
- name: recipientIntegrationId
in: query
description: >-
Filter results by match with a profile id specified in the coupon's
RecipientIntegrationId field
required: false
type: string
- name: exactMatch
in: query
description: >-
Filter results to an exact case-insensitive matching against the
coupon code
required: false
type: boolean
default: false
- *ref_9
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/AttributeQuery'
responses:
'200':
description: OK
schema:
type: object
required:
- hasMore
- data
properties:
hasMore:
type: boolean
example: true
data:
type: array
items:
$ref: '#/definitions/Coupon'
'/v1/applications/{applicationId}/coupons_search_advanced/no_total':
post:
operationId: searchCouponsAdvancedApplicationWideWithoutTotalCount
summary: List coupons that match the given attributes (without total count)
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List the coupons whose attributes match the query criteria in all the
campaigns of the given Application.
The match is successful if all the attributes of the request are found
in a coupon,
even if the coupon has more attributes that are not present on the
request.
**Note:** The total count is not included in the response.
tags:
- Coupons
parameters:
- *ref_0
- *ref_1
- *ref_2
- *ref_3
- name: value
in: query
description: >-
Filter results performing case-insensitive matching against the
coupon code. Both the code and the query are folded to remove all
non-alpha-numeric characters.
required: false
type: string
- name: createdBefore
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: createdAfter
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: valid
in: query
enum:
- expired
- validNow
- validFuture
description: >
Either "expired", "validNow", or "validFuture". The first option
matches coupons in which the expiration date is set and in the past.
The second matches coupons in which start date is null or in the
past and expiration date is null or in the future, the third matches
coupons in which start date is set and in the future.
required: false
type: string
- name: usable
in: query
enum:
- 'true'
- 'false'
description: >
Either "true" or "false". If "true", only coupons where
`usageCounter < usageLimit` will be returned, "false" will return
only coupons where `usageCounter >= usageLimit`.
type: string
- *ref_8
- name: recipientIntegrationId
in: query
description: >-
Filter results by match with a profile id specified in the coupon's
RecipientIntegrationId field
required: false
type: string
- *ref_9
- name: exactMatch
in: query
description: >-
Filter results to an exact case-insensitive matching against the
coupon code
required: false
type: boolean
default: false
- *ref_6
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/AttributeQuery'
responses:
'200':
description: OK
schema:
type: object
required:
- hasMore
- data
properties:
hasMore:
type: boolean
example: true
data:
type: array
items:
$ref: '#/definitions/Coupon'
'/v1/applications/{applicationId}/campaigns/{campaignId}/referrals/{referralId}':
delete:
operationId: deleteReferral
summary: Delete referral
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Delete the specified referral.
tags:
- Referrals
parameters:
- *ref_3
- *ref_4
- &ref_11
name: referralId
in: path
description: The ID of the referral code.
required: true
type: string
responses:
'204':
description: No Content
put:
operationId: updateReferral
summary: Update referral
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Update the specified referral.
tags:
- Referrals
parameters:
- *ref_3
- *ref_4
- *ref_11
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/UpdateReferral'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Referral'
'/v1/applications/{applicationId}/campaigns/{campaignId}/referrals/no_total':
get:
operationId: getReferralsWithoutTotalCount
summary: List referrals
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List all referrals of the specified campaign.
tags:
- Referrals
parameters:
- *ref_0
- *ref_1
- *ref_2
- *ref_3
- *ref_4
- name: code
in: query
description: >-
Filter results performing case-insensitive matching against the
referral code. Both the code and the query are folded to remove all
non-alpha-numeric characters.
required: false
type: string
- name: createdBefore
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the referral creation timestamp. You
can use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: createdAfter
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the referral creation timestamp. You
can use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: valid
in: query
enum:
- expired
- validNow
- validFuture
description: >
Either "expired", "validNow", or "validFuture". The first option
matches referrals in which the expiration date is set and in the
past. The second matches referrals in which start date is null or in
the past and expiration date is null or in the future, the third
matches referrals in which start date is set and in the future.
required: false
type: string
- name: usable
in: query
enum:
- 'true'
- 'false'
description: >
Either "true" or "false". If "true", only referrals where
`usageCounter < usageLimit` will be returned, "false" will return
only referrals where `usageCounter >= usageLimit`.
type: string
- name: advocate
in: query
required: false
type: string
description: >-
Filter results by match with a profile id specified in the
referral's AdvocateProfileIntegrationId field
responses:
'200':
description: OK
schema:
type: object
required:
- hasMore
- data
properties:
hasMore:
type: boolean
example: true
data:
type: array
items:
$ref: '#/definitions/Referral'
/v1/campaign_templates:
get:
operationId: getCampaignTemplates
summary: List campaign templates
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve a list of campaign templates.
tags:
- Campaign templates
parameters:
- *ref_0
- *ref_1
- *ref_2
- name: state
in: query
description: Filter results by the state of the campaign template.
required: false
type: string
enum:
- enabled
- disabled
- draft
- name: name
in: query
description: >-
Filter results performing case-insensitive matching against the name
of the campaign template.
required: false
type: string
- name: tags
in: query
description: >
Filter results performing case-insensitive matching against the tags
of the campaign template. When used in conjunction with the "name"
query parameter, a logical OR will be performed to search both tags
and name for the provided values.
required: false
type: string
- &ref_41
in: query
description: Filter results by user ID.
type: integer
required: false
name: userId
responses:
'200':
description: OK
schema:
type: object
required:
- hasMore
- data
properties:
hasMore:
type: boolean
example: true
data:
type: array
items:
$ref: '#/definitions/CampaignTemplate'
'/v1/applications/{applicationId}/create_campaign_from_template':
post:
operationId: createCampaignFromTemplate
summary: Create campaign from campaign template
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Use the campaign template referenced in the request body to create
a new campaign in one of the connected Applications.
If the template was created from a campaign with rules referencing
[campaign
collections](https://docs.talon.one/docs/product/campaigns/managing-collections),
the corresponding collections for the new campaign are created
automatically.
tags:
- Campaign templates
parameters:
- *ref_3
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/CreateTemplateCampaign'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/CreateTemplateCampaignResponse'
/v1/loyalty_programs:
get:
operationId: getLoyaltyPrograms
summary: List loyalty programs
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List the loyalty programs of the account.
tags:
- Loyalty
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/LoyaltyProgram'
'/v1/loyalty_programs/{loyaltyProgramId}':
get:
operationId: getLoyaltyProgram
summary: Get loyalty program
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Get the specified [loyalty
program](https://docs.talon.one/docs/product/loyalty-programs/overview).
To list all loyalty programs in your Application, use [List loyalty
programs](#operation/getLoyaltyPrograms).
To list the loyalty programs that a customer profile is part of, use the
[List customer
data](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/getCustomerInventory)
tags:
- Loyalty
parameters:
- &ref_12
name: loyaltyProgramId
in: path
type: integer
description: >
Identifier of the card-based loyalty program containing the loyalty
card. You can get the ID with
the [List loyalty
programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms)
endpoint.
required: true
responses:
'200':
description: OK
schema:
$ref: '#/definitions/LoyaltyProgram'
'/v1/loyalty_programs/{loyaltyProgramId}/import_points':
post:
operationId: importLoyaltyPoints
summary: Import loyalty points
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Upload a CSV file containing the loyalty points you want to import into
a given loyalty program.
Send the file as multipart data.
Depending on the loyalty program type, you can import the points into a
given customer profile or into a given _active_ loyalty card.
The CSV file contains the following columns:
- `customerprofileid` (optional): For profile-based loyalty programs,
the integration ID of the customer profile where the loyalty points are
imported.
- `identifier` (optional): For card-based loyalty programs, the
identifier of the loyalty card where the loyalty points are imported.
- `amount`: The amount of points to award to the customer profile.
- `startdate` (optional): The earliest date when the points can be
redeemed. The points are `active` from this date until the expiration
date.
**Note**: It must be an RFC3339 timestamp string or string `immediate`. Empty or missing values are considered `immediate`.
- `expirydate` (optional): The latest date when the points can be
redeemed. The points are `expired` after this date.
**Note**: It must be an RFC3339 timestamp string or string `unlimited`. Empty or missing values are considered `unlimited`.
- `subledgerid` (optional): The ID of the subledger that should received
the points.
- `reason` (optional): The reason why these points are awarded.
You can use the time zone of your choice. It is converted to UTC
internally by Talon.One.
**Note:** For existing customer profiles and loyalty cards, the imported
points are added to any previous active or pending points, depending on
the
value provided for `startdate`. If `startdate` matches the current date,
the imported points are _active_. If it is later, the points are
_pending_ until
the date provided for `startdate` is reached.
**Note:** We recommend limiting your file size to 500MB.
**Example for profile-based programs:**
```text
customerprofileid,amount,startdate,expirydate,subledgerid,reason
URNGV8294NV,100,2009-11-10T23:00:00Z,2009-11-11T23:00:00Z,subledger1,appeasement
```
**Example for card-based programs:**
```text
identifier,amount,startdate,expirydate,subledgerid,reason
summer-loyalty-card-0543,100,2009-11-10T23:00:00Z,2009-11-11T23:00:00Z,subledger1,appeasement
```
tags:
- Loyalty
consumes:
- multipart/form-data
parameters:
- *ref_12
- &ref_13
name: upFile
in: formData
type: string
format: csv
description: >-
The file with the information about the data that should be
imported.
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Import'
'/v1/loyalty_programs/{loyaltyProgramId}/import_customers_tiers':
post:
operationId: importLoyaltyCustomersTiers
summary: Import customers into loyalty tiers
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Upload a CSV file containing existing customers to be assigned to
existing tiers.
Send the file as multipart data.
**Important:** This endpoint only works with loyalty programs with
advanced tiers (with expiration and downgrade policy) feature enabled.
The CSV file should contain the following columns:
- `subledgerid` (optional): The ID of the subledger. If this field is
empty, the main ledger will be used.
- `customerprofileid`: The integration ID of the customer profile to
whom the tier should be assigned.
- `tiername`: The name of an existing tier to assign to the customer.
- `expirydate`: The expiration date of the tier. It should be a future
date.
About customer assignment to a tier:
- If the customer isn't already in a tier, the customer is assigned to
the specified tier during the tier import.
- If the customer is already in a tier, the customer is assigned to
match the new information provided in the CSV file.
- If the customer is already in the tier that's specified in the CSV
file, only the expiration date is updated.
You can use the time zone of your choice. It is converted to UTC
internally by Talon.One.
**Note:** We recommend limiting your file size to 500MB.
**Example:**
```csv
subledgerid,customerprofileid,tiername,expirydate
SUB1,alexa,Gold,2024-03-21T07:32:14Z
,george,Silver,2025-04-16T21:12:37Z
SUB2,avocado,Bronze,2026-05-03T11:47:01Z
```
tags:
- Loyalty
consumes:
- multipart/form-data
parameters:
- *ref_12
- *ref_13
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Import'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}':
get:
operationId: getLoyaltyPoints
summary: Get customer's full loyalty ledger
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Get the loyalty ledger for this profile integration ID.
To get the `integrationId` of the profile from a `sessionId`, use the
[Update customer
session](https://docs.talon.one/integration-api#operation/updateCustomerSessionV2)
endpoint.
**Important:** To get loyalty transaction logs for a given Integration
ID in a loyalty program,
we recommend using the Integration API's [Get customer's loyalty
logs](https://docs.talon.one/integration-api#tag/Loyalty/operation/getLoyaltyProgramProfileTransactions).
tags:
- Loyalty
parameters:
- &ref_14
name: loyaltyProgramId
in: path
type: string
description: The identifier for the loyalty program.
required: true
- &ref_15
name: integrationId
in: path
type: string
description: The identifier of the profile.
required: true
responses:
'200':
description: OK
schema:
$ref: '#/definitions/LoyaltyLedger'
'/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/add_points':
put:
operationId: addLoyaltyPoints
summary: Add points to customer profile
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Add points in the specified loyalty program for the given customer.
To get the `integrationId` of the profile from a `sessionId`, use the
[Update customer
session](https://docs.talon.one/integration-api#operation/updateCustomerSessionV2)
endpoint.
tags:
- Loyalty
parameters:
- *ref_14
- *ref_15
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/AddLoyaltyPoints'
responses:
'204':
description: No Content
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/deduct_points':
put:
operationId: removeLoyaltyPoints
summary: Deduct points from customer profile
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Deduct points from the specified loyalty program and specified customer
profile.
**Important:**
- Only active points can be deducted.
- Only pending points are rolled back when a session is cancelled or
reopened.
To get the `integrationId` of the profile from a `sessionId`, use the
[Update customer
session](https://docs.talon.one/integration-api#operation/updateCustomerSessionV2)
endpoint.
tags:
- Loyalty
parameters:
- *ref_14
- *ref_15
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/DeductLoyaltyPoints'
responses:
'204':
description: No Content
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/export_log':
get:
operationId: exportLoyaltyLedger
produces:
- application/csv
summary: Export customer's transaction logs
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Download a CSV file containing a customer's transaction logs in the
loyalty program.
**Tip:** If the exported CSV file is too large to view, you can [split
it into multiple
files](https://www.makeuseof.com/tag/how-to-split-a-huge-csv-excel-workbook-into-seperate-files/).
The generated file can contain the following columns:
- `customerprofileid`: The ID of the profile.
- `customersessionid`: The ID of the customer session.
- `rulesetid`: The ID of the rule set.
- `rulename`: The name of the rule.
- `programid`: The ID of the loyalty program.
- `type`: The type of the loyalty program.
- `name`: The name of the loyalty program.
- `subledgerid`: The ID of the subledger, when applicable.
- `startdate`: The start date of the program.
- `expirydate`: The expiration date of the program.
- `id`: The ID of the transaction.
- `created`: The timestamp of the creation of the loyalty program.
- `amount`: The number of points in that transaction.
- `archived`: Whether the session related to the transaction is
archived.
tags:
- Loyalty
parameters:
- &ref_18
name: rangeStart
in: query
required: true
type: string
format: date-time
description: >-
Only return results from after this timestamp. This must be an
RFC3339 timestamp string.
- &ref_19
name: rangeEnd
in: query
required: true
type: string
format: date-time
description: >-
Only return results from before this timestamp. This must be an
RFC3339 timestamp string.
- &ref_20
name: dateFormat
in: query
description: Determines the format of dates in the export document.
required: false
type: string
enum:
- excel
- ISO8601
- *ref_14
- *ref_15
responses:
'200':
description: OK
schema:
type: string
format: csv
examples:
application/csv: >
customerprofileid,customersessionid,rulesetid,rulename,programid,type,name,subledgerid,startdate,expirydate,id,created,amount,archived
8NHOS78H,06b0fafb-ccbf-42c7-b44b-d858e8b525022,1691,test,37,subtraction,10%
of current total,,immediate,unlimited,60803,2022-11-29
16:16:10,100.00,false
EB780RDN,06b0fafb-ccbf-42c7-b44b-d858e8b525022,1691,test,37,addition,Reimbursed
loyalty points,,immediate,unlimited,60804,2022-11-29
16:16:23,100.00,false
'/v1/loyalty_programs/{loyaltyProgramId}/export_customers_tiers':
get:
operationId: exportCustomersTiers
produces:
- application/csv
summary: Export customers' tier data
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Download a CSV file containing the tier information for customers of the
specified loyalty program.
The generated file contains the following columns:
- `programid`: The identifier of the loyalty program. It is displayed in
your Talon.One deployment URL.
- `subledgerid`: The ID of the subledger associated with the loyalty
program. This column is empty if the loyalty program has no subledger.
In this case, refer to the export file name to get the ID of the loyalty
program.
- `customerprofileid`: The ID used to integrate customer profiles with
the loyalty program.
- `tiername`: The name of the tier.
- `startdate`: The tier start date in RFC3339.
- `expirydate`: The tier expiry date in RFC3339.
You can filter the results by providing the following optional input
parameters:
- `subledgerId` (optional): Filter results by subledger ID. If no value
is provided, all subledger data for the specified loyalty program will
be exported.
- `tierName` (optional): Filter results by tier name. If no value is
provided, all tier data for the specified loyalty program will be
exported.
tags:
- Loyalty
parameters:
- *ref_14
- name: subledgerIds
in: query
type: array
required: false
items:
type: string
description: An array of subledgers IDs to filter the export by.
- name: tierNames
in: query
type: array
required: false
items:
type: string
description: An array of tier names to filter the export by.
responses:
'200':
description: OK
schema:
type: string
format: csv
examples:
application/csv: >
programid,subledgerid,customerprofileid,tiername,startdate,expirydate
1,SUB1,Dinesh,Golden,2023-08-02T15:04:05Z07:00,2024-08-02T15:04:05Z07:00
1,SUB2,Gilfoyle,Silver,2023-03-21T03:45:12Z05:00,2026-03-21T03:45:12Z05:00
'/v1/loyalty_programs/{loyaltyProgramId}/statistics':
get:
operationId: getLoyaltyStatistics
summary: Get loyalty program statistics
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve the statistics of the specified loyalty program such as the
total active points, pending points, spent points, and expired points.
**Important:** The returned data does not include the current day. All
statistics
are updated daily at 11:59 PM in the loyalty program time zone.
tags:
- Loyalty
parameters:
- *ref_12
responses:
'200':
description: OK
schema:
$ref: '#/definitions/LoyaltyDashboardData'
'/v1/loyalty_programs/{loyaltyProgramId}/export_customer_balances':
get:
operationId: exportLoyaltyBalances
produces:
- application/csv
summary: Export customer loyalty balances
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Download a CSV file containing the balance of each customer in the
loyalty program.
**Tip:** If the exported CSV file is too large to view, you can [split
it into multiple
files](https://www.makeuseof.com/tag/how-to-split-a-huge-csv-excel-workbook-into-seperate-files/).
The generated file can contain the following columns:
- `loyaltyProgramID`: The ID of the loyalty program.
- `loyaltySubledger`: The name of the subdleger, when applicatble.
- `profileIntegrationID`: The integration ID of the customer profile.
- `currentBalance`: The current point balance.
- `pendingBalance`: The number of pending points.
- `expiredBalance`: The number of expired points.
- `spentBalance`: The number of spent points.
- `currentTier`: The tier that the customer is in at the time of the
export.
tags:
- Loyalty
parameters:
- *ref_14
- &ref_16
name: endDate
in: query
required: false
type: string
format: date-time
description: >
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.
responses:
'200':
description: OK
schema:
type: string
format: csv
examples:
application/csv: >
loyaltyProgramID,loyaltySubledger,profileIntegrationID,currentBalance,pendingBalance,expiredBalance,spentBalance,currentTier
40,,8786NTHSAO8,10.00,0.00,0.00,0.00,First
40,,2735HATHOH8,20.00,0.00,0.00,0.00,First
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/loyalty_programs/{loyaltyProgramId}/export_customer_balance':
get:
operationId: exportLoyaltyBalance
produces:
- application/csv
summary: Export customer loyalty balance to CSV
deprecated: true
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
⚠️ Deprecation notice: Support for requests to this endpoint will end
soon.
To export customer loyalty balances to CSV, use the [Export customer
loyalty balances to
CSV](/management-api#tag/Loyalty/operation/exportLoyaltyBalances)
endpoint.
Download a CSV file containing the balance of each customer in the
loyalty program.
**Tip:** If the exported CSV file is too large to view, you can [split
it into multiple
files](https://www.makeuseof.com/tag/how-to-split-a-huge-csv-excel-workbook-into-seperate-files/).
tags:
- Loyalty
parameters:
- *ref_14
- *ref_16
responses:
'200':
description: OK
schema:
type: string
format: csv
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/loyalty_programs/{loyaltyProgramId}/transactions':
get:
operationId: getLoyaltyProgramTransactions
summary: List loyalty program transactions
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve all loyalty program transaction logs in a given loyalty program
with filtering options applied. Manual and imported transactions are
also included.
If no filters are applied, the last 50 loyalty transactions for the
given loyalty program are returned.
**Important:** To get loyalty transaction logs for a given Integration
ID in a loyalty program,
we recommend using the Integration API's [Get customer's loyalty
logs](https://docs.talon.one/integration-api#tag/Loyalty/operation/getLoyaltyProgramProfileTransactions).
tags:
- Loyalty
parameters:
- *ref_12
- name: loyaltyTransactionType
in: query
required: false
type: string
enum:
- manual
- session
- import
description: >
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.
- &ref_23
name: subledgerId
in: query
required: false
type: string
description: The ID of the subledger by which we filter the data.
- &ref_21
name: startDate
in: query
required: false
type: string
format: date-time
description: >
Date and time from which results are returned. Results are filtered
by transaction creation date.
**Note:** It must be an RFC3339 timestamp string.
- &ref_22
name: endDate
in: query
required: false
type: string
format: date-time
description: >
Date and time by which results are returned. Results are filtered by
transaction creation date.
**Note:** It must be an RFC3339 timestamp string.
- name: pageSize
in: query
required: false
type: integer
minimum: 1
maximum: 50
default: 50
description: The number of items in this response.
- *ref_1
responses:
'200':
description: OK
schema:
type: object
required:
- hasMore
- data
properties:
hasMore:
type: boolean
example: true
data:
type: array
items:
$ref: '#/definitions/LoyaltyProgramTransaction'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/loyalty_programs/{loyaltyProgramId}/import_cards':
post:
operationId: importLoyaltyCards
summary: Import loyalty cards
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Upload a CSV file containing the loyalty cards that you want to use in
your card-based loyalty program.
Send the file as multipart data.
It contains the following columns for each card:
- `identifier` (required): The alphanumeric identifier of the loyalty
card.
- `state` (required): The state of the loyalty card. It can be `active`
or `inactive`.
- `customerprofileids` (optional): An array of strings representing the
identifiers of the customer profiles linked to the loyalty card.
**Note:** We recommend limiting your file size to 500MB.
**Example:**
```csv
identifier,state,customerprofileids
123-456-789AT,active,Alexa001;UserA
```
tags:
- Loyalty cards
consumes:
- multipart/form-data
parameters:
- *ref_12
- *ref_13
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Import'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/loyalty_programs/{loyaltyProgramId}/export_card_balances':
get:
operationId: exportLoyaltyCardBalances
produces:
- application/csv
summary: Export all card transaction logs
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Download a CSV file containing the balances of all cards in the loyalty
program.
**Tip:** If the exported CSV file is too large to view, you can [split
it into multiple
files](https://www.makeuseof.com/tag/how-to-split-a-huge-csv-excel-workbook-into-seperate-files/).
The CSV file contains the following columns:
- `loyaltyProgramID`: The ID of the loyalty program.
- `loyaltySubledger`: The name of the subdleger, when applicatble.
- `cardIdentifier`: The alphanumeric identifier of the loyalty card.
- `cardState`:The state of the loyalty card. It can be `active` or
`inactive`.
- `currentBalance`: The current point balance.
- `pendingBalance`: The number of pending points.
- `expiredBalance`: The number of expired points.
- `spentBalance`: The number of spent points.
tags:
- Loyalty cards
parameters:
- *ref_12
- *ref_16
responses:
'200':
description: OK
schema:
type: string
format: csv
examples:
application/csv: >
loyaltyProgramID,loyaltySubledger,cardIdentifier,cardState,currentBalance,pendingBalance,expiredBalance,spentBalance
40,,111,active,10,0,0,0,5
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/loyalty_programs/{loyaltyProgramId}/cards':
get:
operationId: getLoyaltyCards
summary: List loyalty cards
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
For the given card-based loyalty program, list the loyalty cards that
match your filter criteria.
tags:
- Loyalty cards
parameters:
- *ref_0
- *ref_1
- *ref_2
- *ref_12
- name: identifier
description: Optional query parameter to search cards by identifier.
minLength: 4
in: query
required: false
type: string
- name: profileId
type: integer
in: query
description: Filter by the profile ID.
required: false
minimum: 1
responses:
'200':
description: OK
schema:
type: object
required:
- hasMore
- data
properties:
hasMore:
type: boolean
example: true
data:
type: array
items:
$ref: '#/definitions/LoyaltyCard'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}':
delete:
operationId: deleteLoyaltyCard
summary: Delete loyalty card
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Delete the given loyalty card.
tags:
- Loyalty cards
parameters:
- *ref_12
- &ref_17
name: loyaltyCardId
in: path
description: >
Identifier of the loyalty card. You can get the identifier with
the [List loyalty
cards](https://docs.talon.one/management-api#tag/Loyalty-cards/operation/getLoyaltyCards)
endpoint.
type: string
required: true
maxLength: 108
responses:
'204':
description: No Content
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
put:
operationId: updateLoyaltyCard
summary: Update loyalty card status
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Update the status of the given loyalty card. A card can be _active_ or
_inactive_.
tags:
- Loyalty cards
parameters:
- *ref_12
- *ref_17
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/UpdateLoyaltyCard'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/LoyaltyCard'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
get:
operationId: getLoyaltyCard
summary: Get loyalty card
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Get the given loyalty card.
tags:
- Loyalty cards
parameters:
- *ref_12
- *ref_17
responses:
'200':
description: OK
schema:
$ref: '#/definitions/LoyaltyCard'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/add_points':
put:
operationId: addLoyaltyCardPoints
summary: Add points to card
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Add points to the given loyalty card in the specified card-based loyalty
program.
tags:
- Loyalty cards
parameters:
- *ref_12
- *ref_17
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/AddLoyaltyPoints'
responses:
'204':
description: No Content
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/deduct_points':
put:
operationId: deductLoyaltyCardPoints
summary: Deduct points from card
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Deduct points from the given loyalty card in the specified card-based
loyalty program.
tags:
- Loyalty cards
parameters:
- *ref_12
- *ref_17
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/DeductLoyaltyPoints'
responses:
'204':
description: No Content
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/export_log':
get:
operationId: exportLoyaltyCardLedger
produces:
- application/csv
summary: Export card's ledger log
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Download a CSV file containing a loyalty card ledger log of the loyalty
program.
**Tip:** If the exported CSV file is too large to view, you can [split
it into multiple
files](https://www.makeuseof.com/tag/how-to-split-a-huge-csv-excel-workbook-into-seperate-files/).
tags:
- Loyalty cards
parameters:
- *ref_12
- *ref_17
- *ref_18
- *ref_19
- *ref_20
responses:
'200':
description: OK
schema:
type: string
format: csv
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/logs':
get:
operationId: getLoyaltyCardTransactionLogs
summary: List card's transactions
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve the transaction logs for the given [loyalty
card](https://docs.talon.one/docs/product/loyalty-programs/card-based/card-based-overview)
within the specified [card-based loyalty
program](https://docs.talon.one/docs/product/loyalty-programs/overview#loyalty-program-types)
with filtering options applied.
If no filtering options are applied, the last 50 loyalty transactions
for the given loyalty card are returned.
tags:
- Loyalty cards
parameters:
- *ref_12
- *ref_17
- *ref_21
- *ref_22
- *ref_0
- *ref_1
- *ref_23
responses:
'200':
description: OK
schema:
type: object
required:
- data
- hasMore
properties:
hasMore:
type: boolean
description: >-
true means there is more data in the source collection to
request..
example: true
data:
type: array
description: List of loyalty card transaction logs.
items:
$ref: '#/definitions/CardLedgerTransactionLogEntry'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/transfer':
put:
operationId: transferLoyaltyCard
summary: Transfer card data
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Transfer loyalty card data, such as linked customers, loyalty balances
and transactions, from a given loyalty card to a new, automatically
created loyalty card.
**Important:**
- The original card is automatically blocked once the new card is
created, and it cannot be activated again.
- The default status of the new card is _active_.
tags:
- Loyalty cards
parameters:
- *ref_12
- *ref_17
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/TransferLoyaltyCard'
responses:
'204':
description: No Content
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/giveaways/pools/{poolId}/import':
post:
operationId: importPoolGiveaways
summary: Import giveaway codes into a giveaway pool
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Upload a CSV file containing the giveaway codes that should be created.
Send the file as multipart data.
The CSV file contains the following columns:
- `code` (required): the code of your giveaway, for instance, a gift
card redemption code.
- `startdate`: the start date in RFC3339 of the code redemption period.
- `enddate`: the last date in RFC3339 of the code redemption period.
- `attributes`: A JSON object describing _custom_ giveaway attribute
names and their values, enclosed with double quotation marks.
For example, if you created a [custom attribute](https://docs.talon.one/docs/dev/concepts/attributes#custom-attributes)
called `provider` associated with the giveaway entity, the object in the CSV file, when opened in a text editor, must be: `"{"provider": "myPartnerCompany"}"`.
The `startdate` and `enddate` have nothing to do with the _validity_ of
the codes. They are only used by the Rule Engine to award the codes or
not.
You can use the time zone of your choice. The values are converted to
UTC internally by Talon.One.
**Note:**
- We recommend limiting your file size to 500MB.
- You can import the same code multiple times. Duplicate codes are
treated and distributed to customers as unique codes.
**Example:**
```text
code,startdate,enddate,attributes
GIVEAWAY1,2020-11-10T23:00:00Z,2022-11-11T23:00:00Z,"{""provider"":
""Amazon""}"
GIVEAWAY2,2020-11-10T23:00:00Z,2022-11-11T23:00:00Z,"{""provider"":
""Amazon""}"
GIVEAWAY3,2021-01-10T23:00:00Z,2022-11-11T23:00:00Z,"{""provider"":
""Aliexpress""}"
```
tags:
- Giveaways
consumes:
- multipart/form-data
parameters:
- &ref_24
name: poolId
description: >-
The ID of the pool. You can find it in the Campaign Manager, in the
**Giveaways** section.
in: path
type: integer
required: true
- *ref_13
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Import'
'/v1/giveaways/pools/{poolId}/export':
get:
operationId: exportPoolGiveaways
produces:
- application/csv
summary: Export giveaway codes of a giveaway pool
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Download a CSV file containing the giveaway codes of a specific giveaway
pool.
**Tip:** If the exported CSV file is too large to view, you can [split
it into multiple
files](https://www.makeuseof.com/tag/how-to-split-a-huge-csv-excel-workbook-into-seperate-files/).
The CSV file contains the following columns:
- `id`: The internal ID of the giveaway.
- `poolid`: The internal ID of the giveaway pool.
- `code`: The giveaway code.
- `startdate`: The validity start date in RFC3339 of the giveaway (can
be empty).
- `enddate`: The validity end date in RFC3339 of the giveaway (can be
empty).
- `attributes`: Any custom attributes associated with the giveaway code
(can be empty).
- `used`: An indication of whether the giveaway is already awarded.
- `importid`: The ID of the import which created the giveaway.
- `created`: The creation time of the giveaway code.
- `profileintegrationid`: The third-party integration ID of the customer
profile that was awarded the giveaway. Can be empty if the giveaway was
not awarded.
- `profileid`: The internal ID of the customer profile that was awarded
the giveaway. Can be empty if the giveaway was not awarded or an
internal ID does not exist.
tags:
- Giveaways
parameters:
- *ref_24
- name: createdBefore
format: date-time
description: >-
Timestamp that filters the results to only contain giveaways created
before this date. Must be an RFC3339 timestamp string.
type: string
in: query
- name: createdAfter
format: date-time
description: >-
Timestamp that filters the results to only contain giveaways created
after this date. Must be an RFC3339 timestamp string.
type: string
in: query
responses:
'200':
description: OK
schema:
type: string
format: csv
examples:
application/csv: >
id,poolid,code,startdate,enddate,attributes,used,importid,created,profileintegrationid,profileid
1,7,af18bc3839799451fb6d6b6467cf4c25e,2023-04-11T12:47:47Z,2024-04-11T12:47:47Z,"{""attribute"":
""value""}",true,2,2023-04-11T12:47:47Z,R195412,35
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
/v1/collections:
get:
operationId: listAccountCollections
summary: List collections in account
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List account-level collections in the account.
tags:
- Collections
parameters:
- *ref_0
- *ref_1
- *ref_2
- &ref_26
name: withTotalResultSize
type: boolean
in: query
description: >
When this flag is set, the result includes the total size of the
result, across all pages. This might decrease performance on large
data sets.
- When `true`: `hasMore` is true when there is a next page.
`totalResultSize` is always zero.
- When `false`: `hasMore` is always false. `totalResultSize`
contains the total number of results for this query.
- name: name
type: string
in: query
description: Filter by collection name.
required: false
responses:
'200':
description: OK
schema:
type: object
required:
- data
properties:
hasMore:
type: boolean
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/CollectionWithoutPayload'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
post:
operationId: createAccountCollection
summary: Create account-level collection
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Create an account-level collection.
tags:
- Collections
parameters:
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewCollection'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/Collection'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'409':
description: Conflict. A collection with this name already exists.
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/collections/{collectionId}':
get:
operationId: getAccountCollection
summary: Get account-level collection
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve a given account-level collection.
tags:
- Collections
parameters:
- &ref_25
name: collectionId
in: path
required: true
type: integer
description: >-
The ID of the collection. You can get it with the [List collections
in account](#operation/listAccountCollections) endpoint.
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Collection'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
put:
operationId: updateAccountCollection
summary: Update account-level collection
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Edit the description of a given account-level collection and enable or
disable the collection in the specified Applications.
tags:
- Collections
parameters:
- *ref_25
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/UpdateCollection'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Collection'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'409':
description: Conflict. A collection with this name already exists.
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
delete:
operationId: deleteAccountCollection
summary: Delete account-level collection
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Delete a given account-level collection.
tags:
- Collections
parameters:
- *ref_25
responses:
'204':
description: No Content
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/collections/{collectionId}/items':
get:
operationId: getCollectionItems
summary: Get collection items
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve items from a given collection.
You can retrieve items from both account-level collections and
campaign-level collections using this endpoint.
tags:
- Collections
parameters:
- *ref_0
- *ref_1
- *ref_25
responses:
'200':
description: OK
schema:
type: object
required:
- hasMore
- data
properties:
hasMore:
type: boolean
data:
type: array
items:
$ref: '#/definitions/CollectionItem'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/applications/{applicationId}/collections':
get:
operationId: listCollectionsInApplication
summary: List collections in Application
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List campaign-level collections from all campaigns in a given
Application.
tags:
- Collections
parameters:
- *ref_3
- *ref_0
- *ref_1
- *ref_2
- *ref_26
- name: name
type: string
in: query
description: Filter by collection name.
required: false
responses:
'200':
description: OK
schema:
type: object
required:
- data
properties:
hasMore:
type: boolean
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/Collection'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/applications/{applicationId}/campaigns/{campaignId}/collections':
get:
operationId: listCollections
summary: List collections in campaign
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List collections in a given campaign.
tags:
- Collections
parameters:
- *ref_3
- *ref_4
- *ref_0
- *ref_1
- *ref_2
- *ref_26
- name: name
type: string
in: query
description: Filter by collection name.
required: false
responses:
'200':
description: OK
schema:
type: object
required:
- data
properties:
hasMore:
type: boolean
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/Collection'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
post:
operationId: createCollection
summary: Create campaign-level collection
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Create a campaign-level collection in a given campaign.
tags:
- Collections
parameters:
- *ref_3
- *ref_4
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewCampaignCollection'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/Collection'
'/v1/applications/{applicationId}/campaigns/{campaignId}/collections/{collectionId}':
get:
operationId: getCollection
summary: Get campaign-level collection
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve a given campaign-level collection.
tags:
- Collections
parameters:
- *ref_3
- *ref_4
- &ref_27
name: collectionId
in: path
required: true
type: integer
description: >-
The ID of the collection. You can get it with the [List collections
in Application](#operation/listCollectionsInApplication) endpoint.
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Collection'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
put:
operationId: updateCollection
summary: Update campaign-level collection's description
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Edit the description of a given campaign-level collection.
tags:
- Collections
parameters:
- *ref_3
- *ref_4
- *ref_27
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/UpdateCampaignCollection'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Collection'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
delete:
operationId: deleteCollection
summary: Delete campaign-level collection
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Delete a given campaign-level collection.
tags:
- Collections
parameters:
- *ref_3
- *ref_4
- *ref_27
responses:
'204':
description: No Content
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/collections/{collectionId}/import':
post:
operationId: importAccountCollection
summary: Import data into existing account-level collection
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Upload a CSV file containing the collection of string values that should
be attached as payload for collection.
The file should be sent as multipart data.
The import **replaces** the initial content of the collection.
The CSV file **must** only contain the following column:
- `item`: the values in your collection.
A collection is limited to 500,000 items.
Example:
```
item
Addidas
Nike
Asics
```
**Note:** Before sending a request to this endpoint, ensure the data in
the CSV to import is different from the data currently stored in the
collection.
tags:
- Collections
consumes:
- multipart/form-data
parameters:
- *ref_25
- *ref_13
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Import'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/applications/{applicationId}/campaigns/{campaignId}/collections/{collectionId}/import':
post:
operationId: importCollection
summary: Import data into existing campaign-level collection
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Upload a CSV file containing the collection of string values that should
be attached as payload for collection.
The file should be sent as multipart data.
The import **replaces** the initial content of the collection.
The CSV file **must** only contain the following column:
- `item`: the values in your collection.
A collection is limited to 500,000 items.
Example:
```
item
Addidas
Nike
Asics
```
**Note:** Before sending a request to this endpoint, ensure the data in
the CSV to import is different from the data currently stored in the
collection.
tags:
- Collections
consumes:
- multipart/form-data
parameters:
- *ref_3
- *ref_4
- *ref_27
- *ref_13
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Import'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/collections/{collectionId}/export':
get:
operationId: exportAccountCollectionItems
produces:
- application/csv
summary: Export account-level collection's items
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Download a CSV file containing items from a given account-level
collection.
**Tip:** If the exported CSV file is too large to view, you can [split
it into multiple
files](https://www.makeuseof.com/tag/how-to-split-a-huge-csv-excel-workbook-into-seperate-files/).
tags:
- Collections
parameters:
- *ref_25
responses:
'200':
description: OK
schema:
type: string
format: csv
examples:
application/csv: |
item
SKU1
SKU2
SKU3
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/applications/{applicationId}/campaigns/{campaignId}/collections/{collectionId}/export':
get:
operationId: exportCollectionItems
produces:
- application/csv
summary: Export campaign-level collection's items
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Download a CSV file containing items from a given campaign-level
collection.
**Tip:** If the exported CSV file is too large to view, you can [split
it into multiple
files](https://www.makeuseof.com/tag/how-to-split-a-huge-csv-excel-workbook-into-seperate-files/).
tags:
- Collections
parameters:
- *ref_3
- *ref_4
- *ref_27
responses:
'200':
description: OK
schema:
type: string
format: csv
examples:
application/csv: |
item
SKU1
SKU2
SKU3
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/applications/{applicationId}/health_report':
get:
operationId: getApplicationApiHealth
summary: Get Application health
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Display the health of the Application and show the last time the
Application
was used.
You can also display this information from the **Settings** of an
Application, in the **Developer Settings** menu.
See the
[docs](https://docs.talon.one/docs/dev/tutorials/monitoring-integration-status).
tags:
- Applications
parameters:
- *ref_3
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ApplicationApiHealth'
'/v1/applications/{applicationId}/access_logs/no_total':
get:
operationId: getAccessLogsWithoutTotalCount
summary: Get access logs for Application
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve the list of API calls sent to the specified Application.
tags:
- Logs
parameters:
- *ref_3
- &ref_28
name: path
in: query
type: string
description: >-
Only return results where the request path matches the given regular
expression.
- &ref_29
name: method
in: query
type: string
description: >-
Only return results where the request method matches the given
regular expression.
enum:
- get
- put
- post
- delete
- patch
- &ref_30
name: status
in: query
description: Filter results by HTTP status codes.
required: false
type: string
enum:
- success
- error
- *ref_18
- *ref_19
- *ref_0
- *ref_1
- *ref_2
responses:
'200':
description: OK
schema:
type: object
required:
- hasMore
- data
properties:
hasMore:
type: boolean
data:
type: array
items:
$ref: '#/definitions/AccessLogEntry'
/v1/access_logs:
get:
operationId: getAllAccessLogs
summary: List access logs
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Fetches the access logs for the entire account. Sensitive requests
(logins) are _always_ filtered from the logs.
tags:
- Logs
parameters:
- *ref_18
- *ref_19
- *ref_28
- *ref_29
- *ref_30
- *ref_0
- *ref_1
- *ref_2
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/AccessLogEntry'
'/v1/applications/{applicationId}/campaigns/{campaignId}/analytics':
get:
operationId: getCampaignAnalytics
summary: Get analytics of campaigns
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve statistical data about the performance of the given campaign.
tags:
- Campaigns
parameters:
- *ref_3
- *ref_4
- *ref_18
- *ref_19
- name: granularity
in: query
type: string
enum:
- 1 hour
- 1 day
- 1 week
- 1 month
- 1 year
description: The time interval between the results in the returned time-series.
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/CampaignAnalytics'
'/v1/applications/{applicationId}/customers':
get:
operationId: getApplicationCustomers
summary: List application's customers
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List all the customers of the specified application.
tags:
- Customer data
parameters:
- *ref_3
- &ref_33
name: integrationId
in: query
description: >-
Filter results performing an exact matching against the profile
integration identifier.
required: false
type: string
- *ref_0
- *ref_1
- *ref_26
responses:
'200':
description: OK
schema:
type: object
required:
- data
properties:
totalResultSize:
type: integer
example: 1
hasMore:
type: boolean
data:
type: array
items:
$ref: '#/definitions/ApplicationCustomer'
'/v1/applications/{applicationId}/customer_search':
post:
operationId: getApplicationCustomersByAttributes
summary: List application customers matching the given attributes
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Get a list of the application customers matching the provided criteria.
The match is successful if all the attributes of the request are found
in a profile, even if the profile has more attributes that are not
present on the request.
tags:
- Customer data
parameters:
- *ref_3
- *ref_0
- *ref_1
- *ref_26
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/CustomerProfileSearchQuery'
responses:
'200':
description: OK
schema:
type: object
required:
- data
properties:
hasMore:
type: boolean
totalResultSize:
type: integer
data:
type: array
items:
$ref: '#/definitions/ApplicationCustomer'
/v1/customer_search/no_total:
post:
operationId: getCustomersByAttributes
summary: List customer profiles matching the given attributes
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Get a list of the customer profiles matching the provided criteria.
The match is successful if all the attributes of the request are found
in a profile, even if the profile has more attributes that are not
present on the request.
tags:
- Customer data
parameters:
- *ref_0
- *ref_1
- &ref_31
name: sandbox
in: query
type: boolean
description: Indicates whether you are pointing to a sandbox or Live customer.
required: false
default: false
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/CustomerProfileSearchQuery'
responses:
'200':
description: OK
schema:
type: object
required:
- data
properties:
hasMore:
type: boolean
totalResultSize:
type: integer
data:
type: array
items:
$ref: '#/definitions/CustomerProfile'
'/v1/customers/{customerId}':
get:
operationId: getCustomerProfile
summary: Get customer profile
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Return the details of the specified customer profile.
Performance tips
You can retrieve the same information via the Integration API, which can save you extra API requests. consider these options:
- Request the customer profile to be part of the response content using
[Update Customer Session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2).
- Send an empty update with the [Update Customer Profile](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/updateCustomerProfileV2) endpoint with `runRuleEngine=false`.
tags:
- Customer data
parameters:
- &ref_32
name: customerId
in: path
description: >
The value of the `id` property of a customer profile. Get it with
the
[List Application's
customers](https://docs.talon.one/management-api#operation/getApplicationCustomers)
endpoint.
required: true
type: integer
responses:
'200':
description: OK
schema:
$ref: '#/definitions/CustomerProfile'
/v1/customers/no_total:
get:
operationId: getCustomerProfiles
summary: List customer profiles
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List all customer profiles.
tags:
- Customer data
parameters:
- *ref_0
- *ref_1
- *ref_31
responses:
'200':
description: OK
schema:
type: object
required:
- hasMore
- data
properties:
hasMore:
type: boolean
data:
type: array
items:
$ref: '#/definitions/CustomerProfile'
'/v1/applications/{applicationId}/customers/{customerId}':
get:
operationId: getApplicationCustomer
summary: Get application's customer
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve the customers of the specified application.
tags:
- Customer data
parameters:
- *ref_3
- *ref_32
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ApplicationCustomer'
'/v1/applications/{applicationId}/customer_activity_reports/no_total':
get:
operationId: getCustomerActivityReportsWithoutTotalCount
summary: Get Activity Reports for Application Customers
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Fetch summary reports for all application customers based on a time
range. Instead of having the total number of results
in the response, this endpoint only mentions whether there are more
results.
tags:
- Customer data
parameters:
- *ref_0
- *ref_1
- *ref_2
- *ref_18
- *ref_19
- *ref_3
- name: name
in: query
description: Only return reports matching the customer name
required: false
type: string
- *ref_33
- name: campaignName
in: query
description: Only return reports matching the campaignName
required: false
type: string
- name: advocateName
in: query
description: Only return reports matching the current customer referrer name
required: false
type: string
responses:
'200':
description: OK
schema:
type: object
required:
- hasMore
- data
properties:
hasMore:
type: boolean
data:
type: array
items:
$ref: '#/definitions/CustomerActivityReport'
'/v1/applications/{applicationId}/customer_activity_reports/{customerId}':
get:
operationId: getCustomerActivityReport
summary: Get customer's activity report
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Fetch the summary report of a given customer in the given application,
in a time range.
tags:
- Customer data
parameters:
- *ref_0
- *ref_1
- *ref_18
- *ref_19
- *ref_3
- *ref_32
responses:
'200':
description: OK
schema:
$ref: '#/definitions/CustomerActivityReport'
'/v1/applications/{applicationId}/customers/{customerId}/analytics':
get:
operationId: getCustomerAnalytics
summary: Get customer's analytics report
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Fetch analytics for a given customer in the given application.
tags:
- Customer data
parameters:
- *ref_0
- *ref_1
- *ref_2
- *ref_3
- *ref_32
responses:
'200':
description: OK
schema:
$ref: '#/definitions/CustomerAnalytics'
'/v1/applications/{applicationId}/sessions':
get:
operationId: getApplicationSessions
summary: List Application sessions
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List all the sessions of the specified Application.
tags:
- Customer data
parameters:
- *ref_0
- *ref_1
- *ref_2
- name: profile
in: query
required: false
type: string
description: Profile integration ID filter for sessions. Must be exact match.
- name: state
in: query
required: false
type: string
enum:
- open
- closed
- partially_returned
- cancelled
description: Filter by sessions with this state. Must be exact match.
- name: createdBefore
in: query
description: >-
Only return events created before this date. You can use any
timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: createdAfter
in: query
description: >-
Only return events created after this date. You can use any
timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: coupon
in: query
required: false
type: string
description: Filter by sessions with this coupon. Must be exact match.
- name: referral
in: query
required: false
type: string
description: Filter by sessions with this referral. Must be exact match.
- name: integrationId
in: query
required: false
type: string
description: Filter by sessions with this integrationId. Must be exact match.
- *ref_3
responses:
'200':
description: OK
schema:
type: object
required:
- data
properties:
hasMore:
type: boolean
data:
type: array
items:
$ref: '#/definitions/ApplicationSession'
'/v1/applications/{applicationId}/sessions/{sessionId}':
get:
operationId: getApplicationSession
summary: Get Application session
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Get the details of the given session.
You can list the sessions with the [List Application
sessions](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationSessions)
endpoint.
tags:
- Customer data
parameters:
- *ref_3
- name: sessionId
in: path
description: >
The **internal** ID of the session. You can get the ID with the
[List Application
sessions](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationSessions)
endpoint.
required: true
type: integer
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ApplicationSession'
'/v1/applications/{applicationId}/events/no_total':
get:
operationId: getApplicationEventsWithoutTotalCount
summary: List Applications events
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Lists all events recorded for an application. Instead of having the
total number of results in the response, this endpoint only mentions
whether there are more results.
tags:
- Customer data
parameters:
- *ref_0
- *ref_1
- *ref_2
- name: type
in: query
required: false
type: string
description: >-
Comma-separated list of types by which to filter events. Must be
exact match(es).
- &ref_36
name: createdBefore
in: query
description: >-
Only return events created before this date. You can use any
timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- &ref_37
name: createdAfter
in: query
description: >-
Only return events created after this date. You can use any
timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: session
in: query
required: false
type: string
description: Session integration ID filter for events. Must be exact match.
- name: profile
in: query
required: false
type: string
description: Profile integration ID filter for events. Must be exact match.
- name: customerName
in: query
required: false
type: string
description: >-
Customer name filter for events. Will match substrings
case-insensitively.
minLength: 2
- name: customerEmail
in: query
required: false
type: string
description: >-
Customer e-mail address filter for events. Will match substrings
case-insensitively.
minLength: 2
- name: couponCode
in: query
required: false
type: string
description: Coupon code
- name: referralCode
in: query
required: false
type: string
description: Referral code
- name: ruleQuery
in: query
description: Rule name filter for events
required: false
type: string
- name: campaignQuery
in: query
description: Campaign name filter for events
required: false
type: string
- *ref_3
responses:
'200':
description: OK
schema:
type: object
required:
- hasMore
- data
properties:
hasMore:
type: boolean
data:
type: array
items:
$ref: '#/definitions/ApplicationEvent'
'/v1/applications/{applicationId}/event_types':
get:
operationId: getApplicationEventTypes
summary: List Applications event types
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Get all of the distinct values of the Event `type` property for events
recorded in the application.
See also: [Track an
event](https://docs.talon.one/integration-api#tag/Events/operation/trackEventV2)
tags:
- Customer data
parameters:
- *ref_0
- *ref_1
- *ref_2
- *ref_3
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
type: string
/v1/audiences:
get:
operationId: getAudiences
summary: List audiences
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Get all audiences created in the account. To create an audience, use
[Create
audience](https://docs.talon.one/integration-api#tag/Audiences/operation/createAudienceV2).
tags:
- Audiences
parameters:
- *ref_0
- *ref_1
- *ref_2
- *ref_26
responses:
'200':
description: OK
schema:
type: object
required:
- data
properties:
hasMore:
type: boolean
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/Audience'
'/v1/applications/{applicationId}/profile/{integrationId}/friends':
get:
operationId: getApplicationCustomerFriends
summary: List friends referred by customer profile
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List the friends referred by the specified customer profile in this
Application.
tags:
- Referrals
parameters:
- *ref_0
- *ref_1
- *ref_2
- *ref_3
- *ref_26
- name: integrationId
in: path
required: true
type: string
description: The Integration ID of the Advocate's Profile.
responses:
'200':
description: OK
schema:
type: object
required:
- data
properties:
hasMore:
type: boolean
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/ApplicationReferee'
/v1/attributes:
post:
operationId: createAttribute
summary: Create custom attribute
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Create a _custom attribute_ in this account.
[Custom attributes](https://docs.talon.one/docs/dev/concepts/attributes)
allow you
to add data to Talon.One domain entities like campaigns, coupons,
customers and so on.
These attributes can then be given values when creating/updating these
entities, and these values can be
used in your campaign rules.
For example, you could define a `zipCode` field for customer sessions,
and add a rule to your campaign that only allows certain ZIP codes.
These attributes are shared across all Applications in your account and
are never required.
tags:
- Attributes
parameters:
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewAttribute'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/Attribute'
get:
operationId: getAttributes
summary: List custom attributes
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Return all the custom attributes for the account.
tags:
- Attributes
parameters:
- *ref_0
- *ref_1
- *ref_2
- name: entity
in: query
required: false
type: string
description: Returned attributes will be filtered by supplied entity.
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/Attribute'
'/v1/attributes/{attributeId}':
get:
operationId: getAttribute
summary: Get custom attribute
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve the specified custom attribute.
tags:
- Attributes
parameters:
- &ref_34
name: attributeId
in: path
required: true
type: integer
description: >-
The ID of the attribute. You can find the ID in the Campaign
Manager's URL when you display the details of an attribute in
**Account** > **Tools** > **Attributes**.
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Attribute'
put:
operationId: updateAttribute
summary: Update custom attribute
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Update an existing custom attribute. Once created, the only property of
a custom attribute that can be
changed is the description.
To change the `type` or `name` property of a custom attribute, create a
new attribute and
update any relevant integrations and rules to use the new attribute.
tags:
- Attributes
parameters:
- *ref_34
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewAttribute'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Attribute'
'/v1/attributes/{attributeId}/allowed_list/import':
post:
operationId: importAllowedList
summary: Import allowed values for attribute
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Upload a CSV file containing a list of [picklist
values](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes#picklist-values)
for the specified attribute.
The file should be sent as multipart data.
The import **replaces** the previous list of allowed values for this
attribute, if any.
The CSV file **must** only contain the following column:
- `item` (required): the values in your allowed list, for example a list
of SKU's.
An allowed list is limited to 500,000 items.
Example:
```text
item
CS-VG-04032021-UP-50D-10
CS-DV-04042021-UP-49D-12
CS-DG-02082021-UP-50G-07
```
tags:
- Attributes
consumes:
- multipart/form-data
parameters:
- *ref_34
- *ref_13
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Import'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/catalogs/{catalogId}/items':
get:
operationId: listCatalogItems
summary: List items in a catalog
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Return a paginated list of cart items in the given catalog.
tags:
- Catalogs
parameters:
- name: catalogId
description: >-
The ID of the catalog. You can find the ID in the Campaign Manager
in **Account** > **Tools** > **Cart item catalogs**.
in: path
required: true
type: integer
- *ref_0
- *ref_1
- *ref_26
- name: sku
in: query
description: The SKU of the item.
type: string
responses:
'200':
description: OK
schema:
type: object
required:
- data
properties:
hasMore:
type: boolean
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/CatalogItem'
/v1/additional_costs:
post:
operationId: createAdditionalCost
summary: Create additional cost
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Create an [additional
cost](https://docs.talon.one/docs/product/account/dev-tools/managing-additional-costs).
These additional costs are shared across all applications in your
account, and are never required.
tags:
- Additional costs
parameters:
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewAdditionalCost'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/AccountAdditionalCost'
get:
operationId: getAdditionalCosts
summary: List additional costs
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Returns all the defined additional costs for the account.
tags:
- Additional costs
parameters:
- *ref_0
- *ref_1
- *ref_2
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/AccountAdditionalCost'
'/v1/additional_costs/{additionalCostId}':
get:
operationId: getAdditionalCost
summary: Get additional cost
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Returns the additional cost.
tags:
- Additional costs
parameters:
- &ref_35
name: additionalCostId
description: >
The ID of the additional cost. You can find the ID the the Campaign
Manager's URL when you display the details of the cost in
**Account** > **Tools** > **Additional costs**.
in: path
required: true
type: integer
responses:
'200':
description: OK
schema:
$ref: '#/definitions/AccountAdditionalCost'
put:
operationId: updateAdditionalCost
summary: Update additional cost
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Updates an existing additional cost. Once created, the only property of
an additional cost that cannot be changed is the `name` property (or
**API name** in the Campaign Manager). This restriction is in place to
prevent accidentally breaking live integrations.
tags:
- Additional costs
parameters:
- *ref_35
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewAdditionalCost'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/AccountAdditionalCost'
/v1/webhooks:
get:
operationId: getWebhooks
summary: List webhooks
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List all webhooks.
tags:
- Webhooks
parameters:
- name: applicationIds
in: query
required: false
type: string
description: 'Filter by one or more Application IDs, separated by a comma.'
- *ref_2
- *ref_0
- *ref_1
- name: creationType
in: query
description: Filter results by creation type.
required: false
type: string
enum:
- templateWebhooks
- webhooks
- name: visibility
in: query
description: Filter results by visibility.
required: false
type: string
enum:
- visible
- hidden
- name: outgoingIntegrationsTypeId
in: query
description: Filter results by outgoing integration type ID.
required: false
type: integer
- name: title
in: query
description: >-
Filter results performing case-insensitive matching against the
webhook title.
required: false
type: string
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/WebhookWithOutgoingIntegrationDetails'
'/v1/webhooks/{webhookId}':
get:
operationId: getWebhook
summary: Get webhook
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Returns a webhook by its id.
tags:
- Webhooks
parameters:
- name: webhookId
description: >
The ID of the webhook. You can find the ID in the Campaign Manager's
URL when you display the details of the webhook in **Account** >
**Webhooks**.
in: path
required: true
type: integer
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Webhook'
/v1/webhook_activation_logs:
get:
operationId: getWebhookActivationLogs
summary: List webhook activation log entries
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Webhook activation log entries are created as soon as an integration
request
triggers a webhook effect. See the
[docs](https://docs.talon.one/docs/dev/getting-started/webhooks).
tags:
- Logs
parameters:
- *ref_0
- *ref_1
- *ref_2
- name: integrationRequestUuid
in: query
description: Filter results by integration request UUID.
type: string
- &ref_38
name: webhookId
in: query
description: Filter results by Webhook.
type: number
- &ref_39
name: applicationId
in: query
type: number
description: Filter results by Application ID.
required: false
- &ref_40
name: campaignId
in: query
description: Filter results by campaign.
type: number
- *ref_36
- *ref_37
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/WebhookActivationLogEntry'
/v1/webhook_logs:
get:
operationId: getWebhookLogs
summary: List webhook log entries
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve all webhook log entries.
tags:
- Logs
parameters:
- *ref_0
- *ref_1
- *ref_2
- *ref_30
- *ref_38
- *ref_39
- *ref_40
- name: requestUuid
in: query
description: Filter results by request UUID.
required: false
type: string
- name: createdBefore
in: query
description: >-
Filter results where request and response times to return entries
before parameter value, expected to be an RFC3339 timestamp string.
You can use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: createdAfter
in: query
description: >-
Filter results where request and response times to return entries
after parameter value, expected to be an RFC3339 timestamp string.
You can use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/WebhookLogEntry'
/v1/event_types:
get:
operationId: getEventTypes
summary: List event types
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Fetch all event type definitions for your account.
tags:
- Events
parameters:
- name: name
type: string
in: query
description: >-
Filter results to event types with the given name. This parameter
implies `includeOldVersions`.
- name: includeOldVersions
type: boolean
in: query
default: false
description: Include all versions of every event type.
- *ref_0
- *ref_1
- *ref_2
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/EventType'
'/v1/applications/{applicationId}/campaigns/{campaignId}/import_coupons':
post:
operationId: importCoupons
summary: Import coupons
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Upload a CSV file containing the coupons that should be created. The
file should be sent as multipart data.
The CSV file contains the following columns:
- `value` (required): The coupon code.
- `expirydate`: The end date in RFC3339 of the code redemption period.
- `startdate`: The start date in RFC3339 of the code redemption period.
- `recipientintegrationid`: The integration ID of the customer who
receives the coupon.
Only the customer with this integration ID can redeem the corresponding coupon code.
Learn about [coupon reservation](https://docs.talon.one/docs/product/rules/effects/using-effects#reserving-a-coupon-code).
- `limitval`: The maximum number of redemptions of this code. For
unlimited redemptions, use `0`. Defaults to `1` when not provided.
- `discountlimit`: The total discount value that the code can give. This
is typically used to represent a gift card value.
- `attributes`: A JSON object describing _custom_ coupon attribute names
and their values, enclosed with double quotation marks.
For example, if you created a [custom attribute](https://docs.talon.one/docs/dev/concepts/attributes#custom-attributes)
called `category` associated with the coupon entity, the object in the CSV file, when opened in a text editor, must be: `"{"category": "10_off"}"`.
You can use the time zone of your choice. It is converted to UTC
internally by Talon.One.
**Note:** We recommend limiting your file size to 500MB.
**Example:**
```text
"value","expirydate","startdate","recipientintegrationid","limitval","attributes","discountlimit"
COUP1,2018-07-01T04:00:00Z,2018-05-01T04:00:00Z,cust123,1,"{""Category"":
""10_off""}",2.4
```
Once imported, you can find the `batchId` in the Campaign Manager or by
using [List
coupons](#tag/Coupons/operation/getCouponsWithoutTotalCount).
tags:
- Coupons
consumes:
- multipart/form-data
parameters:
- *ref_3
- *ref_4
- *ref_13
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Import'
'/v1/applications/{applicationId}/export_coupons':
get:
operationId: exportCoupons
produces:
- application/csv
summary: Export coupons
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Download a CSV file containing the coupons that match the given
properties.
**Tip:** If the exported CSV file is too large to view, you can [split
it into multiple
files](https://www.makeuseof.com/tag/how-to-split-a-huge-csv-excel-workbook-into-seperate-files/).
The CSV file can contain the following columns:
- `accountid`: The ID of your deployment.
- `applicationid`: The ID of the Application this coupon is related to.
- `attributes`: A json object describing _custom_ referral attribute
names and their values.
- `batchid`: The ID of the batch this coupon is part of.
- `campaignid`: The ID of the campaign this coupon is related to.
- `counter`: The number of times this coupon has been redeemed.
- `created`: The creation date of the coupon code.
- `deleted`: Whether the coupon code is deleted.
- `deleted_changelogid`: The ID of the delete event in the logs.
- `discount_counter`: The amount of discount given by this coupon.
- `discount_limitval`: The maximum discount amount that can be given be
this coupon.
- `expirydate`: The end date in RFC3339 of the code redemption period.
- `id`: The internal ID of the coupon code.
- `importid`: The ID of the import job that created this coupon.
- `is_reservation_mandatory`: Whether this coupon requires a reservation
to be redeemed.
- `limits`: The limits set on this coupon.
- `limitval`: The maximum number of redemptions of this code.
- `recipientintegrationid`: The integration ID of the customer
considered as recipient of the coupon.
Only the customer with this integration ID can redeem the corresponding coupon code.
Learn about [coupon reservation](https://docs.talon.one/docs/product/rules/effects/using-effects#reserving-a-coupon-code).
- `referralid`: The ID of the referral code that triggered the creation
of this coupon (create coupon effect).
- `reservation`: Whether the coupon is reserved.
- `reservation_counter`: How many times this coupon has been reserved.
- `reservation_limitval`: The maximum of number of reservations this
coupon can have.
- `startdate`: The start date in RFC3339 of the code redemption period.
- `value`: The coupon code.
tags:
- Coupons
parameters:
- *ref_3
- *ref_40
- *ref_2
- name: value
in: query
description: >-
Filter results performing case-insensitive matching against the
coupon code. Both the code and the query are folded to remove all
non-alpha-numeric characters.
required: false
type: string
- name: createdBefore
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: createdAfter
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: valid
in: query
enum:
- expired
- validNow
- validFuture
description: >
Either "expired", "validNow", or "validFuture". The first option
matches coupons in which the expiration date is set and in the past.
The second matches coupons in which start date is null or in the
past and expiration date is null or in the future, the third matches
coupons in which start date is set and in the future.
required: false
type: string
- name: usable
in: query
enum:
- 'true'
- 'false'
description: >
Either "true" or "false". If "true", only coupons where
`usageCounter < usageLimit` will be returned, "false" will return
only coupons where `usageCounter >= usageLimit`.
type: string
- *ref_8
- name: recipientIntegrationId
in: query
description: >-
Filter results by match with a profile id specified in the coupon's
RecipientIntegrationId field.
required: false
type: string
- *ref_9
- name: exactMatch
in: query
description: >-
Filter results to an exact case-insensitive matching against the
coupon code.
required: false
type: boolean
default: false
- *ref_20
- *ref_6
- name: valuesOnly
in: query
description: >-
Filter results to only return the coupon codes (`value` column)
without the associated coupon data.
required: false
type: boolean
default: false
responses:
'200':
description: OK
schema:
type: string
format: csv
examples:
application/csv: >
id,created,campaignid,value,expirydate,startdate,attributes,applicationid,deleted,deleted_changelogid,accountid,referralid,recipientintegrationid,importid,batchid,reservation,limits,limitval,counter,discount_counter,discount_limitval
20191301,2022-04-26T11:02:38Z,3882,COUP1,2022-04-27T10:56:47Z,2022-04-26T10:56:47Z,"{""test"":
""premium""}",270,,0,1,,cust123,671,axghjfdy,,"[]",1,0,0,1.5
'/v1/applications/{applicationId}/export_referrals':
get:
operationId: exportReferrals
produces:
- application/csv
summary: Export referrals
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Download a CSV file containing the referrals that match the given
parameters.
**Tip:** If the exported CSV file is too large to view, you can [split
it into multiple
files](https://www.makeuseof.com/tag/how-to-split-a-huge-csv-excel-workbook-into-seperate-files/).
The CSV file contains the following columns:
- `code`: The referral code.
- `advocateprofileintegrationid`: The profile ID of the advocate.
- `startdate`: The start date in RFC3339 of the code redemption period.
- `expirydate`: The end date in RFC3339 of the code redemption period.
- `limitval`: The maximum number of redemptions of this code. Defaults
to `1` when left blank.
- `attributes`: A json object describing _custom_ referral attribute
names and their values.
tags:
- Referrals
parameters:
- *ref_3
- *ref_40
- name: createdBefore
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the referral creation timestamp. You
can use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: createdAfter
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the referral creation timestamp. You
can use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: valid
in: query
enum:
- expired
- validNow
- validFuture
description: >
- `expired`: Matches referrals in which the expiration date is set
and in the past.
- `validNow`: Matches referrals in which start date is null or in
the past and expiration date is null or in the future.
- `validFuture`: Matches referrals in which start date is set and in
the future.
required: false
type: string
- name: usable
in: query
enum:
- 'true'
- 'false'
description: >
- `true`, only referrals where `usageCounter < usageLimit` will be
returned.
- `false`, only referrals where `usageCounter >= usageLimit` will be
returned.
type: string
- name: batchId
in: query
description: Filter results by batches of referrals
type: string
- *ref_20
responses:
'200':
description: OK
schema:
type: string
format: csv
examples:
application/csv: >
id,created,campaignid,advocateprofileintegrationid,friendprofileintegrationid,startdate,expirydate,code,importid,attributes,batchid,counter,limitval
687,2021-09-10
09:21:06,3882,UGAV4628K,,,,3LFC-4BPC,,"{}",pimcxobg,0,9999
'/v1/applications/{applicationId}/export_effects':
get:
operationId: exportEffects
produces:
- application/csv
summary: Export triggered effects
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Download a CSV file containing the triggered effects that match the
given attributes.
**Tip:** If the exported CSV file is too large to view, you can [split
it into multiple
files](https://www.makeuseof.com/tag/how-to-split-a-huge-csv-excel-workbook-into-seperate-files/).
The generated file can contain the following columns:
- `applicationid`: The ID of the Application.
- `campaignid`: The ID of the campaign.
- `couponid`: The ID of the coupon, when applicable to the effect.
- `created`: The timestamp of the effect.
- `event_type`: The name of the event. See the
[docs](https://docs.talon.one/docs/dev/concepts/entities/events).
- `eventid`: The internal ID of the effect.
- `name`: The effect name. See the
[docs](https://docs.talon.one/docs/dev/integration-api/api-effects).
- `profileintegrationid`: The ID of the customer profile, when
applicable.
- `props`: The
[properties](https://docs.talon.one/docs/dev/integration-api/api-effects)
of the effect.
- `ruleindex`: The index of the rule.
- `rulesetid`: The ID of the rule set.
- `sessionid`: The internal ID of the session that triggered the effect.
- `profileid`: The internal ID of the customer profile.
- `sessionintegrationid`: The integration ID of the session.
- `total_revenue`: The total revenue.
- `store_integration_id`: The integration ID of the store. You choose
this ID when you create a store.
tags:
- Analytics
parameters:
- *ref_3
- *ref_40
- name: createdBefore
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: createdAfter
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the coupon creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- *ref_20
responses:
'200':
description: OK
schema:
type: string
format: csv
examples:
application/csv: >
created,name,applicationid,campaignid,rulesetid,ruleindex,sessionintegrationid,profileintegrationid,sessionid,profileid,eventid,event_type,total_revenue,props,couponid,store_id,store_integration_id
2021-06-02T21:14:16Z,rejectCoupon,270,0,0,0,newsession1,,9168,0,95797,talon_session_created,265.00,"{""value"":
""XMAS20"", ""rejectionReason"":
""CouponNotFound""}",,115,STORE-001
2021-09-01T13:04:04Z,setDiscountPerItem,270,3882,13599,0,test_flattening_2,integid_4,9707,4800,98806,talon_session_updated,405.00,"{""name"":
""10% off per item#1"", ""value"": 11.0, ""position"":
1}",,116,STORE-002
'/v1/applications/{applicationId}/export_customer_sessions':
get:
operationId: exportCustomerSessions
produces:
- application/csv
summary: Export customer sessions
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Download a CSV file containing the customer sessions that match the
request.
**Important:** Archived sessions cannot be exported. See the [retention
policy](https://docs.talon.one/docs/product/server-infrastructure-and-data-retention#data-retention-policy).
**Tip:** If the exported CSV file is too large to view, you can [split
it into multiple
files](https://www.makeuseof.com/tag/how-to-split-a-huge-csv-excel-workbook-into-seperate-files/).
- `id`: The internal ID of the session.
- `firstsession`: Whether this is a first session.
- `integrationid`: The integration ID of the session.
- `applicationid`: The ID of the Application.
- `profileid`: The internal ID of the customer profile.
- `profileintegrationid`: The integration ID of the customer profile.
- `created`: The timestamp when the session was created.
- `state`: The
[state](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions#customer-session-states)
of the session.
- `cartitems`: The cart items in the session.
- `discounts`: The discounts in the session.
- `total`: The total value of cart items and additional costs in the
session, before any discounts are applied.
- `attributes`: The attributes set in the session.
- `closedat`: Timestamp when the session was closed.
- `cancelledat`: Timestamp when the session was cancelled.
- `referral`: The referral code in the session.
- `identifiers`: The identifiers in the session.
- `additional_costs`: The [additional
costs](https://docs.talon.one/docs/product/account/dev-tools/managing-additional-costs)
in the session.
- `updated`: Timestamp of the last session update.
- `store_integration_id`: The integration ID of the store.
- `coupons`: Coupon codes in the session.
tags:
- Analytics
parameters:
- *ref_3
- name: createdBefore
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string.
required: false
type: string
format: date-time
- name: createdAfter
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string.
required: false
type: string
format: date-time
- name: profileIntegrationId
in: query
description: >-
Only return sessions for the customer that matches this customer
integration ID.
required: false
type: string
- *ref_20
- name: customerSessionState
in: query
description: Filter results by state.
required: false
enum:
- open
- closed
- partially_returned
- cancelled
type: string
responses:
'200':
description: OK
schema:
type: string
format: csv
examples:
application/csv: >
id,firstsession,integrationid,applicationid,profileid,profileintegrationid,created,state,cartitems,discounts,total,attributes,closedat,cancelledat,referral,identifiers,additional_costs,updated,store_integration_id,coupons
12327,true,62791173fbf323ee5cfd96f3,270,6111,dxclwds,2022-05-09T13:05:31Z,open,"[{""sku"":
""B00004TKVY"", ""name"": ""Gravel bike - \""Aisle of Man\"""",
""price"": 1800, ""weight"": 6, ""category"": ""gravelbikes"",
""position"": 0, ""quantity"": 1, ""attributes"": {""color"":
[""black,white""], ""material"": ""titanium""},
""returnedQuantity"": 0, ""remainingQuantity"":
1}]","{}",1850.00,"{""ShippingCost"": 50, ""PaymentMethod"":
""creditcard"", ""ShippingMethod"":
""Standard""}",0001-01-01T00:00:00Z,0001-01-01T00:00:00Z,,"null","{""ShippingCost"":
{""price"":
50}}",2022-05-09T13:13:28Z,"STORE-001","[""SORRY5QMUJRWA""]"
'/v1/applications/{applicationId}/campaigns/{campaignId}/import_referrals':
post:
operationId: importReferrals
summary: Import referrals
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Upload a CSV file containing the referrals that should be created.
The file should be sent as multipart data.
The CSV file contains the following columns:
- `code` (required): The referral code.
- `advocateprofileintegrationid` (required): The profile ID of the
advocate.
- `startdate`: The start date in RFC3339 of the code redemption period.
- `expirydate`: The end date in RFC3339 of the code redemption period.
- `limitval`: The maximum number of redemptions of this code. Defaults
to `1` when left blank.
- `attributes`: A JSON object describing _custom_ referral attribute
names and their values, enclosed with double quotation marks.
For example, if you created a [custom attribute](https://docs.talon.one/docs/dev/concepts/attributes#custom-attributes)
called `category` associated with the referral entity, the object in the CSV file, when opened in a text editor, must be: `"{"category": "10_off"}"`.
You can use the time zone of your choice. It is converted to UTC
internally by Talon.One.
**Important:** When you import a CSV file with referrals, a [customer
profile](https://docs.talon.one/docs/dev/concepts/entities/customer-profiles)
is **not** automatically created for each `advocateprofileintegrationid`
column value. Use the [Update customer
profile](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/updateCustomerProfileV2)
endpoint or the [Update multiple customer
profiles](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/updateCustomerProfilesV2)
endpoint to create the customer profiles.
**Note:** We recommend limiting your file size to 500MB.
**Example:**
```text
code,startdate,expirydate,advocateprofileintegrationid,limitval,attributes
REFERRAL_CODE1,2020-11-10T23:00:00Z,2021-11-11T23:00:00Z,integid_4,1,"{""my_attribute"":
""10_off""}"
REFERRAL_CODE2,2020-11-10T23:00:00Z,2021-11-11T23:00:00Z,integid1,1,"{""my_attribute"":
""20_off""}"
```
tags:
- Referrals
consumes:
- multipart/form-data
parameters:
- *ref_3
- *ref_4
- *ref_13
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Import'
/v1/users:
get:
operationId: getUsers
summary: List users in account
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve all users in your account.
tags:
- Accounts and users
parameters:
- *ref_0
- *ref_1
- *ref_2
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/User'
'/v1/users/{userId}':
get:
operationId: getUser
summary: Get user
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve the data (including an invitation code) for a user. Non-admin
users can only get their own profile.
tags:
- Accounts and users
parameters:
- name: userId
in: path
description: The ID of the user.
required: true
type: integer
responses:
'200':
description: OK
schema:
$ref: '#/definitions/User'
/v1/changes:
get:
operationId: getChanges
summary: Get audit logs for an account
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Retrieve the audit logs displayed in **Accounts > Audit logs**.
tags:
- Logs
parameters:
- *ref_0
- *ref_1
- *ref_2
- *ref_39
- name: entityPath
in: query
description: >-
Filter results on a case insensitive matching of the url path of the
entity
type: string
required: false
- *ref_41
- name: createdBefore
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the change creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- name: createdAfter
in: query
description: >-
Filter results comparing the parameter value, expected to be an
RFC3339 timestamp string, to the change creation timestamp. You can
use any timezone. Talon.One will convert to UTC internally.
required: false
type: string
format: date-time
- *ref_26
- name: managementKeyId
in: query
description: Filter results that match the given management key ID.
required: false
type: integer
- name: includeOld
type: boolean
in: query
description: >-
When this flag is set to false, the state without the change will
not be returned. The default value is true.
responses:
'200':
description: OK
schema:
type: object
required:
- data
properties:
totalResultSize:
type: integer
example: 1
hasMore:
type: boolean
data:
type: array
items:
$ref: '#/definitions/Change'
/v1/password_recovery_emails:
post:
operationId: createPasswordRecoveryEmail
summary: Request a password reset
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Send an email with a password recovery link to the email address of an
existing account.
**Note:** The password recovery link expires 30 minutes after this
endpoint is triggered.
tags:
- Accounts and users
parameters:
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewPasswordEmail'
responses:
'204':
description: Created
schema:
$ref: '#/definitions/NewPasswordEmail'
/v1/reset_password:
post:
operationId: resetPassword
summary: Reset password
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Consumes the supplied password reset token and updates the password for
the associated account.
tags:
- Accounts and users
parameters:
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewPassword'
responses:
'204':
description: Created
schema:
$ref: '#/definitions/NewPassword'
'/v1/accounts/{accountId}':
get:
operationId: getAccount
summary: Get account details
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Return the details of your companies Talon.One account.
tags:
- Accounts and users
parameters:
- &ref_42
name: accountId
in: path
description: >
The identifier of the account. Retrieve it via the
[List users in
account](https://docs.talon.one/management-api#operation/getUsers)
endpoint in the `accountId`
property.
required: true
type: integer
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Account'
'/v1/accounts/{accountId}/analytics':
get:
operationId: getAccountAnalytics
summary: Get account analytics
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Return the analytics of your Talon.One account.
tags:
- Accounts and users
parameters:
- *ref_42
responses:
'200':
description: OK
schema:
$ref: '#/definitions/AccountAnalytics'
/v1/sessions:
post:
operationId: createSession
summary: Create session
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Create a session to use the Management API endpoints.
Use the value of the `token` property provided in the response as bearer
token in other API calls.
A token is valid for 3 months. In accordance with best pratices, use
your generated token
for all your API requests. Do **not** regenerate a token for each
request.
This endpoint has a rate limit of 3 to 6 requests per second per
account, depending on your setup.
Granular API key
Instead of using a session, you can also use the
Management API key feature
in the Campaign Manager to decide which endpoints can be used with a given key.
tags:
- Sessions
parameters:
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/LoginParams'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/Session'
delete:
operationId: destroySession
summary: Destroy session
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Destroys the session.
tags:
- Sessions
parameters: []
responses:
'204':
description: No Content
/v1/exports:
get:
operationId: getExports
summary: Get exports
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List all past exports
tags:
- Logs
parameters:
- *ref_0
- *ref_1
- *ref_39
- name: campaignId
type: integer
in: query
description: Filter by the campaign ID on which the limit counters are used.
required: false
- name: entity
in: query
type: string
enum:
- Coupon
- Referral
- Effect
- CustomerSession
- LoyaltyLedger
- LoyaltyLedgerLog
- Collection
- AudienceMembership
required: false
description: The name of the entity type that was exported.
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/Export'
/v1/roles:
get:
operationId: getAllRoles
summary: List roles
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List all roles.
tags:
- Roles
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/Role'
'/v1/roles/{roleId}':
get:
operationId: getRole
summary: Get role
description: >
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Get the details of a specific role. To see all the roles, use [List
roles](#operation/getAllRoles).
tags:
- Roles
parameters:
- name: roleId
in: path
description: 'The ID of role. '
required: true
type: integer
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Role'
'/v1/applications/{applicationId}/stores':
get:
operationId: listStores
summary: List stores
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
List all stores for a specific Application.
tags:
- Stores
parameters:
- *ref_3
- *ref_0
- *ref_1
- *ref_2
- *ref_26
- *ref_40
- name: name
description: The name of the store.
required: false
in: query
type: string
- name: integrationId
description: The integration ID of the store.
required: false
in: query
type: string
responses:
'200':
description: OK
schema:
type: object
required:
- data
properties:
hasMore:
type: boolean
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/Store'
post:
operationId: createStore
summary: Create store
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Create a new store in a specific Application.
tags:
- Stores
parameters:
- *ref_3
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewStore'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/Store'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponse'
'409':
description: >-
Conflict. A store with this integration ID already exists for this
application.
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/applications/{applicationId}/stores/{storeId}':
get:
operationId: getStore
summary: Get store
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Get store details for a specific store ID.
tags:
- Stores
parameters:
- *ref_3
- &ref_43
name: storeId
required: true
in: path
type: string
description: >
The ID of the store.
You can get this ID with the [List
stores](#tag/Stores/operation/listStores) endpoint.
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Store'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
put:
operationId: updateStore
summary: Update store
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Update store details for a specific store ID.
tags:
- Stores
parameters:
- *ref_3
- *ref_43
- name: body
description: body
required: true
in: body
schema:
$ref: '#/definitions/NewStore'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Store'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
delete:
operationId: deleteStore
summary: Delete store
description: >-
Management API endpoints are not
meant to be used in real-time integrations that directly serve your end
users. Rate limit: 3 requests per second.
Delete the specified store.
tags:
- Stores
parameters:
- *ref_3
- *ref_43
responses:
'204':
description: No Content
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
definitions:
ErrorResponse:
type: object
required:
- message
properties:
message:
type: string
description: A message describing the error.
errors:
type: array
description: An array of individual problems encountered during the request.
items:
$ref: '#/definitions/APIError'
ErrorResponseWithStatus:
type: object
properties:
message:
type: string
errors:
type: array
description: An array of individual problems encountered during the request.
items:
$ref: '#/definitions/APIError'
StatusCode:
type: integer
description: The error code
APIError:
type: object
required:
- source
- title
properties:
title:
type: string
description: Short description of the problem.
details:
type: string
description: Longer description of this specific instance of the problem.
source:
$ref: '#/definitions/ErrorSource'
FeatureFlag:
type: object
properties:
name:
type: string
description: The name of the feature flag.
example: canCreateCampaignFromTemplate
value:
type: string
description: The value of the feature flag.
example: 'true'
created:
type: string
format: date-time
description: The time this entity was last created.
example: '2021-09-22T12:24:14.956203Z'
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: 2021-09-25T10:34:12.956Z
required:
- name
- value
ErrorSource:
type: object
description: >
The source of the current error, exactly one of `pointer`, `parameter` or
`line` will be defined.
properties:
pointer:
type: string
description: Pointer to the path in the payload that caused this error.
parameter:
type: string
description: Query parameter that caused this error.
line:
type: string
description: >-
Line number in uploaded multipart file that caused this error. 'N/A'
if unknown.
resource:
type: string
description: Pointer to the resource that caused this error.
IdentifiableEntity:
type: object
required:
- id
properties:
id:
type: integer
description: >-
Unique ID for this entity. Not to be confused with the Integration ID,
which is set by your integration layer and used in most endpoints.
example: 6
Entity:
type: object
required:
- id
- created
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
EntityWithTalangVisibleID:
type: object
required:
- id
- created
properties:
id:
type: integer
description: Unique ID for this entity.
example: 4
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
MutableEntity:
type: object
required:
- modified
properties:
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
AccountEntity:
type: object
required:
- accountId
properties:
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
UserEntity:
type: object
required:
- userId
properties:
userId:
type: integer
description: The ID of the user associated with this entity.
example: 388
EmailEntity:
type: object
required:
- email
properties:
email:
type: string
format: email
example: john.doe@example.com
description: The email address associated with your account.
ApplicationEntity:
type: object
required:
- applicationId
properties:
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
LoyaltyProgramEntity:
type: object
required:
- programID
properties:
programID:
type: integer
description: The ID of the loyalty program that owns this entity.
example: 125
CampaignGroupEntity:
type: object
properties:
campaignGroups:
type: array
description: The IDs of the campaign groups that own this entity.
items:
type: integer
MultiApplicationEntity:
type: object
required:
- applicationIds
properties:
applicationIds:
type: array
minItems: 1
description: The IDs of the Applications that are related to this entity.
items:
type: integer
CampaignEntity:
type: object
required:
- campaignId
properties:
campaignId:
type: integer
title: Campaign ID
description: The ID of the campaign that owns this entity.
example: 211
ApplicationSessionEntity:
type: object
required:
- sessionId
properties:
sessionId:
type: integer
description: >-
The globally unique Talon.One ID of the session where this entity was
created.
example: 2
ApplicationCustomerEntity:
type: object
properties:
profileId:
type: integer
description: >-
The globally unique Talon.One ID of the customer that created this
entity.
example: 138
ApplicationStoreEntity:
type: object
properties:
storeId:
type: integer
description: The ID of the store.
IntegrationEntity:
type: object
required:
- integrationId
- created
properties:
integrationId:
type: string
format: string
example: URNGV8294NV
maxLength: 1000
description: The integration ID set by your integration layer.
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-02-07T08:15:22Z'
IntegrationProfileEntity:
type: object
properties:
profileId:
type: string
description: >
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`.
example: URNGV8294NV
IntegrationStoreEntity:
type: object
properties:
storeIntegrationId:
type: string
minLength: 1
maxLength: 1000
description: >-
The integration ID of the store. You choose this ID when you create a
store.
example: STORE-001
CouponValue:
type: object
properties:
value:
type: string
title: Coupon Code
description: The coupon code.
minLength: 4
example: XMAS-20-2021
CouponConstraints:
type: object
properties:
usageLimit:
type: integer
minimum: 0
maximum: 999999
example: 100
description: >
The number of times the coupon code can be redeemed. `0` means
unlimited redemptions but any campaign usage limits will still apply.
discountLimit:
type: number
minimum: 0
maximum: 999999
example: 30
description: >
The total discount value that the code can give. Typically used to
represent a gift card value.
reservationLimit:
type: integer
minimum: 0
maximum: 999999
example: 45
description: |
The number of reservations that can be made with this coupon code.
startDate:
type: string
format: date-time
example: '2020-01-24T14:15:22Z'
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
example: '2023-08-24T14:15:22Z'
minimum: 0
description: >-
Expiration date of the coupon. Coupon never expires if this is
omitted, zero, or negative.
CodeGeneratorSettings:
type: object
properties:
validCharacters:
type: array
description: |
List of characters used to generate the random parts of a code.
example:
- 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'
items:
type: string
couponPattern:
type: string
description: >
The pattern used to generate coupon codes. The character `#` is a
placeholder and is replaced by a random character from the
`validCharacters` set.
maxLength: 100
minLength: 3
example: 'SUMMER-####-####'
additionalProperties: false
required:
- couponPattern
- validCharacters
Session:
type: object
properties:
userId:
type: integer
description: The ID of the user of this session.
example: 109
token:
type: string
description: The token to use as a bearer token to query Management API endpoints.
example: dy_Fa_lQ4iDAnqldJFvVEmnsN8xDTxej19l0LZDBJhQ
created:
type: string
format: date-time
description: Unix timestamp indicating when the session was first created.
example: '2021-07-20T22:00:00Z'
required:
- userId
- token
- created
OneTimeCode:
type: object
properties:
userId:
type: integer
description: The ID of the user.
example: 109
accountId:
type: integer
description: The ID of the account.
example: 31
token:
type: string
description: >-
The two-factor authentication token created during sign-in. This token
is used to ensure that the correct user is trying to sign in with a
given one-time security code.
example: dy_Fa_lQ4iDAnqldJFvV
code:
type: string
description: The one-time security code used for signing in.
example: '552917'
required:
- userId
- accountId
- token
LoginParams:
type: object
description: ''
required:
- email
- password
properties:
email:
type: string
format: email
example: john.doe@example.com
description: The email address associated with your account.
password:
type: string
description: The password for your account.
example: admin123456
additionalProperties: false
AttributesMandatory:
type: object
description: Arbitrary settings associated with attributes.
properties:
campaigns:
type: array
items:
type: string
description: List of mandatory attributes for campaigns.
coupons:
type: array
items:
type: string
description: List of mandatory attributes for campaigns.
AttributesSettings:
type: object
description: Arbitrary settings associated with attributes.
properties:
mandatory:
$ref: '#/definitions/AttributesMandatory'
UpdateApplication:
type: object
properties:
name:
type: string
description: The name of this application.
minLength: 1
example: My Application
description:
type: string
description: A longer description of the application.
example: A test Application
timezone:
type: string
description: A string containing an IANA timezone descriptor.
minLength: 1
example: Europe/Berlin
currency:
type: string
description: The default currency for new customer sessions.
minLength: 1
example: EUR
caseSensitivity:
type: string
enum:
- sensitive
- insensitive-uppercase
- insensitive-lowercase
description: >-
The case sensitivity behavior to check coupon codes in the campaigns
of this Application.
example: sensitive
attributes:
type: object
description: Arbitrary properties associated with this campaign.
additionalProperties: true
limits:
type: array
description: Default limits for campaigns created in this application.
items:
$ref: '#/definitions/LimitConfig'
defaultDiscountScope:
type: string
example: sessionTotal
description: >
The default scope to apply `setDiscount` effects on if no scope was
provided with the effect.
enum:
- sessionTotal
- cartItems
- additionalCosts
enableCascadingDiscounts:
type: boolean
description: Indicates if discounts should cascade for this Application.
example: true
enableFlattenedCartItems:
type: boolean
example: true
description: >
Indicates if cart items of quantity larger than one should be
separated into different items of quantity one.
attributesSettings:
$ref: '#/definitions/AttributesSettings'
sandbox:
type: boolean
description: Indicates if this is a live or sandbox Application.
example: true
enablePartialDiscounts:
type: boolean
description: Indicates if this Application supports partial discounts.
example: false
defaultDiscountAdditionalCostPerItemScope:
type: string
description: >
The default scope to apply `setDiscountPerItem` effects on if no scope
was provided with the effect.
example: price
enum:
- price
- itemTotal
- additionalCosts
defaultEvaluationGroupId:
type: integer
description: >-
The ID of the default campaign evaluation group to which new campaigns
will be added unless a different group is selected when creating the
campaign.
example: 3
required:
- name
- timezone
- currency
NewApplication:
type: object
additionalProperties: false
properties:
name:
type: string
description: The name of this application.
minLength: 1
example: My Application
description:
type: string
description: A longer description of the application.
example: A test Application
timezone:
type: string
description: A string containing an IANA timezone descriptor.
minLength: 1
example: Europe/Berlin
currency:
type: string
description: The default currency for new customer sessions.
minLength: 1
example: EUR
caseSensitivity:
type: string
enum:
- sensitive
- insensitive-uppercase
- insensitive-lowercase
description: >-
The case sensitivity behavior to check coupon codes in the campaigns
of this Application.
example: sensitive
attributes:
type: object
description: Arbitrary properties associated with this campaign.
additionalProperties: true
limits:
type: array
description: Default limits for campaigns created in this application.
items:
$ref: '#/definitions/LimitConfig'
defaultDiscountScope:
type: string
description: >
The default scope to apply `setDiscount` effects on if no scope was
provided with the effect.
enum:
- sessionTotal
- cartItems
- additionalCosts
enableCascadingDiscounts:
type: boolean
description: Indicates if discounts should cascade for this Application.
enableFlattenedCartItems:
type: boolean
description: >
Indicates if cart items of quantity larger than one should be
separated into different items of quantity one.
attributesSettings:
$ref: '#/definitions/AttributesSettings'
sandbox:
type: boolean
description: Indicates if this is a live or sandbox Application.
enablePartialDiscounts:
type: boolean
description: Indicates if this Application supports partial discounts.
example: false
defaultDiscountAdditionalCostPerItemScope:
type: string
description: >
The default scope to apply `setDiscountPerItem` effects on if no scope
was provided with the effect.
enum:
- price
- itemTotal
- additionalCosts
key:
type: string
description: >-
Hex key for HMAC-signing API calls as coming from this application (16
hex digits).
pattern: '^[a-fA-F0-9]{16}$'
required:
- name
- timezone
- currency
Application:
type: object
description: ''
required:
- id
- created
- modified
- accountId
- name
- timezone
- currency
- loyaltyPrograms
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
name:
type: string
description: The name of this application.
minLength: 1
example: My Application
description:
type: string
description: A longer description of the application.
example: A test Application
timezone:
type: string
description: A string containing an IANA timezone descriptor.
minLength: 1
example: Europe/Berlin
currency:
type: string
description: The default currency for new customer sessions.
minLength: 1
example: EUR
caseSensitivity:
type: string
enum:
- sensitive
- insensitive-uppercase
- insensitive-lowercase
description: >-
The case sensitivity behavior to check coupon codes in the campaigns
of this Application.
example: sensitive
attributes:
type: object
description: Arbitrary properties associated with this campaign.
additionalProperties: true
limits:
type: array
description: Default limits for campaigns created in this application.
items:
$ref: '#/definitions/LimitConfig'
defaultDiscountScope:
type: string
example: sessionTotal
description: >
The default scope to apply `setDiscount` effects on if no scope was
provided with the effect.
enum:
- sessionTotal
- cartItems
- additionalCosts
enableCascadingDiscounts:
type: boolean
description: Indicates if discounts should cascade for this Application.
example: true
enableFlattenedCartItems:
type: boolean
example: true
description: >
Indicates if cart items of quantity larger than one should be
separated into different items of quantity one.
attributesSettings:
$ref: '#/definitions/AttributesSettings'
sandbox:
type: boolean
description: Indicates if this is a live or sandbox Application.
example: true
enablePartialDiscounts:
type: boolean
description: Indicates if this Application supports partial discounts.
example: false
defaultDiscountAdditionalCostPerItemScope:
type: string
description: >
The default scope to apply `setDiscountPerItem` effects on if no scope
was provided with the effect.
example: price
enum:
- price
- itemTotal
- additionalCosts
defaultEvaluationGroupId:
type: integer
description: >-
The ID of the default campaign evaluation group to which new campaigns
will be added unless a different group is selected when creating the
campaign.
example: 3
loyaltyPrograms:
type: array
description: >-
An array containing all the loyalty programs to which this application
is subscribed.
items:
$ref: '#/definitions/LoyaltyProgram'
additionalProperties: false
NewCampaignGroup:
type: object
properties:
name:
type: string
description: The name of this campaign access group.
minLength: 1
description:
type: string
description: A longer description of the campaign access group.
example: My campaign access group.
subscribedApplicationsIds:
type: array
description: >-
A list of IDs of the Applications that this campaign access group is
enabled for.
items:
type: integer
example:
- 1
- 2
- 3
campaignIds:
type: array
description: >-
A list of IDs of the campaigns that are part of the campaign access
group.
items:
type: integer
example:
- 4
- 6
- 8
required:
- name
CampaignGroup:
type: object
description: ''
required:
- id
- created
- modified
- accountId
- name
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
name:
type: string
description: The name of this campaign access group.
minLength: 1
description:
type: string
description: A longer description of the campaign access group.
example: My campaign access group.
subscribedApplicationsIds:
type: array
description: >-
A list of IDs of the Applications that this campaign access group is
enabled for.
items:
type: integer
example:
- 1
- 2
- 3
campaignIds:
type: array
description: >-
A list of IDs of the campaigns that are part of the campaign access
group.
items:
type: integer
example:
- 4
- 6
- 8
additionalProperties: false
UpdateCampaignGroup:
type: object
description: ''
required:
- name
properties:
name:
type: string
description: The name of this campaign access group.
minLength: 1
description:
type: string
description: A longer description of the campaign access group.
example: My campaign access group.
subscribedApplicationsIds:
type: array
description: >-
A list of IDs of the Applications that this campaign access group is
enabled for.
items:
type: integer
example:
- 1
- 2
- 3
campaignIds:
type: array
description: >-
A list of IDs of the campaigns that are part of the campaign access
group.
items:
type: integer
example:
- 4
- 6
- 8
additionalProperties: false
NewCampaign:
type: object
description: ''
required:
- name
- state
- tags
- limits
- features
properties:
name:
type: string
title: Campaign Name
description: A user-facing name for this campaign.
minLength: 1
example: Summer promotions
description:
type: string
title: Campaign Description
description: A detailed description of the campaign.
example: Campaign for all summer 2021 promotions
startTime:
type: string
format: date-time
description: Timestamp when the campaign will become active.
example: '2021-07-20T22:00:00Z'
endTime:
type: string
format: date-time
description: Timestamp when the campaign will become inactive.
example: '2021-09-22T22:00:00Z'
attributes:
type: object
description: Arbitrary properties associated with this campaign.
additionalProperties: true
state:
type: string
enum:
- enabled
- disabled
- archived
default: enabled
example: enabled
description: |
A disabled or archived campaign is not evaluated for rules or coupons.
activeRulesetId:
type: integer
description: >
[ID of
Ruleset](https://docs.talon.one/management-api#operation/getRulesets)
this
campaign applies on customer session evaluation.
example: 6
tags:
type: array
description: A list of tags for the campaign.
example:
- summer
maxItems: 50
items:
type: string
minLength: 1
maxLength: 50
features:
type: array
description: The features enabled in this campaign.
example:
- coupons
- referrals
items:
type: string
enum:
- coupons
- referrals
- loyalty
- giveaways
- strikethrough
couponSettings:
$ref: '#/definitions/CodeGeneratorSettings'
referralSettings:
$ref: '#/definitions/CodeGeneratorSettings'
limits:
type: array
description: >
The set of [budget
limits](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets)
for this campaign.
items:
$ref: '#/definitions/LimitConfig'
campaignGroups:
type: array
description: >
The IDs of the [campaign
groups](https://docs.talon.one/docs/product/account/managing-campaign-groups)
this campaign belongs to.
example:
- 1
- 3
items:
type: integer
evaluationGroupId:
type: integer
title: Evaluation Group ID
example: 2
description: The ID of the campaign evaluation group the campaign belongs to.
type:
type: string
title: Type
enum:
- cartItem
- advanced
default: advanced
example: advanced
description: |
The campaign type. Possible type values:
- `cartItem`: Type of campaign that can apply effects only to cart items.
- `advanced`: Type of campaign that can apply effects to customer sessions and cart items.
linkedStoreIds:
type: array
description: >
A list of store IDs that you want to link to the campaign.
**Note:** Campaigns with linked store IDs will only be evaluated when
there is a
[customer session
update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
that references a linked store.
items:
type: integer
example:
- 1
- 2
- 3
additionalProperties: false
UpdateCampaign:
type: object
properties:
name:
type: string
title: Campaign Name
description: A user-facing name for this campaign.
minLength: 1
example: Summer promotions
description:
type: string
title: Campaign Description
description: A detailed description of the campaign.
example: Campaign for all summer 2021 promotions
startTime:
type: string
format: date-time
description: Timestamp when the campaign will become active.
example: '2021-07-20T22:00:00Z'
endTime:
type: string
format: date-time
description: Timestamp when the campaign will become inactive.
example: '2021-10-01T02:00:00Z'
attributes:
type: object
description: Arbitrary properties associated with this campaign.
additionalProperties: true
example:
myattribute: 20
state:
type: string
enum:
- enabled
- disabled
- archived
default: enabled
example: disabled
description: |
A disabled or archived campaign is not evaluated for rules or coupons.
activeRulesetId:
type: integer
description: >
[ID of
Ruleset](https://docs.talon.one/management-api#operation/getRulesets)
this
campaign applies on customer session evaluation.
example: 2
tags:
type: array
description: A list of tags for the campaign.
maxItems: 50
example:
- Summer
- Shoes
items:
type: string
minLength: 1
maxLength: 50
features:
type: array
description: A list of features for the campaign.
items:
type: string
enum:
- coupons
- referrals
- loyalty
- giveaways
- strikethrough
example:
- coupons
- loyalty
couponSettings:
$ref: '#/definitions/CodeGeneratorSettings'
referralSettings:
$ref: '#/definitions/CodeGeneratorSettings'
limits:
type: array
description: The set of limits that will operate for this campaign.
items:
$ref: '#/definitions/LimitConfig'
campaignGroups:
type: array
description: >
The IDs of the [campaign
groups](https://docs.talon.one/docs/product/account/account-settings/managing-campaign-groups)
this campaign belongs to.
example:
- 1
- 3
items:
type: integer
evaluationGroupId:
type: integer
example: 2
description: The ID of the campaign evaluation group the campaign belongs to.
type:
type: string
enum:
- cartItem
- advanced
default: advanced
example: advanced
description: |
The campaign type. Possible type values:
- `cartItem`: Type of campaign that can apply effects only to cart items.
- `advanced`: Type of campaign that can apply effects to customer sessions and cart items.
linkedStoreIds:
type: array
description: >
A list of store IDs that you want to link to the campaign.
**Note:** Campaigns with linked store IDs will only be evaluated when
there is a
[customer session
update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
that references a linked store.
items:
type: integer
example:
- 1
- 2
- 3
required:
- name
- tags
- limits
- features
BaseCampaign:
type: object
properties:
name:
type: string
title: Campaign Name
description: A user-facing name for this campaign.
minLength: 1
example: Summer promotions
description:
type: string
title: Campaign Description
description: A detailed description of the campaign.
example: Campaign for all summer 2021 promotions
startTime:
type: string
format: date-time
description: Timestamp when the campaign will become active.
example: '2021-07-20T22:00:00Z'
endTime:
type: string
format: date-time
description: Timestamp when the campaign will become inactive.
example: '2021-09-22T22:00:00Z'
attributes:
type: object
description: Arbitrary properties associated with this campaign.
additionalProperties: true
state:
type: string
enum:
- enabled
- disabled
- archived
default: enabled
example: enabled
description: |
A disabled or archived campaign is not evaluated for rules or coupons.
activeRulesetId:
type: integer
description: >
[ID of
Ruleset](https://docs.talon.one/management-api#operation/getRulesets)
this
campaign applies on customer session evaluation.
example: 6
tags:
type: array
description: A list of tags for the campaign.
example:
- summer
maxItems: 50
items:
type: string
minLength: 1
maxLength: 50
features:
type: array
description: The features enabled in this campaign.
example:
- coupons
- referrals
items:
type: string
enum:
- coupons
- referrals
- loyalty
- giveaways
- strikethrough
couponSettings:
$ref: '#/definitions/CodeGeneratorSettings'
referralSettings:
$ref: '#/definitions/CodeGeneratorSettings'
limits:
type: array
description: >
The set of [budget
limits](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets)
for this campaign.
items:
$ref: '#/definitions/LimitConfig'
campaignGroups:
type: array
description: >
The IDs of the [campaign
groups](https://docs.talon.one/docs/product/account/managing-campaign-groups)
this campaign belongs to.
example:
- 1
- 3
items:
type: integer
evaluationGroupId:
type: integer
title: Evaluation Group ID
example: 2
description: The ID of the campaign evaluation group the campaign belongs to.
type:
type: string
title: Type
enum:
- cartItem
- advanced
default: advanced
example: advanced
description: |
The campaign type. Possible type values:
- `cartItem`: Type of campaign that can apply effects only to cart items.
- `advanced`: Type of campaign that can apply effects to customer sessions and cart items.
linkedStoreIds:
type: array
description: >
A list of store IDs that you want to link to the campaign.
**Note:** Campaigns with linked store IDs will only be evaluated when
there is a
[customer session
update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
that references a linked store.
items:
type: integer
example:
- 1
- 2
- 3
required:
- name
- state
- tags
- limits
- features
BaseCampaignForNotification:
type: object
properties:
name:
type: string
title: Campaign Name
description: A user-facing name for this campaign.
minLength: 1
example: Summer promotions
description:
type: string
title: Campaign Description
description: A detailed description of the campaign.
example: Campaign for all summer 2021 promotions
startTime:
type: string
format: date-time
description: Timestamp when the campaign will become active.
example: '2021-07-20T22:00:00Z'
endTime:
type: string
format: date-time
description: Timestamp when the campaign will become inactive.
example: '2021-09-22T22:00:00Z'
attributes:
type: object
description: Arbitrary properties associated with this campaign.
additionalProperties: true
state:
type: string
enum:
- enabled
- disabled
- archived
- draft
- scheduled
- running
- expired
default: enabled
example: enabled
description: |
A disabled or archived campaign is not evaluated for rules or coupons.
activeRulesetId:
type: integer
description: >
[ID of
Ruleset](https://docs.talon.one/management-api#operation/getRulesets)
this
campaign applies on customer session evaluation.
example: 6
tags:
type: array
description: A list of tags for the campaign.
example:
- summer
maxItems: 50
items:
type: string
minLength: 1
maxLength: 50
features:
type: array
description: The features enabled in this campaign.
example:
- coupons
- referrals
items:
type: string
enum:
- coupons
- referrals
- loyalty
- giveaways
- strikethrough
couponSettings:
$ref: '#/definitions/CodeGeneratorSettings'
referralSettings:
$ref: '#/definitions/CodeGeneratorSettings'
limits:
type: array
description: >
The set of [budget
limits](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets)
for this campaign.
items:
$ref: '#/definitions/LimitConfig'
campaignGroups:
type: array
description: >
The IDs of the [campaign
groups](https://docs.talon.one/docs/product/account/managing-campaign-groups)
this campaign belongs to.
example:
- 1
- 3
items:
type: integer
evaluationGroupId:
type: integer
example: 2
description: The ID of the campaign evaluation group the campaign belongs to.
type:
type: string
enum:
- cartItem
- advanced
default: advanced
example: advanced
description: |
The campaign type. Possible type values:
- `cartItem`: Type of campaign that can apply effects only to cart items.
- `advanced`: Type of campaign that can apply effects to customer sessions and cart items.
linkedStoreIds:
type: array
description: >
A list of store IDs that are linked to the campaign.
**Note:** Campaigns with linked store IDs will only be evaluated when
there is a
[customer session
update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
that references a linked store.
items:
type: integer
example:
- 1
- 2
- 3
required:
- name
- state
- tags
- limits
- features
Campaign:
type: object
description: ''
required:
- id
- created
- applicationId
- userId
- name
- state
- tags
- limits
- features
- description
- type
- budgets
properties:
id:
type: integer
description: Unique ID for this entity.
example: 4
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
userId:
type: integer
description: The ID of the user associated with this entity.
example: 388
name:
type: string
title: Campaign Name
description: A user-facing name for this campaign.
minLength: 1
example: Summer promotions
description:
type: string
title: Campaign Description
description: A detailed description of the campaign.
example: Campaign for all summer 2021 promotions
startTime:
type: string
format: date-time
description: Timestamp when the campaign will become active.
example: '2021-07-20T22:00:00Z'
endTime:
type: string
format: date-time
description: Timestamp when the campaign will become inactive.
example: '2021-09-22T22:00:00Z'
attributes:
type: object
description: Arbitrary properties associated with this campaign.
additionalProperties: true
state:
type: string
enum:
- enabled
- disabled
- archived
default: enabled
example: enabled
description: |
A disabled or archived campaign is not evaluated for rules or coupons.
activeRulesetId:
type: integer
description: >
[ID of
Ruleset](https://docs.talon.one/management-api#operation/getRulesets)
this
campaign applies on customer session evaluation.
example: 6
tags:
type: array
description: A list of tags for the campaign.
example:
- summer
maxItems: 50
items:
type: string
minLength: 1
maxLength: 50
features:
type: array
description: The features enabled in this campaign.
example:
- coupons
- referrals
items:
type: string
enum:
- coupons
- referrals
- loyalty
- giveaways
- strikethrough
couponSettings:
$ref: '#/definitions/CodeGeneratorSettings'
referralSettings:
$ref: '#/definitions/CodeGeneratorSettings'
limits:
type: array
description: >
The set of [budget
limits](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets)
for this campaign.
items:
$ref: '#/definitions/LimitConfig'
campaignGroups:
type: array
description: >
The IDs of the [campaign
groups](https://docs.talon.one/docs/product/account/managing-campaign-groups)
this campaign belongs to.
example:
- 1
- 3
items:
type: integer
evaluationGroupId:
type: integer
title: Evaluation Group ID
example: 2
description: The ID of the campaign evaluation group the campaign belongs to.
type:
type: string
title: Type
enum:
- cartItem
- advanced
default: advanced
example: advanced
description: |
The campaign type. Possible type values:
- `cartItem`: Type of campaign that can apply effects only to cart items.
- `advanced`: Type of campaign that can apply effects to customer sessions and cart items.
linkedStoreIds:
type: array
description: >
A list of store IDs that you want to link to the campaign.
**Note:** Campaigns with linked store IDs will only be evaluated when
there is a
[customer session
update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
that references a linked store.
items:
type: integer
example:
- 1
- 2
- 3
budgets:
type: array
items:
$ref: '#/definitions/CampaignBudget'
description: >
A list of all the budgets that are defined by this campaign and their
usage.
**Note:** Budgets that are not defined do not appear in this list and
their usage is
not counted until they are defined.
couponRedemptionCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Number of coupons redeemed in the campaign.
example: 163
referralRedemptionCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Number of referral codes redeemed in the campaign.
example: 3
discountCount:
type: number
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total amount of discounts redeemed in the campaign.
example: 288
discountEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of times discounts were redeemed in this campaign.
example: 343
couponCreationCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of coupons created by rules in this campaign.
example: 16
customEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of custom effects triggered by rules in this campaign.
example: 0
referralCreationCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of referrals created by rules in this campaign.
example: 8
addFreeItemEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of times the [add free item
effect](https://docs.talon.one/docs/dev/integration-api/api-effects#addfreeitem)
can be triggered in this campaign.
example: 0
awardedGiveawaysCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of giveaways awarded by rules in this campaign.
example: 9
createdLoyaltyPointsCount:
type: number
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty points created by rules in this campaign.
example: 9
createdLoyaltyPointsEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty point creation effects triggered by rules in
this campaign.
example: 2
redeemedLoyaltyPointsCount:
type: number
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty points redeemed by rules in this campaign.
example: 8
redeemedLoyaltyPointsEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty point redemption effects triggered by rules in
this campaign.
example: 9
callApiEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of webhooks triggered by rules in this campaign.
example: 0
reservecouponEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of reserve coupon effects triggered by rules in this
campaign.
example: 9
lastActivity:
type: string
format: date-time
example: '2022-11-10T23:00:00Z'
description: Timestamp of the most recent event received by this campaign.
updated:
type: string
format: date-time
example: '2022-10-97T35:00:00Z'
description: >
Timestamp of the most recent update to the campaign's property.
Updates to external entities used in this campaign
are **not** registered by this property, such as collection or coupon
updates.
createdBy:
type: string
description: Name of the user who created this campaign if available.
example: John Doe
updatedBy:
type: string
description: Name of the user who last updated this campaign if available.
example: Jane Doe
templateId:
type: integer
description: The ID of the Campaign Template this Campaign was created from.
example: 3
additionalProperties: false
CampaignForNotification:
type: object
description: ''
required:
- id
- created
- applicationId
- userId
- name
- state
- tags
- limits
- features
- description
- type
- budgets
properties:
id:
type: integer
description: Unique ID for this entity.
example: 4
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
userId:
type: integer
description: The ID of the user associated with this entity.
example: 388
name:
type: string
title: Campaign Name
description: A user-facing name for this campaign.
minLength: 1
example: Summer promotions
description:
type: string
title: Campaign Description
description: A detailed description of the campaign.
example: Campaign for all summer 2021 promotions
startTime:
type: string
format: date-time
description: Timestamp when the campaign will become active.
example: '2021-07-20T22:00:00Z'
endTime:
type: string
format: date-time
description: Timestamp when the campaign will become inactive.
example: '2021-09-22T22:00:00Z'
attributes:
type: object
description: Arbitrary properties associated with this campaign.
additionalProperties: true
state:
type: string
enum:
- enabled
- disabled
- archived
- draft
- scheduled
- running
- expired
default: enabled
example: enabled
description: |
A disabled or archived campaign is not evaluated for rules or coupons.
activeRulesetId:
type: integer
description: >
[ID of
Ruleset](https://docs.talon.one/management-api#operation/getRulesets)
this
campaign applies on customer session evaluation.
example: 6
tags:
type: array
description: A list of tags for the campaign.
example:
- summer
maxItems: 50
items:
type: string
minLength: 1
maxLength: 50
features:
type: array
description: The features enabled in this campaign.
example:
- coupons
- referrals
items:
type: string
enum:
- coupons
- referrals
- loyalty
- giveaways
- strikethrough
couponSettings:
$ref: '#/definitions/CodeGeneratorSettings'
referralSettings:
$ref: '#/definitions/CodeGeneratorSettings'
limits:
type: array
description: >
The set of [budget
limits](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets)
for this campaign.
items:
$ref: '#/definitions/LimitConfig'
campaignGroups:
type: array
description: >
The IDs of the [campaign
groups](https://docs.talon.one/docs/product/account/managing-campaign-groups)
this campaign belongs to.
example:
- 1
- 3
items:
type: integer
evaluationGroupId:
type: integer
example: 2
description: The ID of the campaign evaluation group the campaign belongs to.
type:
type: string
enum:
- cartItem
- advanced
default: advanced
example: advanced
description: |
The campaign type. Possible type values:
- `cartItem`: Type of campaign that can apply effects only to cart items.
- `advanced`: Type of campaign that can apply effects to customer sessions and cart items.
linkedStoreIds:
type: array
description: >
A list of store IDs that are linked to the campaign.
**Note:** Campaigns with linked store IDs will only be evaluated when
there is a
[customer session
update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
that references a linked store.
items:
type: integer
example:
- 1
- 2
- 3
budgets:
type: array
items:
$ref: '#/definitions/CampaignBudget'
description: >
A list of all the budgets that are defined by this campaign and their
usage.
**Note:** Budgets that are not defined do not appear in this list and
their usage is
not counted until they are defined.
couponRedemptionCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Number of coupons redeemed in the campaign.
example: 163
referralRedemptionCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Number of referral codes redeemed in the campaign.
example: 3
discountCount:
type: number
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total amount of discounts redeemed in the campaign.
example: 288
discountEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of times discounts were redeemed in this campaign.
example: 343
couponCreationCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of coupons created by rules in this campaign.
example: 16
customEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of custom effects triggered by rules in this campaign.
example: 0
referralCreationCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of referrals created by rules in this campaign.
example: 8
addFreeItemEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of times the [add free item
effect](https://docs.talon.one/docs/dev/integration-api/api-effects#addfreeitem)
can be triggered in this campaign.
example: 0
awardedGiveawaysCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of giveaways awarded by rules in this campaign.
example: 9
createdLoyaltyPointsCount:
type: number
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty points created by rules in this campaign.
example: 9
createdLoyaltyPointsEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty point creation effects triggered by rules in
this campaign.
example: 2
redeemedLoyaltyPointsCount:
type: number
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty points redeemed by rules in this campaign.
example: 8
redeemedLoyaltyPointsEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty point redemption effects triggered by rules in
this campaign.
example: 9
callApiEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of webhooks triggered by rules in this campaign.
example: 0
reservecouponEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of reserve coupon effects triggered by rules in this
campaign.
example: 9
lastActivity:
type: string
format: date-time
example: '2022-11-10T23:00:00Z'
description: Timestamp of the most recent event received by this campaign.
updated:
type: string
format: date-time
example: '2022-10-97T35:00:00Z'
description: >
Timestamp of the most recent update to the campaign's property.
Updates to external entities used in this campaign
are **not** registered by this property, such as collection or coupon
updates.
createdBy:
type: string
description: Name of the user who created this campaign if available.
example: John Doe
updatedBy:
type: string
description: Name of the user who last updated this campaign if available.
example: Jane Doe
templateId:
type: integer
description: The ID of the Campaign Template this Campaign was created from.
example: 3
additionalProperties: false
CampaignBudget:
type: object
required:
- action
- limit
- counter
properties:
action:
type: string
description: |
The limitable action to which this limit applies. For example:
- `setDiscount`
- `setDiscountEffect`
- `redeemCoupon`
- `createCoupon`
example: createCoupon
limit:
type: number
minimum: 0
example: 1000
description: The value to set for the limit.
counter:
type: number
minimum: 0
example: 42
description: >-
The number of occurrences of the limited action in the context of the
campaign.
AdditionalCampaignProperties:
type: object
properties:
budgets:
type: array
items:
$ref: '#/definitions/CampaignBudget'
description: >
A list of all the budgets that are defined by this campaign and their
usage.
**Note:** Budgets that are not defined do not appear in this list and
their usage is
not counted until they are defined.
couponRedemptionCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Number of coupons redeemed in the campaign.
example: 163
referralRedemptionCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Number of referral codes redeemed in the campaign.
example: 3
discountCount:
type: number
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total amount of discounts redeemed in the campaign.
example: 288
discountEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of times discounts were redeemed in this campaign.
example: 343
couponCreationCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of coupons created by rules in this campaign.
example: 16
customEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of custom effects triggered by rules in this campaign.
example: 0
referralCreationCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of referrals created by rules in this campaign.
example: 8
addFreeItemEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of times the [add free item
effect](https://docs.talon.one/docs/dev/integration-api/api-effects#addfreeitem)
can be triggered in this campaign.
example: 0
awardedGiveawaysCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of giveaways awarded by rules in this campaign.
example: 9
createdLoyaltyPointsCount:
type: number
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty points created by rules in this campaign.
example: 9
createdLoyaltyPointsEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty point creation effects triggered by rules in
this campaign.
example: 2
redeemedLoyaltyPointsCount:
type: number
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty points redeemed by rules in this campaign.
example: 8
redeemedLoyaltyPointsEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty point redemption effects triggered by rules in
this campaign.
example: 9
callApiEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of webhooks triggered by rules in this campaign.
example: 0
reservecouponEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of reserve coupon effects triggered by rules in this
campaign.
example: 9
lastActivity:
type: string
format: date-time
example: '2022-11-10T23:00:00Z'
description: Timestamp of the most recent event received by this campaign.
updated:
type: string
format: date-time
example: '2022-10-97T35:00:00Z'
description: >
Timestamp of the most recent update to the campaign's property.
Updates to external entities used in this campaign
are **not** registered by this property, such as collection or coupon
updates.
createdBy:
type: string
description: Name of the user who created this campaign if available.
example: John Doe
updatedBy:
type: string
description: Name of the user who last updated this campaign if available.
example: Jane Doe
templateId:
type: integer
description: The ID of the Campaign Template this Campaign was created from.
example: 3
required:
- state
- description
- type
- budgets
NewRuleset:
type: object
required:
- rules
- bindings
properties:
rules:
type: array
description: Set of rules to apply.
items:
$ref: '#/definitions/Rule'
strikethroughRules:
type: array
description: Set of rules to apply for strikethrough.
items:
$ref: '#/definitions/Rule'
bindings:
type: array
description: >-
An array that provides objects with variable names (name) and talang
expressions to whose result they are bound (expression) during rule
evaluation. The order of the evaluation is decided by the position in
the array.
items:
$ref: '#/definitions/Binding'
example: []
rbVersion:
type: string
description: The version of the rulebuilder used to create this ruleset.
example: v2
activate:
type: boolean
description: >-
Indicates whether this created ruleset should be activated for the
campaign that owns it.
example: true
Ruleset:
type: object
description: ''
required:
- id
- created
- userId
- rules
- bindings
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
userId:
type: integer
description: The ID of the user associated with this entity.
example: 388
rules:
type: array
description: Set of rules to apply.
items:
$ref: '#/definitions/Rule'
strikethroughRules:
type: array
description: Set of rules to apply for strikethrough.
items:
$ref: '#/definitions/Rule'
bindings:
type: array
description: >-
An array that provides objects with variable names (name) and talang
expressions to whose result they are bound (expression) during rule
evaluation. The order of the evaluation is decided by the position in
the array.
items:
$ref: '#/definitions/Binding'
example: []
rbVersion:
type: string
description: The version of the rulebuilder used to create this ruleset.
example: v2
activate:
type: boolean
description: >-
Indicates whether this created ruleset should be activated for the
campaign that owns it.
example: true
campaignId:
type: integer
title: Campaign ID
description: The ID of the campaign that owns this entity.
example: 320
templateId:
type: integer
title: Campaign Template ID
description: The ID of the campaign template that owns this entity.
example: 3
activatedAt:
type: string
format: date-time
description: Timestamp indicating when this Ruleset was activated.
additionalProperties: false
Binding:
type: object
required:
- name
- expression
properties:
name:
type: string
description: A descriptive name for the value to be bound.
example: my property
type:
type: string
description: |
The kind of binding. Possible values are:
- `bundle`
- `cartItemFilter`
- `subledgerBalance`
- `templateParameter`
example: templateParameter
expression:
type: array
description: >-
A Talang expression that will be evaluated and its result attached to
the name of the binding.
items:
type: object
valueType:
type: string
description: |
Can be one of the following:
- `string`
- `number`
- `boolean`
example: string
Rule:
type: object
required:
- title
- condition
- effects
properties:
id:
type: string
format: uuid
description: A unique identifier for the rule.
example: 7fa800a8-ac8d-4792-85dc-c4650dcc8f23
parentId:
type: string
format: uuid
description: The ID of the rule that was copied to create this rule.
example: 7fa800a8-ac8d-4792-85dc-c4650dcc8f23
title:
type: string
description: A short description of the rule.
example: Give discount via coupon
description:
type: string
description: 'A longer, more detailed description of the rule.'
example: Creates a discount when a coupon is valid
bindings:
type: array
description: >-
An array that provides objects with variable names (name) and talang
expressions to whose result they are bound (expression) during rule
evaluation. The order of the evaluation is decided by the position in
the array.
items:
$ref: '#/definitions/Binding'
condition:
type: array
description: >-
A Talang expression that will be evaluated in the context of the given
event.
minItems: 1
example:
- and
- - couponValid
items:
type: object
effects:
type: array
description: >-
An array of effectful Talang expressions in arrays that will be
evaluated when a rule matches.
items:
type: object
example:
- catch
- - noop
- - setDiscount
- 10% off
- - '*'
- - .
- Session
- Total
- - /
- 10
- 100
TemplateLimitConfig:
type: object
description: ''
required:
- action
- limit
- entities
properties:
action:
type: string
description: |
The limitable action to which this limit applies. For example:
- `setDiscount`
- `setDiscountEffect`
- `redeemCoupon`
- `createCoupon`
example: createCoupon
limit:
type: number
minimum: 0
example: 1000
description: The value to set for the limit.
period:
description: The period on which the budget limit recurs.
type: string
enum:
- daily
- weekly
- monthly
- yearly
example: yearly
entities:
type: array
description: The entity that this limit applies to.
example:
- Coupon
items:
type: string
enum:
- Coupon
- Referral
- Profile
- Identifier
additionalProperties: false
LimitConfig:
type: object
required:
- action
- limit
- entities
properties:
action:
type: string
description: |
The limitable action to which this limit applies. For example:
- `setDiscount`
- `setDiscountEffect`
- `redeemCoupon`
- `createCoupon`
example: createCoupon
limit:
type: number
minimum: 0
example: 1000
description: The value to set for the limit.
period:
description: The period on which the budget limit recurs.
type: string
enum:
- daily
- weekly
- monthly
- yearly
example: yearly
entities:
type: array
description: The entity that this limit applies to.
example:
- Coupon
items:
type: string
enum:
- Coupon
- Referral
- Profile
- Identifier
CampaignSet:
type: object
description: ''
required:
- applicationId
- set
- version
- id
properties:
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
id:
type: integer
description: Internal ID of this entity.
example: 6
version:
type: integer
minimum: 1
description: Version of the campaign set.
example: 3
set:
$ref: '#/definitions/CampaignSetBranchNode'
updatedBy:
type: string
description: 'Name of the user who last updated this campaign set, if available.'
example: Jane Doe
additionalProperties: false
CampaignSetNode:
type: object
required:
- type
properties:
type:
type: string
example: type
CampaignSetBranchNode:
type: object
additionalProperties: false
required:
- type
- name
- operator
- elements
- groupId
- evaluationMode
- locked
- evaluationScope
properties:
type:
type: string
description: Indicates the node type.
enum:
- SET
example: SET
name:
type: string
description: Name of the set.
example: name
operator:
type: string
description: An indicator of how the set operates on its elements.
enum:
- ALL
- FIRST
example: ALL
elements:
type: array
description: Child elements of this set.
items:
$ref: '#/definitions/CampaignSetNode'
groupId:
type: integer
description: The ID of the campaign set.
locked:
type: boolean
description: An indicator of whether the campaign set is locked for modification.
description:
type: string
description: A description of the campaign set.
evaluationMode:
type: string
enum:
- stackable
- listOrder
- lowestDiscount
- highestDiscount
description: >-
The mode by which campaigns in the campaign evaluation group are
evaluated.
evaluationScope:
type: string
enum:
- cartItem
- session
description: The evaluation scope of the campaign evaluation group.
CampaignSetLeafNode:
type: object
additionalProperties: false
required:
- type
- campaignId
properties:
type:
type: string
description: Indicates the node type.
enum:
- CAMPAIGN
campaignId:
type: integer
description: ID of the campaign
NewCampaignSet:
type: object
description: ''
required:
- applicationId
- set
- version
properties:
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
version:
type: integer
minimum: 1
example: 2
description: Version of the campaign set.
set:
$ref: '#/definitions/CampaignSetBranchNode'
additionalProperties: false
NewCampaignEvaluationGroup:
type: object
required:
- name
- parentId
- evaluationMode
- locked
- evaluationScope
properties:
name:
type: string
description: The name of the campaign evaluation group.
example: Summer campaigns
parentId:
type: integer
minimum: 1
description: >-
The ID of the parent group that contains the campaign evaluation
group.
example: 2
description:
type: string
description: A description of the campaign evaluation group.
example: >-
This campaign evaluation group contains all campaigns that are running
in the summer.
evaluationMode:
type: string
enum:
- stackable
- listOrder
- lowestDiscount
- highestDiscount
description: >-
The mode by which campaigns in the campaign evaluation group are
evaluated.
evaluationScope:
type: string
enum:
- cartItem
- session
description: The evaluation scope of the campaign evaluation group.
locked:
description: >-
An indicator of whether the campaign evaluation group is locked for
modification.
type: boolean
example: false
UpdateCampaignEvaluationGroup:
type: object
description: ''
required:
- name
- parentId
- evaluationMode
- locked
- evaluationScope
properties:
name:
type: string
description: The name of the campaign evaluation group.
example: Summer campaigns
parentId:
type: integer
minimum: 1
description: >-
The ID of the parent group that contains the campaign evaluation
group.
example: 2
description:
type: string
description: A description of the campaign evaluation group.
example: >-
This campaign evaluation group contains all campaigns that are running
in the summer.
evaluationMode:
type: string
enum:
- stackable
- listOrder
- lowestDiscount
- highestDiscount
description: >-
The mode by which campaigns in the campaign evaluation group are
evaluated.
evaluationScope:
type: string
enum:
- cartItem
- session
description: The evaluation scope of the campaign evaluation group.
locked:
description: >-
An indicator of whether the campaign evaluation group is locked for
modification.
type: boolean
example: false
additionalProperties: false
CampaignEvaluationGroup:
type: object
description: ''
required:
- applicationId
- name
- parentId
- evaluationMode
- locked
- evaluationScope
- id
properties:
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
name:
type: string
description: The name of the campaign evaluation group.
example: Summer campaigns
parentId:
type: integer
minimum: 1
description: >-
The ID of the parent group that contains the campaign evaluation
group.
example: 2
description:
type: string
description: A description of the campaign evaluation group.
example: >-
This campaign evaluation group contains all campaigns that are running
in the summer.
evaluationMode:
type: string
enum:
- stackable
- listOrder
- lowestDiscount
- highestDiscount
description: >-
The mode by which campaigns in the campaign evaluation group are
evaluated.
evaluationScope:
type: string
enum:
- cartItem
- session
description: The evaluation scope of the campaign evaluation group.
locked:
description: >-
An indicator of whether the campaign evaluation group is locked for
modification.
type: boolean
example: false
id:
type: integer
description: >-
Unique ID for this entity. Not to be confused with the Integration ID,
which is set by your integration layer and used in most endpoints.
example: 6
additionalProperties: false
ReferralConstraints:
type: object
properties:
startDate:
type: string
format: date-time
minimum: 0
title: Referral code valid from
description: Timestamp at which point the referral code becomes valid.
example: '2020-11-10T23:00:00Z'
expiryDate:
type: string
format: date-time
minimum: 0
title: Referral code valid until
description: >-
Expiration date of the referral code. Referral never expires if this
is omitted, zero, or negative.
example: '2021-11-10T23:00:00Z'
usageLimit:
type: integer
title: Referral code Usage Limit
description: >
The number of times a referral code can be used. `0` means no limit
but any campaign usage limits will still apply.
minimum: 0
maximum: 999999
example: 1
UpdateReferralBatch:
type: object
required:
- batchID
additionalProperties: false
properties:
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
batchID:
title: Batch ID
type: string
description: The id of the batch the referral belongs to.
example: 32535-43255
startDate:
type: string
format: date-time
minimum: 0
title: Referral code valid from
description: Timestamp at which point the referral code becomes valid.
example: '2020-11-10T23:00:00Z'
expiryDate:
type: string
format: date-time
minimum: 0
title: Referral code valid until
example: '2021-11-10T23:00:00Z'
description: >-
Expiration date of the referral code. Referral never expires if this
is omitted, zero, or negative.
usageLimit:
type: integer
title: Referral code Usage Limit
description: >
The number of times a referral code can be used. This can be set to 0
for no limit, but any campaign usage limits will still apply.
minimum: 0
maximum: 999999
example: 1
NewReferral:
type: object
description: ''
required:
- campaignId
- advocateProfileIntegrationId
properties:
startDate:
type: string
format: date-time
minimum: 0
title: Referral code valid from
description: Timestamp at which point the referral code becomes valid.
example: '2020-11-10T23:00:00Z'
expiryDate:
type: string
format: date-time
minimum: 0
title: Referral code valid until
description: >-
Expiration date of the referral code. Referral never expires if this
is omitted, zero, or negative.
example: '2021-11-10T23:00:00Z'
usageLimit:
type: integer
title: Referral code Usage Limit
description: >
The number of times a referral code can be used. `0` means no limit
but any campaign usage limits will still apply.
minimum: 0
maximum: 999999
example: 1
campaignId:
type: integer
title: Referral's Campaign ID
description: ID of the campaign from which the referral received the referral code.
example: 78
advocateProfileIntegrationId:
type: string
title: Advocate's Profile ID
description: The Integration ID of the Advocate's Profile.
maxLength: 1000
example: URNGV8294NV
friendProfileIntegrationId:
type: string
title: Friend's Profile ID
description: An optional Integration ID of the Friend's Profile.
example: BZGGC2454PA
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
example:
channel: web
additionalProperties: false
ImportEntity:
type: object
properties:
importId:
type: integer
description: The ID of the Import which created this referral.
example: 4
Referral:
type: object
description: ''
required:
- id
- created
- campaignId
- advocateProfileIntegrationId
- code
- usageCounter
- usageLimit
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
startDate:
type: string
format: date-time
minimum: 0
title: Referral code valid from
description: Timestamp at which point the referral code becomes valid.
example: '2020-11-10T23:00:00Z'
expiryDate:
type: string
format: date-time
minimum: 0
title: Referral code valid until
description: >-
Expiration date of the referral code. Referral never expires if this
is omitted, zero, or negative.
example: '2021-11-10T23:00:00Z'
usageLimit:
type: integer
title: Referral code Usage Limit
description: >
The number of times a referral code can be used. `0` means no limit
but any campaign usage limits will still apply.
minimum: 0
maximum: 999999
example: 1
campaignId:
type: integer
title: Referral's Campaign ID
description: ID of the campaign from which the referral received the referral code.
example: 78
advocateProfileIntegrationId:
type: string
title: Advocate's Profile ID
description: The Integration ID of the Advocate's Profile.
maxLength: 1000
example: URNGV8294NV
friendProfileIntegrationId:
type: string
title: Friend's Profile ID
description: An optional Integration ID of the Friend's Profile.
example: BZGGC2454PA
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
example:
channel: web
importId:
type: integer
description: The ID of the Import which created this referral.
example: 4
code:
type: string
title: Referral code
description: The referral code.
minLength: 4
example: 27G47Y54VH9L
usageCounter:
type: integer
title: Referral code Usages
description: The number of times this referral code has been successfully used.
example: 1
batchId:
type: string
title: Batch ID
description: The ID of the batch the referrals belong to.
example: tqyrgahe
additionalProperties: false
UpdateReferral:
type: object
additionalProperties: false
properties:
friendProfileIntegrationId:
type: string
title: Friend's Profile ID
description: An optional Integration ID of the Friend's Profile.
example: BZGGC2454PA
maxLength: 1000
startDate:
type: string
format: date-time
minimum: 0
title: Referral code valid from
description: Timestamp at which point the referral code becomes valid.
example: '2020-11-10T23:00:00Z'
expiryDate:
type: string
format: date-time
minimum: 0
title: Referral code valid until
description: >-
Expiration date of the referral code. Referral never expires if this
is omitted, zero, or negative.
example: '2021-11-10T23:00:00Z'
usageLimit:
type: integer
title: Referral code Usage Limit
description: >
The number of times a referral code can be used. This can be set to 0
for no limit, but any campaign usage limits will still apply.
minimum: 0
maximum: 999999
example: 1
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
NewReferralsForMultipleAdvocates:
type: object
description: ''
required:
- campaignId
- advocateProfileIntegrationIds
- usageLimit
properties:
startDate:
type: string
format: date-time
minimum: 0
title: Referral code valid from
description: Timestamp at which point the referral code becomes valid.
example: '2020-11-10T23:00:00Z'
expiryDate:
type: string
format: date-time
minimum: 0
title: Referral code valid until
description: >-
Expiration date of the referral code. Referral never expires if this
is omitted, zero, or negative.
example: '2021-11-10T23:00:00Z'
usageLimit:
type: integer
title: Referral code Usage Limit
description: >
The number of times a referral code can be used. `0` means no limit
but any campaign usage limits will still apply.
minimum: 0
maximum: 999999
example: 1
campaignId:
type: integer
title: Referral's Campaign ID
description: >-
The ID of the campaign from which the referral received the referral
code.
example: 45
advocateProfileIntegrationIds:
type: array
title: Advocate Profile List
description: An array containing all the respective advocate profiles.
example:
- URNGV8294NV
- DRPVV9476AF
items:
type: string
maxItems: 1000
minItems: 1
attributes:
type: object
description: Arbitrary properties associated with this referral code.
additionalProperties: true
example:
channel: web
validCharacters:
type: array
description: >
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.
example:
- 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
items:
type: string
referralPattern:
type: string
description: >
The pattern used to generate referrals. The character `#` is a
placeholder and is replaced by a random character from the
`validCharacters` set.
example: 'REF-###-###'
maxLength: 100
minLength: 3
additionalProperties: false
InventoryReferral:
type: object
description: ''
required:
- id
- created
- campaignId
- advocateProfileIntegrationId
- code
- usageCounter
- usageLimit
- referredCustomers
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
startDate:
type: string
format: date-time
minimum: 0
title: Referral code valid from
description: Timestamp at which point the referral code becomes valid.
example: '2020-11-10T23:00:00Z'
expiryDate:
type: string
format: date-time
minimum: 0
title: Referral code valid until
description: >-
Expiration date of the referral code. Referral never expires if this
is omitted, zero, or negative.
example: '2021-11-10T23:00:00Z'
usageLimit:
type: integer
title: Referral code Usage Limit
description: >
The number of times a referral code can be used. `0` means no limit
but any campaign usage limits will still apply.
minimum: 0
maximum: 999999
example: 1
campaignId:
type: integer
title: Referral's Campaign ID
description: ID of the campaign from which the referral received the referral code.
example: 78
advocateProfileIntegrationId:
type: string
title: Advocate's Profile ID
description: The Integration ID of the Advocate's Profile.
maxLength: 1000
example: URNGV8294NV
friendProfileIntegrationId:
type: string
title: Friend's Profile ID
description: An optional Integration ID of the Friend's Profile.
example: BZGGC2454PA
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
example:
channel: web
importId:
type: integer
description: The ID of the Import which created this referral.
example: 4
code:
type: string
title: Referral code
description: The referral code.
minLength: 4
example: 27G47Y54VH9L
usageCounter:
type: integer
title: Referral code Usages
description: The number of times this referral code has been successfully used.
example: 1
batchId:
type: string
title: Batch ID
description: The ID of the batch the referrals belong to.
example: tqyrgahe
referredCustomers:
type: array
description: An array of referred customers.
items:
type: string
additionalProperties: false
AttributeQuery:
type: object
additionalProperties: true
description: Object representing a set of of attributes and their respective values.
example:
my_attribute_1: some value
my_attribute_2: some other value
my_attribute_3: some other value
CouponSearch:
type: object
required:
- attributes
properties:
attributes:
type: object
description: >-
Properties to match against a coupon. All provided attributes will be
exactly matched against attributes.
additionalProperties: true
CampaignSearch:
type: object
required:
- attributes
properties:
attributes:
type: object
description: >-
Properties to match against a campaign. All provided attributes will
be exactly matched against campaign attributes.
additionalProperties: true
CampaignCopy:
type: object
required:
- applicationIds
properties:
name:
type: string
description: >-
Name of the copied campaign (Defaults to "Copy of original campaign
name").
example: Copy of Summer promotions
applicationIds:
type: array
description: >-
Application IDs of the applications to which a campaign should be
copied to.
additionalProperties: true
items:
type: integer
example:
- 1
- 2
- 3
description:
type: string
title: Campaign Description
description: A detailed description of the campaign.
example: Campaign for all summer 2021 promotions
startTime:
type: string
format: date-time
description: Timestamp when the campaign will become active.
example: '2021-06-01T09:00:27.993483Z'
endTime:
type: string
format: date-time
description: Timestamp when the campaign will become inactive.
example: '2021-09-10T01:00:00.993483Z'
tags:
type: array
description: A list of tags for the campaign.
maxItems: 50
items:
type: string
minLength: 1
maxLength: 50
example:
- Summer
- Shoes
evaluationGroupId:
type: integer
example: 2
description: The ID of the campaign evaluation group the campaign belongs to.
NewCoupons:
type: object
description: ''
required:
- numberOfCoupons
- usageLimit
properties:
usageLimit:
type: integer
minimum: 0
maximum: 999999
example: 100
description: >
The number of times the coupon code can be redeemed. `0` means
unlimited redemptions but any campaign usage limits will still apply.
discountLimit:
type: number
minimum: 0
maximum: 999999
example: 30
description: >
The total discount value that the code can give. Typically used to
represent a gift card value.
reservationLimit:
type: integer
minimum: 0
maximum: 999999
example: 45
description: |
The number of reservations that can be made with this coupon code.
startDate:
type: string
format: date-time
example: '2020-01-24T14:15:22Z'
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
example: '2023-08-24T14:15:22Z'
minimum: 0
description: >-
Expiration date of the coupon. Coupon never expires if this is
omitted, zero, or negative.
limits:
type: array
description: >
Limits configuration for a coupon. These limits will override the
limits
set from the campaign.
**Note:** Only usable when creating a single coupon which is not tied
to a specific recipient.
Only per-profile limits are allowed to be configured.
items:
$ref: '#/definitions/LimitConfig'
numberOfCoupons:
type: integer
description: >-
The number of new coupon codes to generate for the campaign. Must be
at least 1.
example: 1
uniquePrefix:
title: Coupon code unique prefix
type: string
description: >
**DEPRECATED** To create more than 20,000 coupons in one request, use
[Create coupons
asynchronously](https://docs.talon.one/management-api#operation/createCouponsAsync)
endpoint.
example: ''
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
example:
venueId: 12
recipientIntegrationId:
title: Receiving customer profile integration ID
type: string
maxLength: 1000
description: The integration ID for this coupon's beneficiary's profile.
example: URNGV8294NV
validCharacters:
type: array
description: >
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.
items:
type: string
example:
- A
- B
- G
- 'Y'
couponPattern:
type: string
description: >
The pattern used to generate coupon codes.
The character `#` is a placeholder and is replaced by a random
character from the `validCharacters` set.
maxLength: 100
minLength: 3
example: 'SUMMER-#####'
isReservationMandatory:
title: Is reservation mandatory
type: boolean
example: false
description: Whether the reservation effect actually created a new reservation.
default: true
implicitlyReserved:
title: Is coupon implicitly reserved for all customers
description: >-
An indication of whether the coupon is implicitly reserved for all
customers.
type: boolean
example: false
additionalProperties: false
NewCouponsForMultipleRecipients:
type: object
description: ''
required:
- recipientsIntegrationIds
- usageLimit
properties:
usageLimit:
type: integer
minimum: 0
maximum: 999999
example: 100
description: >
The number of times the coupon code can be redeemed. `0` means
unlimited redemptions but any campaign usage limits will still apply.
discountLimit:
type: number
minimum: 0
maximum: 999999
example: 30
description: >
The total discount value that the code can give. Typically used to
represent a gift card value.
reservationLimit:
type: integer
minimum: 0
maximum: 999999
example: 45
description: |
The number of reservations that can be made with this coupon code.
startDate:
type: string
format: date-time
example: '2020-01-24T14:15:22Z'
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
example: '2023-08-24T14:15:22Z'
minimum: 0
description: >-
Expiration date of the coupon. Coupon never expires if this is
omitted, zero, or negative.
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
example:
venueId: 12
recipientsIntegrationIds:
title: Receiving customer profiles integration IDs
type: array
example:
- URNGV8294NV
- BZGGC2454PA
items:
type: string
description: The integration IDs for recipients.
maxItems: 1000
minItems: 1
validCharacters:
type: array
description: >
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.
example:
- 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
items:
type: string
couponPattern:
type: string
description: >
The pattern used to generate coupon codes. The character `#` is a
placeholder and is replaced by a random character from the
`validCharacters` set.
example: 'SUMMER-#####'
maxLength: 100
minLength: 3
additionalProperties: false
UpdateCoupon:
type: object
description: ''
properties:
usageLimit:
type: integer
minimum: 0
maximum: 999999
example: 100
description: >
The number of times the coupon code can be redeemed. `0` means
unlimited redemptions but any campaign usage limits will still apply.
discountLimit:
type: number
minimum: 0
maximum: 999999
example: 30
description: >
The total discount value that the code can give. Typically used to
represent a gift card value.
reservationLimit:
type: integer
minimum: 0
maximum: 999999
example: 45
description: |
The number of reservations that can be made with this coupon code.
startDate:
type: string
format: date-time
example: '2020-01-24T14:15:22Z'
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
example: '2023-08-24T14:15:22Z'
minimum: 0
description: >-
Expiration date of the coupon. Coupon never expires if this is
omitted, zero, or negative.
limits:
type: array
description: >
Limits configuration for a coupon. These limits will override the
limits
set from the campaign.
**Note:** Only usable when creating a single coupon which is not tied
to a specific recipient.
Only per-profile limits are allowed to be configured.
items:
$ref: '#/definitions/LimitConfig'
recipientIntegrationId:
title: Receiving customer profile integration ID
type: string
maxLength: 1000
description: The integration ID for this coupon's beneficiary's profile.
example: URNGV8294NV
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
isReservationMandatory:
title: Is reservation mandatory
type: boolean
example: false
description: Whether the reservation effect actually created a new reservation.
default: true
implicitlyReserved:
title: Is coupon implicitly reserved for all customers
description: >-
An indication of whether the coupon is implicitly reserved for all
customers.
type: boolean
example: false
additionalProperties: false
UpdateCouponBatch:
type: object
description: ''
properties:
usageLimit:
type: integer
minimum: 0
maximum: 999999
example: 100
description: >
The number of times the coupon code can be redeemed. `0` means
unlimited redemptions but any campaign usage limits will still apply.
discountLimit:
type: number
minimum: 0
maximum: 999999
example: 30
description: >
The total discount value that the code can give. Typically used to
represent a gift card value.
reservationLimit:
type: integer
minimum: 0
maximum: 999999
example: 45
description: |
The number of reservations that can be made with this coupon code.
startDate:
type: string
format: date-time
example: '2020-01-24T14:15:22Z'
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
example: '2023-08-24T14:15:22Z'
minimum: 0
description: >-
Expiration date of the coupon. Coupon never expires if this is
omitted, zero, or negative.
attributes:
type: object
description: >
Optional property to set the value of custom coupon attributes. They
are defined in the Campaign Manager,
see [Managing
attributes](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes).
Coupon attributes can also be set to _mandatory_ in your Application
[settings](https://docs.talon.one/docs/product/applications/using-attributes#making-attributes-mandatory).
If your Application uses mandatory attributes, you must use this
property to set their value.
additionalProperties: true
batchID:
title: Batch ID
type: string
description: The ID of the batch the coupon(s) belong to.
additionalProperties: false
Coupon:
type: object
description: ''
required:
- id
- created
- campaignId
- value
- usageCounter
- usageLimit
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
campaignId:
type: integer
title: Campaign ID
description: The ID of the campaign that owns this entity.
example: 211
value:
type: string
title: Coupon Code
description: The coupon code.
minLength: 4
example: XMAS-20-2021
usageLimit:
type: integer
minimum: 0
maximum: 999999
example: 100
description: >
The number of times the coupon code can be redeemed. `0` means
unlimited redemptions but any campaign usage limits will still apply.
discountLimit:
type: number
minimum: 0
maximum: 999999
example: 30
description: >
The total discount value that the code can give. Typically used to
represent a gift card value.
reservationLimit:
type: integer
minimum: 0
maximum: 999999
example: 45
description: |
The number of reservations that can be made with this coupon code.
startDate:
type: string
format: date-time
example: '2020-01-24T14:15:22Z'
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
example: '2023-08-24T14:15:22Z'
minimum: 0
description: >-
Expiration date of the coupon. Coupon never expires if this is
omitted, zero, or negative.
limits:
type: array
description: >
Limits configuration for a coupon. These limits will override the
limits
set from the campaign.
**Note:** Only usable when creating a single coupon which is not tied
to a specific recipient.
Only per-profile limits are allowed to be configured.
items:
$ref: '#/definitions/LimitConfig'
usageCounter:
type: integer
title: Total coupon redemptions
example: 10
description: The number of times the coupon has been successfully redeemed.
discountCounter:
type: number
title: Discounts Given
description: >-
The amount of discounts given on rules redeeming this coupon. Only
usable if a coupon discount budget was set for this coupon.
example: 10
discountRemainder:
type: number
title: Coupon Discount Remainder
description: The remaining discount this coupon can give.
example: 5
reservationCounter:
type: number
title: Number of reservations
description: The number of times this coupon has been reserved.
example: 1
attributes:
type: object
title: Attributes of coupon
description: Custom attributes associated with this coupon.
additionalProperties: true
referralId:
type: integer
title: Advocate ID
description: >-
The integration ID of the referring customer (if any) for whom this
coupon was created as an effect.
example: 326632952
recipientIntegrationId:
title: Recipient ID
example: URNGV8294NV
type: string
maxLength: 1000
description: >-
The Integration ID of the customer that is allowed to redeem this
coupon.
importId:
title: Import ID
type: integer
description: The ID of the Import which created this coupon.
example: 4
reservation:
title: Reservation Status
type: boolean
example: false
description: >
Defines the type of reservation:
- `true`: The reservation is a soft reservation. Any customer can use
the coupon. This is done via the [Create coupon
reservation](https://docs.talon.one/integration-api#operation/createCouponReservation)
endpoint.
- `false`: The reservation is a hard reservation. Only the associated
customer (`recipientIntegrationId`) can use the coupon. This is done
via the Campaign Manager when you create a coupon for a given
`recipientIntegrationId`, the [Create
coupons](https://docs.talon.one/management-api#operation/createCoupons)
endpoint or [Create coupons for multiple
recipients](https://docs.talon.one/management-api#operation/createCouponsForMultipleRecipients)
endpoint.
default: true
batchId:
title: Batch ID
type: string
description: The id of the batch the coupon belongs to.
example: 32535-43255
isReservationMandatory:
title: Is reservation mandatory
type: boolean
example: false
description: Whether the reservation effect actually created a new reservation.
default: true
implicitlyReserved:
title: Is coupon implicitly reserved for all customers
description: >-
An indication of whether the coupon is implicitly reserved for all
customers.
type: boolean
example: false
additionalProperties: false
IntegrationCoupon:
type: object
description: ''
required:
- id
- created
- campaignId
- value
- usageCounter
- usageLimit
- profileRedemptionCount
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
campaignId:
type: integer
title: Campaign ID
description: The ID of the campaign that owns this entity.
example: 211
value:
type: string
title: Coupon Code
description: The coupon code.
minLength: 4
example: XMAS-20-2021
usageLimit:
type: integer
minimum: 0
maximum: 999999
example: 100
description: >
The number of times the coupon code can be redeemed. `0` means
unlimited redemptions but any campaign usage limits will still apply.
discountLimit:
type: number
minimum: 0
maximum: 999999
example: 30
description: >
The total discount value that the code can give. Typically used to
represent a gift card value.
reservationLimit:
type: integer
minimum: 0
maximum: 999999
example: 45
description: |
The number of reservations that can be made with this coupon code.
startDate:
type: string
format: date-time
example: '2020-01-24T14:15:22Z'
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
example: '2023-08-24T14:15:22Z'
minimum: 0
description: >-
Expiration date of the coupon. Coupon never expires if this is
omitted, zero, or negative.
limits:
type: array
description: >
Limits configuration for a coupon. These limits will override the
limits
set from the campaign.
**Note:** Only usable when creating a single coupon which is not tied
to a specific recipient.
Only per-profile limits are allowed to be configured.
items:
$ref: '#/definitions/LimitConfig'
usageCounter:
type: integer
title: Total coupon redemptions
example: 10
description: The number of times the coupon has been successfully redeemed.
discountCounter:
type: number
title: Discounts Given
description: >-
The amount of discounts given on rules redeeming this coupon. Only
usable if a coupon discount budget was set for this coupon.
example: 10
discountRemainder:
type: number
title: Coupon Discount Remainder
description: The remaining discount this coupon can give.
example: 5
reservationCounter:
type: number
title: Number of reservations
description: The number of times this coupon has been reserved.
example: 1
attributes:
type: object
title: Attributes of coupon
description: Custom attributes associated with this coupon.
additionalProperties: true
referralId:
type: integer
title: Advocate ID
description: >-
The integration ID of the referring customer (if any) for whom this
coupon was created as an effect.
example: 326632952
recipientIntegrationId:
title: Recipient ID
example: URNGV8294NV
type: string
maxLength: 1000
description: >-
The Integration ID of the customer that is allowed to redeem this
coupon.
importId:
title: Import ID
type: integer
description: The ID of the Import which created this coupon.
example: 4
reservation:
title: Reservation Status
type: boolean
example: false
description: >
Defines the type of reservation:
- `true`: The reservation is a soft reservation. Any customer can use
the coupon. This is done via the [Create coupon
reservation](https://docs.talon.one/integration-api#operation/createCouponReservation)
endpoint.
- `false`: The reservation is a hard reservation. Only the associated
customer (`recipientIntegrationId`) can use the coupon. This is done
via the Campaign Manager when you create a coupon for a given
`recipientIntegrationId`, the [Create
coupons](https://docs.talon.one/management-api#operation/createCoupons)
endpoint or [Create coupons for multiple
recipients](https://docs.talon.one/management-api#operation/createCouponsForMultipleRecipients)
endpoint.
default: true
batchId:
title: Batch ID
type: string
description: The id of the batch the coupon belongs to.
example: 32535-43255
isReservationMandatory:
title: Is reservation mandatory
type: boolean
example: false
description: Whether the reservation effect actually created a new reservation.
default: true
implicitlyReserved:
title: Is coupon implicitly reserved for all customers
description: >-
An indication of whether the coupon is implicitly reserved for all
customers.
type: boolean
example: false
profileRedemptionCount:
type: integer
title: Coupon redemptions for the profile
description: The number of times the coupon was redeemed by the profile.
example: 5
additionalProperties: false
InventoryCoupon:
type: object
description: ''
required:
- id
- created
- campaignId
- value
- usageCounter
- usageLimit
- state
- profileRedemptionCount
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
campaignId:
type: integer
title: Campaign ID
description: The ID of the campaign that owns this entity.
example: 211
value:
type: string
title: Coupon Code
description: The coupon code.
minLength: 4
example: XMAS-20-2021
usageLimit:
type: integer
minimum: 0
maximum: 999999
example: 100
description: >
The number of times the coupon code can be redeemed. `0` means
unlimited redemptions but any campaign usage limits will still apply.
discountLimit:
type: number
minimum: 0
maximum: 999999
example: 30
description: >
The total discount value that the code can give. Typically used to
represent a gift card value.
reservationLimit:
type: integer
minimum: 0
maximum: 999999
example: 45
description: |
The number of reservations that can be made with this coupon code.
startDate:
type: string
format: date-time
example: '2020-01-24T14:15:22Z'
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
example: '2023-08-24T14:15:22Z'
minimum: 0
description: >-
Expiration date of the coupon. Coupon never expires if this is
omitted, zero, or negative.
limits:
type: array
description: >
Limits configuration for a coupon. These limits will override the
limits
set from the campaign.
**Note:** Only usable when creating a single coupon which is not tied
to a specific recipient.
Only per-profile limits are allowed to be configured.
items:
$ref: '#/definitions/LimitConfig'
usageCounter:
type: integer
title: Total coupon redemptions
example: 10
description: The number of times the coupon has been successfully redeemed.
discountCounter:
type: number
title: Discounts Given
description: >-
The amount of discounts given on rules redeeming this coupon. Only
usable if a coupon discount budget was set for this coupon.
example: 10
discountRemainder:
type: number
title: Coupon Discount Remainder
description: The remaining discount this coupon can give.
example: 5
reservationCounter:
type: number
title: Number of reservations
description: The number of times this coupon has been reserved.
example: 1
attributes:
type: object
title: Attributes of coupon
description: Custom attributes associated with this coupon.
additionalProperties: true
referralId:
type: integer
title: Advocate ID
description: >-
The integration ID of the referring customer (if any) for whom this
coupon was created as an effect.
example: 326632952
recipientIntegrationId:
title: Recipient ID
example: URNGV8294NV
type: string
maxLength: 1000
description: >-
The Integration ID of the customer that is allowed to redeem this
coupon.
importId:
title: Import ID
type: integer
description: The ID of the Import which created this coupon.
example: 4
reservation:
title: Reservation Status
type: boolean
example: false
description: >
Defines the type of reservation:
- `true`: The reservation is a soft reservation. Any customer can use
the coupon. This is done via the [Create coupon
reservation](https://docs.talon.one/integration-api#operation/createCouponReservation)
endpoint.
- `false`: The reservation is a hard reservation. Only the associated
customer (`recipientIntegrationId`) can use the coupon. This is done
via the Campaign Manager when you create a coupon for a given
`recipientIntegrationId`, the [Create
coupons](https://docs.talon.one/management-api#operation/createCoupons)
endpoint or [Create coupons for multiple
recipients](https://docs.talon.one/management-api#operation/createCouponsForMultipleRecipients)
endpoint.
default: true
batchId:
title: Batch ID
type: string
description: The id of the batch the coupon belongs to.
example: 32535-43255
isReservationMandatory:
title: Is reservation mandatory
type: boolean
example: false
description: Whether the reservation effect actually created a new reservation.
default: true
implicitlyReserved:
title: Is coupon implicitly reserved for all customers
description: >-
An indication of whether the coupon is implicitly reserved for all
customers.
type: boolean
example: false
profileRedemptionCount:
type: integer
title: Number of coupon usages per profile
description: The number of times the coupon was redeemed by the profile.
example: 5
state:
type: string
example: active
description: >
Can be:
- `active`: The coupon can be used. It is a reserved coupon that is
neither pending, used nor expired, and has a non-exhausted limit
counter.
- `used`: The coupon has been redeemed and cannot be used again. It is
not pending and has reached its redemption limit or was redeemed by
the profile before expiration.
- `expired`: The coupon was never redeemed and it is now expired. It
is non-pending, non-active and non-used by the profile.
- `pending`: The coupon will be usable in the future.
- `disabled`: The coupon is part of a non-active campaign.
additionalProperties: false
CampaignAnalytics:
type: object
description: ''
required:
- date
- campaignRevenue
- totalCampaignRevenue
- campaignRefund
- totalCampaignRefund
- campaignDiscountCosts
- totalCampaignDiscountCosts
- campaignRefundedDiscounts
- totalCampaignRefundedDiscounts
- campaignFreeItems
- totalCampaignFreeItems
- referralRedemptions
- totalReferralRedemptions
- couponRedemptions
- totalCouponRedemptions
- couponRolledbackRedemptions
- totalCouponRolledbackRedemptions
- couponsCreated
- totalCouponsCreated
- referralsCreated
- totalReferralsCreated
- addedLoyaltyPoints
- totalAddedLoyaltyPoints
- deductedLoyaltyPoints
- totalDeductedLoyaltyPoints
properties:
date:
type: string
format: date-time
example: '2021-10-12T10:12:42Z'
campaignRevenue:
type: number
description: Amount of revenue in this campaign (for coupon or discount sessions).
example: 3539.76
totalCampaignRevenue:
type: number
description: >-
Amount of revenue in this campaign since it began (for coupon or
discount sessions).
example: 5784.63
campaignRefund:
type: number
description: Amount of refunds in this campaign (for coupon or discount sessions).
totalCampaignRefund:
type: number
description: >-
Amount of refunds in this campaign since it began (for coupon or
discount sessions).
campaignDiscountCosts:
type: number
description: Amount of cost caused by discounts given in the campaign.
totalCampaignDiscountCosts:
type: number
description: >-
Amount of cost caused by discounts given in the campaign since it
began.
campaignRefundedDiscounts:
type: number
description: Amount of discounts rolledback due to refund in the campaign.
totalCampaignRefundedDiscounts:
type: number
description: >-
Amount of discounts rolledback due to refund in the campaign since it
began.
campaignFreeItems:
type: integer
description: Amount of free items given in the campaign.
totalCampaignFreeItems:
type: integer
description: Amount of free items given in the campaign since it began.
example: 86
couponRedemptions:
type: integer
description: Number of coupon redemptions in the campaign.
totalCouponRedemptions:
type: integer
description: Number of coupon redemptions in the campaign since it began.
couponRolledbackRedemptions:
type: integer
description: >-
Number of coupon redemptions that have been rolled back (due to
canceling closed session) in the campaign.
totalCouponRolledbackRedemptions:
type: integer
description: >-
Number of coupon redemptions that have been rolled back (due to
canceling closed session) in the campaign since it began.
referralRedemptions:
type: integer
description: Number of referral redemptions in the campaign.
totalReferralRedemptions:
type: integer
description: Number of referral redemptions in the campaign since it began.
couponsCreated:
type: integer
description: Number of coupons created in the campaign by the rule engine.
totalCouponsCreated:
type: integer
description: >-
Number of coupons created in the campaign by the rule engine since it
began.
referralsCreated:
type: integer
description: Number of referrals created in the campaign by the rule engine.
totalReferralsCreated:
type: integer
description: >-
Number of referrals created in the campaign by the rule engine since
it began.
addedLoyaltyPoints:
type: number
description: Number of added loyalty points in the campaign in a specific interval.
example: 250
totalAddedLoyaltyPoints:
type: number
description: Number of added loyalty points in the campaign since it began.
example: 340
deductedLoyaltyPoints:
type: number
description: >-
Number of deducted loyalty points in the campaign in a specific
interval.
example: 120
totalDeductedLoyaltyPoints:
type: number
description: Number of deducted loyalty points in the campaign since it began.
example: 220
additionalProperties: false
LoyaltyDashboardData:
type: object
description: Datapoint for the graphs and cards on a loyalty program dashboard.
required:
- date
- totalActivePoints
- totalPendingPoints
- totalSpentPoints
- totalExpiredPoints
- totalMembers
- newMembers
- spentPoints
- earnedPoints
properties:
date:
type: string
format: date-time
description: Date at which data point was collected.
totalActivePoints:
type: number
description: Total of active points for this loyalty program.
example: 9756
totalPendingPoints:
type: number
description: Total of pending points for this loyalty program.
example: 548
totalSpentPoints:
type: number
description: Total of spent points for this loyalty program.
example: 25668
totalExpiredPoints:
type: number
description: Total of expired points for this loyalty program.
example: 1156
totalMembers:
type: number
description: Number of loyalty program members.
example: 2582
newMembers:
type: number
description: Number of members who joined on this day.
example: 3
spentPoints:
description: Points spent on this day.
$ref: '#/definitions/LoyaltyDashboardPointsBreakdown'
earnedPoints:
description: Points that were earned on this day.
$ref: '#/definitions/LoyaltyDashboardPointsBreakdown'
LoyaltyDashboardPointsBreakdown:
type: object
required:
- createdManually
- createdViaRuleEngine
properties:
createdManually:
type: number
example: 125
createdViaRuleEngine:
type: number
example: 9631
ApplicationApiHealth:
type: object
description: Report of health of the API connection of an application.
required:
- summary
- lastUsed
properties:
summary:
type: string
description: >
One-word summary of the health of the API connection of an
application. Possible values are:
- `OK`: The Application has received only successful API requests in
the last 5 minutes.
- `WARNING`: The Application received at least one failed request in
the last 50 minutes.
- `ERROR`: More than 50% of received requests failed.
- `CRITICAL`: All received requests failed.
- `NONE`: During the last 5 minutes, the Application hasn't recorded
any integration API requests.
enum:
- OK
- WARNING
- ERROR
- CRITICAL
- NONE
lastUsed:
type: string
format: date-time
description: time of last request relevant to the API health test.
example: '2021-09-12T10:12:42Z'
AccessLogEntry:
type: object
description: Log of application accesses.
required:
- uuid
- status
- method
- requestUri
- time
- requestPayload
- responsePayload
properties:
uuid:
type: string
description: UUID reference of request.
example: 606e7d34-2d36-4d53-ac71-d4442c325985
status:
type: integer
description: HTTP status code of response.
example: 200
method:
type: string
description: HTTP method of request.
example: PUT
requestUri:
type: string
description: target URI of request
example: /v2/customer_sessions/Session136667
time:
type: string
format: date-time
description: timestamp of request
example: '2023-01-16T16:00:00.700763Z'
requestPayload:
type: string
description: payload of request
example: |-
{
"customerSession": {
"profileId": "customer123",
"state": "closed",
...
}
responsePayload:
type: string
description: payload of response
example: '{"coupons":[],"createdCoupons":[],...}'
WebhookLogEntry:
type: object
description: Log of webhook API calls.
required:
- id
- integrationRequestUuid
- webhookId
- url
- request
- requestTime
properties:
id:
type: string
description: UUID reference of the webhook request.
example: 2
integrationRequestUuid:
type: string
description: >-
UUID reference of the integration request linked to this webhook
request.
example: 472075793
webhookId:
type: integer
description: ID of the webhook that triggered the request.
example: 5
applicationId:
type: integer
description: ID of the application that triggered the webhook.
example: 12
url:
type: string
description: Target url of request
example: www.my-company.com/my-endpoint-name
request:
type: string
description: Request message
example: |
{
mydata: "somevalue"
}
response:
type: string
description: Response message
example: ''
status:
type: integer
description: HTTP status code of response.
example: 204
requestTime:
type: string
format: date-time
description: Timestamp of request
example: '2021-07-20T22:00:00Z'
responseTime:
type: string
format: date-time
description: Timestamp of response
example: '2021-07-20T22:00:50Z'
WebhookActivationLogEntry:
type: object
description: Log of activated webhooks.
required:
- integrationRequestUuid
- webhookId
- applicationId
- campaignId
- created
properties:
integrationRequestUuid:
type: string
description: >-
UUID reference of the integration request that triggered the effect
with the webhook.
example: 6d3699cf-95bd-444a-b62f-80d6e8391dc9
webhookId:
type: integer
description: ID of the webhook that triggered the request.
example: 1
applicationId:
type: integer
description: ID of the application that triggered the webhook.
example: 13
campaignId:
type: integer
description: ID of the campaign that triggered the webhook.
example: 86
created:
type: string
format: date-time
description: Timestamp of request
example: '2023-03-21T13:55:08.571144Z'
User:
type: object
description: ''
required:
- id
- created
- modified
- email
- accountId
- inviteToken
- state
- name
- policy
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
email:
type: string
format: email
example: john.doe@example.com
description: The email address associated with your account.
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
inviteToken:
type: string
description: 'Invite token, empty if the user as already accepted their invite.'
example: Gy9b8w1irmQtEPo5RmbMmSPheL5h4
state:
type: string
enum:
- invited
- active
- deactivated
description: Current user state.
example: invited
name:
type: string
description: Full name
example: John Doe
policy:
type: object
format: acl
description: User ACL Policy
example:
Role: 127
Applications: null
latestFeedTimestamp:
type: string
format: date-time
description: Latest timestamp the user has been notified for feed.
example: '2020-06-01T00:00:00Z'
roles:
type: array
description: Contains a list of all roles the user is a member of.
example:
- 71
items:
type: integer
applicationNotificationSubscriptions:
type: object
additionalProperties: true
example: null
authMethod:
type: string
description: The Authentication method for this user.
example: basic_auth
isAdmin:
type: boolean
description: An indication of whether the user has admin permissions.
example: false
lastSignedIn:
type: string
format: date-time
description: Date and time when the user last signed in to Talon.One.
example: '2021-09-12T10:12:42Z'
lastAccessed:
type: string
format: date-time
description: >-
Date and time of the user's last activity after signing in to
Talon.One.
example: '2021-09-12T10:14:42Z'
additionalProperties: false
NewInvitation:
type: object
description: Parameters for inviting a new user.
required:
- email
properties:
name:
type: string
description: Name of the user being invited.
example: John Doe
email:
type: string
format: email
example: john.doe@example.com
acl:
type: string
description: >
The `Access Control List` json defining the role of the user. This
represents the access control on the user level.
Use one of the following:
- normal user: `{"Role": 0}`
- admin: `{"Role": 127}`
example: '{"Role":0}'
isAdmin:
type: boolean
description: >
An indication of whether the user has admin permissions. We recommend
using this flag over using the `acl` with value `{"Role": 127}`.
example: false
roles:
type: array
description: An array of role IDs to assign to the new user.
items:
type: integer
example:
- 2
- 4
- 13
Change:
type: object
description: ''
required:
- id
- created
- userId
- entity
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
userId:
type: integer
description: The ID of the user associated with this entity.
example: 388
applicationId:
type: integer
description: ID of application associated with change.
example: 359
entity:
type: string
description: API endpoint on which the change was initiated.
example: /v1/applications/359/campaigns/6727
old:
type: object
description: Resource before the change occurred.
additionalProperties: true
example: null
new:
type: object
description: Resource after the change occurred.
additionalProperties: true
example:
applicationId": 359
attributes": {}
campaignGroups": []
created": '2022-07-08T13:04:02.972762328Z'
description": ''
features":
- referrals
- loyalty
id: 6727
managementKeyId:
type: integer
description: ID of management key used to perform changes.
example: 3
additionalProperties: false
AddLoyaltyPoints:
type: object
description: Points to add.
required:
- points
properties:
points:
type: number
minimum: 0
exclusiveMinimum: true
maximum: 999999999999.99
exclusiveMaximum: false
description: Amount of loyalty points.
example: 300
name:
type: string
description: Name / reason for the point addition.
example: Compensation
validityDuration:
type: string
description: >
The time format is either:
- `immediate` or,
- an **integer** followed by one letter indicating the time unit.
Examples: `immediate`, `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`.
Available units:
- `s`: seconds
- `m`: minutes
- `h`: hours
- `D`: days
- `W`: weeks
- `M`: months
- `Y`: years
You can round certain units up or down:
- `_D` for rounding down days only. Signifies the start of the day.
- `_U` for rounding up days, weeks, months and years. Signifies the
end of the day, week, month or year.
If passed, `validUntil` should be omitted.
example: 5D
validUntil:
type: string
format: date-time
description: >
Date and time when points should expire. The value should be provided
in RFC 3339 format.
If passed, `validityDuration` should be omitted.
example: '2021-07-20T22:00:00Z'
pendingDuration:
type: string
description: >
The amount of time before the points are considered valid.
The time format is either:
- `immediate` or,
- an **integer** followed by one letter indicating the time unit.
Examples: `immediate`, `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`.
Available units:
- `s`: seconds
- `m`: minutes
- `h`: hours
- `D`: days
- `W`: weeks
- `M`: months
- `Y`: years
You can round certain units up or down:
- `_D` for rounding down days only. Signifies the start of the day.
- `_U` for rounding up days, weeks, months and years. Signifies the
end of the day, week, month or year.
example: 12h
pendingUntil:
type: string
format: date-time
description: >
Date and time after the points are considered valid. The value should
be provided in RFC 3339 format.
If passed, `pendingDuration` should be omitted.
example: '2021-07-20T22:00:00Z'
subledgerId:
type: string
description: >-
ID of the subledger the points are added to. If there is no existing
subledger with this ID, the subledger is created automatically.
example: sub-123
applicationId:
type: integer
description: >-
ID of the Application that is connected to the loyalty program. It is
displayed in your Talon.One deployment URL.
example: 322
DeductLoyaltyPoints:
type: object
description: Points to deduct.
required:
- points
properties:
points:
type: number
minimum: 0
exclusiveMinimum: true
maximum: 999999999999.99
exclusiveMaximum: false
description: Amount of loyalty points.
example: 300
name:
type: string
description: Name / reason for the point deduction.
example: Penalty
subledgerId:
type: string
description: ID of the subledger the points are deducted from.
example: sub-123
applicationId:
type: integer
description: ID of the Application that is connected to the loyalty program.
example: 322
LoyaltyProgram:
type: object
description: ''
required:
- id
- created
- name
- title
- description
- accountID
- defaultValidity
- defaultPending
- subscribedApplications
- allowSubledger
- timezone
- cardBased
- sandbox
properties:
id:
type: integer
description: The ID of loyalty program. Internal ID of this entity.
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
title:
type: string
description: The display title for the Loyalty Program.
example: Point collection
description:
type: string
description: Description of our Loyalty Program.
example: Customers collect 10 points per 1$ spent
subscribedApplications:
type: array
description: >-
A list containing the IDs of all applications that are subscribed to
this Loyalty Program.
example:
- 132
- 97
items:
type: integer
defaultValidity:
type: string
description: >
The default duration after which new loyalty points should expire. Can
be 'unlimited' or a specific time.
The time format is a number followed by one letter indicating the time
unit, like '30s', '40m', '1h', '5D', '7W', or 10M'. These rounding
suffixes are also supported:
- '_D' for rounding down. Can be used as a suffix after 'D', and
signifies the start of the day.
- '_U' for rounding up. Can be used as a suffix after 'D', 'W', and
'M', and signifies the end of the day, week, and month.
example: 2W_U
defaultPending:
type: string
description: >
The default duration of the pending time after which points should be
valid. Can be 'immediate' or a specific time.
The time format is a number followed by one letter indicating the time
unit, like '30s', '40m', '1h', '5D', '7W', or 10M'. These rounding
suffixes are also supported:
- '_D' for rounding down. Can be used as a suffix after 'D', and
signifies the start of the day.
- '_U' for rounding up. Can be used as a suffix after 'D', 'W', and
'M', and signifies the end of the day, week, and month.
example: immediate
allowSubledger:
type: boolean
description: Indicates if this program supports subledgers inside the program.
example: false
usersPerCardLimit:
type: integer
minimum: 0
example: 111
description: >
The max amount of user profiles with whom a card can be shared. This
can be set to 0 for no limit.
This property is only used when `cardBased` is `true`.
sandbox:
type: boolean
description: >-
Indicates if this program is a live or sandbox program. Programs of a
given type can only be connected to Applications of the same type.
title: Sandbox
example: true
tiersExpireIn:
type: string
description: >
The amount of time until the expiration of every tier, starting from
the date when the customer joined the considered tier for the first
time.
The time format is an **integer** followed by one letter indicating
the time unit.
Examples: `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`.
Available units:
- `s`: seconds
- `m`: minutes
- `h`: hours
- `D`: days
- `W`: weeks
- `M`: months
- `Y`: years
You can round certain units up or down:
- `_D` for rounding down days only. Signifies the start of the day.
- `_U` for rounding up days, weeks, months and years. Signifies the
end of the day, week, month or year.
example: 27W_U
tiersDowngradePolicy:
type: string
enum:
- one_down
- balance_based
description: |
Customers's tier downgrade policy.
- `one_down`: Once the tier expires and if the user doesn't have enough points to stay in the tier, the user is downgraded one tier down.
- `balance_based`: Once the tier expires, the user's tier is evaluated based on the amount of active points the user has at this instant.
accountID:
type: integer
description: The ID of the Talon.One account that owns this program.
example: 1
name:
type: string
description: The internal name for the Loyalty Program. This is an immutable value.
example: my_program
tiers:
type: array
description: The tiers in this loyalty program.
items:
$ref: '#/definitions/LoyaltyTier'
example:
- name: Gold
minPoints: 300
id: 3
created: '2021-06-10T09:05:27.993483Z'
programID: 139
- name: Silver
minPoints: 200
id: 2
created: '2021-06-10T09:04:59.355258Z'
programId: 139
- name: Bronze
minPoints: 100
id: 1
created: '2021-06-10T09:04:39.355258Z'
programId: 139
timezone:
type: string
description: A string containing an IANA timezone descriptor.
example: Europe/Berlin
minLength: 1
cardBased:
type: boolean
description: |
Defines the type of loyalty program:
- `true`: the program is a card-based.
- `false`: the program is profile-based.
default: false
example: true
canUpdateTiers:
type: boolean
description: |
`True` if the tier definitions can be updated.
default: false
example: true
canUpgradeToAdvancedTiers:
type: boolean
description: >
`True` if the program can be upgraded to use the `tiersExpireIn` and
`tiersDowngradePolicy` properties.
default: false
example: true
additionalProperties: false
LoyaltyTier:
type: object
description: ''
required:
- id
- created
- programID
- name
- minPoints
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
programID:
type: integer
description: The ID of the loyalty program that owns this entity.
example: 125
name:
type: string
description: The name of the tier
example: Gold
minPoints:
type: number
minimum: 0
maximum: 999999999999.99
exclusiveMaximum: false
description: The minimum amount of points required to be eligible for the tier.
example: 300
additionalProperties: false
NewLoyaltyTier:
type: object
description: A tier in a loyalty program.
required:
- name
- minPoints
properties:
name:
type: string
description: The name of the tier
example: Gold
minPoints:
type: number
minimum: 0
maximum: 999999999999.99
exclusiveMaximum: false
description: The minimum amount of points required to be eligible for the tier.
example: 300
BaseLoyaltyProgram:
type: object
properties:
title:
type: string
description: The display title for the Loyalty Program.
example: Point collection
description:
type: string
description: Description of our Loyalty Program.
example: Customers collect 10 points per 1$ spent
subscribedApplications:
type: array
description: >-
A list containing the IDs of all applications that are subscribed to
this Loyalty Program.
example:
- 132
- 97
items:
type: integer
defaultValidity:
type: string
description: >
The default duration after which new loyalty points should expire. Can
be 'unlimited' or a specific time.
The time format is a number followed by one letter indicating the time
unit, like '30s', '40m', '1h', '5D', '7W', or 10M'. These rounding
suffixes are also supported:
- '_D' for rounding down. Can be used as a suffix after 'D', and
signifies the start of the day.
- '_U' for rounding up. Can be used as a suffix after 'D', 'W', and
'M', and signifies the end of the day, week, and month.
example: 2W_U
defaultPending:
type: string
description: >
The default duration of the pending time after which points should be
valid. Can be 'immediate' or a specific time.
The time format is a number followed by one letter indicating the time
unit, like '30s', '40m', '1h', '5D', '7W', or 10M'. These rounding
suffixes are also supported:
- '_D' for rounding down. Can be used as a suffix after 'D', and
signifies the start of the day.
- '_U' for rounding up. Can be used as a suffix after 'D', 'W', and
'M', and signifies the end of the day, week, and month.
example: immediate
allowSubledger:
type: boolean
description: Indicates if this program supports subledgers inside the program.
example: false
usersPerCardLimit:
type: integer
minimum: 0
example: 111
description: >
The max amount of user profiles with whom a card can be shared. This
can be set to 0 for no limit.
This property is only used when `cardBased` is `true`.
sandbox:
type: boolean
description: >-
Indicates if this program is a live or sandbox program. Programs of a
given type can only be connected to Applications of the same type.
title: Sandbox
example: true
tiersExpireIn:
type: string
description: >
The amount of time until the expiration of every tier, starting from
the date when the customer joined the considered tier for the first
time.
The time format is an **integer** followed by one letter indicating
the time unit.
Examples: `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`.
Available units:
- `s`: seconds
- `m`: minutes
- `h`: hours
- `D`: days
- `W`: weeks
- `M`: months
- `Y`: years
You can round certain units up or down:
- `_D` for rounding down days only. Signifies the start of the day.
- `_U` for rounding up days, weeks, months and years. Signifies the
end of the day, week, month or year.
example: 27W_U
tiersDowngradePolicy:
type: string
enum:
- one_down
- balance_based
description: |
Customers's tier downgrade policy.
- `one_down`: Once the tier expires and if the user doesn't have enough points to stay in the tier, the user is downgraded one tier down.
- `balance_based`: Once the tier expires, the user's tier is evaluated based on the amount of active points the user has at this instant.
NewLoyaltyProgram:
type: object
description: ''
required:
- name
- title
- defaultValidity
- defaultPending
- allowSubledger
- timezone
- cardBased
- sandbox
properties:
title:
type: string
description: The display title for the Loyalty Program.
example: Point collection
description:
type: string
description: Description of our Loyalty Program.
example: Customers collect 10 points per 1$ spent
subscribedApplications:
type: array
description: >-
A list containing the IDs of all applications that are subscribed to
this Loyalty Program.
example:
- 132
- 97
items:
type: integer
defaultValidity:
type: string
description: >
The default duration after which new loyalty points should expire. Can
be 'unlimited' or a specific time.
The time format is a number followed by one letter indicating the time
unit, like '30s', '40m', '1h', '5D', '7W', or 10M'. These rounding
suffixes are also supported:
- '_D' for rounding down. Can be used as a suffix after 'D', and
signifies the start of the day.
- '_U' for rounding up. Can be used as a suffix after 'D', 'W', and
'M', and signifies the end of the day, week, and month.
example: 2W_U
defaultPending:
type: string
description: >
The default duration of the pending time after which points should be
valid. Can be 'immediate' or a specific time.
The time format is a number followed by one letter indicating the time
unit, like '30s', '40m', '1h', '5D', '7W', or 10M'. These rounding
suffixes are also supported:
- '_D' for rounding down. Can be used as a suffix after 'D', and
signifies the start of the day.
- '_U' for rounding up. Can be used as a suffix after 'D', 'W', and
'M', and signifies the end of the day, week, and month.
example: immediate
allowSubledger:
type: boolean
description: Indicates if this program supports subledgers inside the program.
example: false
usersPerCardLimit:
type: integer
minimum: 0
example: 111
description: >
The max amount of user profiles with whom a card can be shared. This
can be set to 0 for no limit.
This property is only used when `cardBased` is `true`.
sandbox:
type: boolean
description: >-
Indicates if this program is a live or sandbox program. Programs of a
given type can only be connected to Applications of the same type.
title: Sandbox
example: true
tiersExpireIn:
type: string
description: >
The amount of time until the expiration of every tier, starting from
the date when the customer joined the considered tier for the first
time.
The time format is an **integer** followed by one letter indicating
the time unit.
Examples: `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`.
Available units:
- `s`: seconds
- `m`: minutes
- `h`: hours
- `D`: days
- `W`: weeks
- `M`: months
- `Y`: years
You can round certain units up or down:
- `_D` for rounding down days only. Signifies the start of the day.
- `_U` for rounding up days, weeks, months and years. Signifies the
end of the day, week, month or year.
example: 27W_U
tiersDowngradePolicy:
type: string
enum:
- one_down
- balance_based
description: |
Customers's tier downgrade policy.
- `one_down`: Once the tier expires and if the user doesn't have enough points to stay in the tier, the user is downgraded one tier down.
- `balance_based`: Once the tier expires, the user's tier is evaluated based on the amount of active points the user has at this instant.
name:
type: string
description: The internal name for the Loyalty Program. This is an immutable value.
example: GeneralPointCollection
tiers:
type: array
description: The tiers in this loyalty program.
items:
$ref: '#/definitions/NewLoyaltyTier'
timezone:
type: string
description: A string containing an IANA timezone descriptor.
minLength: 1
cardBased:
type: boolean
description: |
Defines the type of loyalty program:
- `true`: the program is a card-based.
- `false`: the program is profile-based.
default: false
example: true
additionalProperties: false
UpdateLoyaltyProgram:
type: object
description: ''
properties:
title:
type: string
description: The display title for the Loyalty Program.
example: Point collection
description:
type: string
description: Description of our Loyalty Program.
example: Customers collect 10 points per 1$ spent
subscribedApplications:
type: array
description: >-
A list containing the IDs of all applications that are subscribed to
this Loyalty Program.
example:
- 132
- 97
items:
type: integer
defaultValidity:
type: string
description: >
The default duration after which new loyalty points should expire. Can
be 'unlimited' or a specific time.
The time format is a number followed by one letter indicating the time
unit, like '30s', '40m', '1h', '5D', '7W', or 10M'. These rounding
suffixes are also supported:
- '_D' for rounding down. Can be used as a suffix after 'D', and
signifies the start of the day.
- '_U' for rounding up. Can be used as a suffix after 'D', 'W', and
'M', and signifies the end of the day, week, and month.
example: 2W_U
defaultPending:
type: string
description: >
The default duration of the pending time after which points should be
valid. Can be 'immediate' or a specific time.
The time format is a number followed by one letter indicating the time
unit, like '30s', '40m', '1h', '5D', '7W', or 10M'. These rounding
suffixes are also supported:
- '_D' for rounding down. Can be used as a suffix after 'D', and
signifies the start of the day.
- '_U' for rounding up. Can be used as a suffix after 'D', 'W', and
'M', and signifies the end of the day, week, and month.
example: immediate
allowSubledger:
type: boolean
description: Indicates if this program supports subledgers inside the program.
example: false
usersPerCardLimit:
type: integer
minimum: 0
example: 111
description: >
The max amount of user profiles with whom a card can be shared. This
can be set to 0 for no limit.
This property is only used when `cardBased` is `true`.
sandbox:
type: boolean
description: >-
Indicates if this program is a live or sandbox program. Programs of a
given type can only be connected to Applications of the same type.
title: Sandbox
example: true
tiersExpireIn:
type: string
description: >
The amount of time until the expiration of every tier, starting from
the date when the customer joined the considered tier for the first
time.
The time format is an **integer** followed by one letter indicating
the time unit.
Examples: `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`.
Available units:
- `s`: seconds
- `m`: minutes
- `h`: hours
- `D`: days
- `W`: weeks
- `M`: months
- `Y`: years
You can round certain units up or down:
- `_D` for rounding down days only. Signifies the start of the day.
- `_U` for rounding up days, weeks, months and years. Signifies the
end of the day, week, month or year.
example: 27W_U
tiersDowngradePolicy:
type: string
enum:
- one_down
- balance_based
description: |
Customers's tier downgrade policy.
- `one_down`: Once the tier expires and if the user doesn't have enough points to stay in the tier, the user is downgraded one tier down.
- `balance_based`: Once the tier expires, the user's tier is evaluated based on the amount of active points the user has at this instant.
tiers:
type: array
description: The tiers in this loyalty program.
items:
$ref: '#/definitions/NewLoyaltyTier'
additionalProperties: false
LoyaltyLedgerTransactions:
type: object
description: List of loyalty ledger transactions.
properties:
hasMore:
type: boolean
description: true means there is more data in the source collection to request.
example: true
data:
description: List of transaction entries from a loyalty ledger.
type: array
items:
$ref: '#/definitions/LoyaltyLedgerEntry'
LoyaltyLedgerEntry:
type: object
description: 'A single row of the ledger, describing one addition or deduction.'
required:
- programID
- type
- amount
- created
- name
- subLedgerID
properties:
created:
type: string
format: date-time
example: '2021-07-20T22:00:00Z'
programID:
type: integer
example: 5
customerProfileID:
type: string
example: URNGV8294NV
cardID:
type: integer
example: 241
customerSessionID:
type: string
example: t2gy5s-47274
eventID:
type: integer
example: 5
type:
type: string
description: |
The type of the ledger transaction. Possible values are:
- `addition`
- `subtraction`
- `expire`
- `expiring` (for expiring points ledgers)
example: addition
amount:
type: number
example: 100
startDate:
type: string
format: date-time
example: '2021-07-20T22:00:00Z'
expiryDate:
type: string
format: date-time
example: '2022-07-20T22:00:00Z'
name:
type: string
description: >-
A name referencing the condition or effect that added this entry, or
the specific name provided in an API call.
example: Add points on purchase
subLedgerID:
type: string
description: >-
This specifies if we are adding loyalty points to the main ledger or a
subledger.
example: mysubledger
userID:
type: integer
description: >-
This is the ID of the user who created this entry, if the addition or
subtraction was done manually.
example: 499
archived:
type: boolean
description: Indicates if the entry belongs to the archived session.
example: false
LoyaltyBalances:
type: object
description: List of loyalty balances for a ledger and its subledgers.
properties:
balance:
title: Loyalty points balance of a ledger
$ref: '#/definitions/LoyaltyBalance'
subledgerBalances:
type: object
description: Map of the loyalty balances of the subledgers of a ledger.
additionalProperties:
$ref: '#/definitions/LoyaltyBalance'
example:
mysubledger:
activePoints: 286
pendingPoints: 50
spentPoints: 150
expiredPoints: 25
LoyaltyBalance:
type: object
description: Point balance of a ledger in the Loyalty Program.
properties:
activePoints:
type: number
title: Current Balance
description: >-
Total amount of points awarded to this customer and available to
spend.
example: 286
pendingPoints:
type: number
title: Total pending points
description: >-
Total amount of points awarded to this customer but not available
until their start date.
example: 50
spentPoints:
type: number
title: Total spent points
description: Total amount of points already spent by this customer.
example: 150
expiredPoints:
type: number
title: Total expired points
description: >-
Total amount of points awarded but never redeemed. They cannot be used
anymore.
example: 286
LoyaltyLedger:
type: object
description: Ledger of Balance in Loyalty Program for a Customer.
required:
- ledger
properties:
ledger:
title: Customer's current loyalty program balance.
description: The balance of the main ledger in the loyalty program.
$ref: '#/definitions/LoyaltySubLedger'
subLedgers:
type: object
description: A map containing a list of all loyalty subledger balances.
additionalProperties:
$ref: '#/definitions/LoyaltySubLedger'
example:
mysubledger:
activePoints: 286
pendingPoints: 50
spentPoints: 150
expiredPoints: 25
LoyaltySubLedger:
type: object
description: Ledger of Balance in Loyalty Program for a Customer.
required:
- total
- totalActivePoints
- totalPendingPoints
- totalSpentPoints
- totalExpiredPoints
properties:
total:
type: number
title: Current Balance (Deprecated)
description: >
**DEPRECATED** Use `totalActivePoints` property instead. Total amount
of currently active and available points in the customer's balance.
totalActivePoints:
type: number
title: Current Balance
description: >-
Total amount of currently active and available points in the
customer's balance.
totalPendingPoints:
type: number
title: Total pending points
description: >-
Total amount of pending points, which are not active yet but will
become active in the future.
totalSpentPoints:
type: number
title: Total spent points
description: Total amount of points already spent by this customer.
totalExpiredPoints:
type: number
title: Total expired points
description: 'Total amount of points, that expired without ever being spent.'
transactions:
description: >-
List of all events that have happened such as additions, subtractions
and expiries.
type: array
items:
$ref: '#/definitions/LoyaltyLedgerEntry'
expiringPoints:
description: List of all points that will expire.
type: array
items:
$ref: '#/definitions/LoyaltyLedgerEntry'
activePoints:
description: List of all currently active points.
type: array
items:
$ref: '#/definitions/LoyaltyLedgerEntry'
pendingPoints:
description: List of all points pending activation.
type: array
items:
$ref: '#/definitions/LoyaltyLedgerEntry'
expiredPoints:
description: List of expired points.
type: array
items:
$ref: '#/definitions/LoyaltyLedgerEntry'
currentTier:
description: Tier for which the ledger is eligible.
$ref: '#/definitions/Tier'
Loyalty:
type: object
description: Customer-specific information about loyalty points.
required:
- programs
properties:
cards:
title: Point balances of the loyalty cards used.
description: Displays information about the balances of the loyalty cards.
type: array
items:
$ref: '#/definitions/LoyaltyCard'
programs:
type: object
title: Customer's current loyalty program balance.
description: Displays information about point balances in profile-based programs.
additionalProperties:
$ref: '#/definitions/LoyaltyProgramLedgers'
LoyaltyProgramLedgers:
type: object
description: Customer-specific information about loyalty points.
required:
- ledger
- title
- name
- id
properties:
id:
type: integer
description: The internal ID of loyalty program.
example: 5
title:
description: Visible name of loyalty program.
type: string
example: My loyalty program
name:
description: Internal name of loyalty program.
type: string
example: program1
ledger:
title: Customer's current loyalty program status
description: Information about the main ledger in the loyalty program.
$ref: '#/definitions/LedgerInfo'
subLedgers:
type: object
description: A map containing information about each loyalty subledger.
additionalProperties:
$ref: '#/definitions/LedgerInfo'
LedgerInfo:
type: object
description: ''
required:
- currentBalance
- pendingBalance
- expiredBalance
- spentBalance
- tentativeCurrentBalance
properties:
currentBalance:
type: number
title: Current balance
description: Sum of currently active points.
example: 100
pendingBalance:
type: number
title: Pending balance
description: Sum of pending points.
example: 10
expiredBalance:
type: number
title: Expired balance
description: |
**DEPRECATED** Value is shown as 0.
example: 0
spentBalance:
type: number
title: Spent balance
description: |
**DEPRECATED** Value is shown as 0.
example: 0
tentativeCurrentBalance:
type: number
title: Tentative current balance
description: >-
Sum of the tentative active points (including additions and
deductions) inside the currently open session. The `currentBalance` is
updated to this value when you close the session, and the effects are
applied.
example: 100
tentativePendingBalance:
type: number
title: Tentative pending balance
description: >-
Sum of pending points (including additions and deductions) inside the
currently open session. The `pendingBalance` is updated to this value
when you close the session, and the effects are applied.
example: 20
currentTier:
$ref: '#/definitions/Tier'
description: Tier for which the ledger is eligible.
example: bronze
pointsToNextTier:
type: number
description: Points required to move up a tier.
example: 20
additionalProperties: false
LoyaltyProgramSubledgers:
type: object
description: The list of all the subledgers that the loyalty program has.
required:
- loyaltyProgramId
- subledgerIds
properties:
loyaltyProgramId:
type: integer
description: The internal ID of the loyalty program.
example: 5
subledgerIds:
type: array
description: The list of subledger IDs.
items:
type: string
Tier:
type: object
required:
- id
- name
properties:
id:
type: integer
description: The internal ID of the tier.
example: 11
name:
type: string
description: The name of the tier.
example: bronze
expiryDate:
type: string
format: date-time
description: >-
Date when tier level expires in the RFC3339 format (in the Loyalty
Program's timezone).
example: '2022-08-02T15:04:05Z07:00'
downgradePolicy:
type: string
enum:
- one_down
- balance_based
description: >
Customers's tier downgrade policy.
- `one_down`: Once the tier expires and if the user doesn't have
enough points to stay in the tier, the user is downgraded one tier
down.
- `balance_based`: Once the tier expires, the user's tier is evaluated
based on the amount of active points the user has at this instant.
TimePoint:
type: object
required:
- hour
- minute
- second
description: >-
The absolute duration after which the achievement is reset for a
particular customer profile.
properties:
month:
type: integer
minimum: 1
maximum: 12
description: |
The achievement is reset in this month.
**Note**: Only applicable if the period is set to `Y`.
example: 11
dayOfMonth:
type: integer
minimum: 1
maximum: 28
description: |
The achievement is reset on this day of the month.
**Note**: Only applicable if the period is set to `Y` or `M`.
example: 23
dayOfWeek:
type: integer
minimum: 1
maximum: 7
description: >
The achievement is reset on this day of the week. `1` represents
`Monday` and `7` represents `Sunday`.
**Note**: Only applicable if the period is set to `W`.
hour:
type: integer
description: The achievement is reset at this hour.
example: 23
minute:
type: integer
description: The achievement is reset at this minute.
example: 59
second:
type: integer
description: The achievement is reset at this second.
example: 59
example:
month: 11
dayOfMonth: 23
hour: 23
minute: 59
second: 59
LoyaltyCard:
type: object
description: ''
required:
- id
- created
- programID
- status
- identifier
- usersPerCardLimit
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
programID:
type: integer
description: The ID of the loyalty program that owns this entity.
example: 125
status:
type: string
description: |
Status of the loyalty card. Can be one of: ['active', 'inactive']
example: active
identifier:
$ref: '#/definitions/LoyaltyCardIdentifier'
usersPerCardLimit:
type: integer
minimum: 0
example: 111
description: >
The max amount of customer profiles that can be linked to the card. 0
means unlimited.
profiles:
type: array
description: Integration IDs of the customers profiles linked to the card.
items:
$ref: '#/definitions/LoyaltyCardProfileRegistration'
ledger:
description: >-
Displays point balances of the card in the main ledger of the loyalty
program.
$ref: '#/definitions/LedgerInfo'
subledgers:
type: object
description: >-
Displays point balances of the card in the subledgers of the loyalty
program.
additionalProperties:
$ref: '#/definitions/LedgerInfo'
modified:
type: string
format: date-time
description: Timestamp of the most recent update of the loyalty card.
example: '2021-09-12T10:12:42Z'
oldCardIdentifier:
description: The identifier of the card from which the points were transferred.
$ref: '#/definitions/LoyaltyCardIdentifier'
example: summer-loyalty-card-0543
newCardIdentifier:
description: The identifier of the card to which the points were transferred.
$ref: '#/definitions/LoyaltyCardIdentifier'
example: autumn-loyalty-card-5822
additionalProperties: false
LoyaltyCardIdentifier:
type: string
description: |
The alphanumeric identifier of the loyalty card.
maxLength: 108
example: summer-loyalty-card-0543
CardLedgerTransactionLogEntry:
type: object
description: Log entry for a given loyalty card transaction.
required:
- created
- programId
- cardIdentifier
- type
- name
- startDate
- expiryDate
- subledgerId
- amount
- id
properties:
created:
type: string
format: date-time
description: Date and time the loyalty card transaction occurred.
example: '2022-01-02T15:04:05Z07:00'
programId:
type: integer
description: ID of the loyalty program.
example: 324
cardIdentifier:
$ref: '#/definitions/LoyaltyCardIdentifier'
applicationId:
type: integer
description: The ID of the Application that owns this entity.
example: 322
sessionId:
description: |
The **internal** ID of the session.
type: integer
example: 233
customerSessionId:
type: string
description: ID of the customer session where the transaction occurred.
maxLength: 255
example: 05c2da0d-48fa-4aa1-b629-898f58f1584d
type:
type: string
enum:
- addition
- subtraction
description: |
Type of transaction. Possible values:
- `addition`: Signifies added points.
- `subtraction`: Signifies deducted points.
maxLength: 255
example: addition
name:
type: string
description: Name or reason of the loyalty ledger transaction.
maxLength: 255
example: Reward 10% points of a purchase's current total
startDate:
type: string
description: |
When points become active. Possible values:
- `immediate`: Points are immediately active.
- a timestamp value: Points become active at a given date and time.
maxLength: 64
example: '2022-01-02T15:04:05Z07:00'
expiryDate:
type: string
description: |
Date when points expire. Possible values are:
- `unlimited`: Points have no expiration date.
- `timestamp value`: Points become active from the given date.
example: '2022-08-02T15:04:05Z07:00'
subledgerId:
type: string
description: ID of the subledger.
maxLength: 64
example: sub-123
amount:
type: number
description: Amount of loyalty points added or deducted in the transaction.
example: 10.25
id:
type: integer
description: ID of the loyalty ledger entry.
example: 123
CardLedgerTransactionLogEntryIntegrationAPI:
type: object
description: Log entry for a given loyalty card transaction.
required:
- created
- programId
- cardIdentifier
- type
- name
- startDate
- expiryDate
- subledgerId
- amount
- id
properties:
created:
type: string
format: date-time
description: Date and time the loyalty card transaction occurred.
example: '2022-01-02T15:04:05Z07:00'
programId:
type: integer
description: ID of the loyalty program.
example: 324
cardIdentifier:
$ref: '#/definitions/LoyaltyCardIdentifier'
customerSessionId:
type: string
description: ID of the customer session where the transaction occurred.
maxLength: 255
example: 05c2da0d-48fa-4aa1-b629-898f58f1584d
type:
type: string
enum:
- addition
- subtraction
description: |
Type of transaction. Possible values:
- `addition`: Signifies added points.
- `subtraction`: Signifies deducted points.
maxLength: 255
example: addition
name:
type: string
description: Name or reason of the loyalty ledger transaction.
maxLength: 255
example: Reward 10% points of a purchase's current total
startDate:
type: string
description: |
When points become active. Possible values:
- `immediate`: Points are active immediately.
- a timestamp value: Points become active at a given date and time.
maxLength: 64
example: '2022-01-02T15:04:05Z07:00'
expiryDate:
type: string
description: |
Date when points expire. Possible values are:
- `unlimited`: Points have no expiration date.
- `timestamp value`: Points expire on the given date.
example: '2022-08-02T15:04:05Z07:00'
subledgerId:
type: string
description: ID of the subledger.
maxLength: 64
example: sub-123
amount:
type: number
description: Amount of loyalty points added or deducted in the transaction.
example: 10.25
id:
type: integer
description: ID of the loyalty ledger transaction.
example: 123
rulesetId:
type: integer
description: The ID of the ruleset containing the rule that triggered this effect.
example: 11
ruleName:
type: string
description: The name of the rule that triggered this effect.
example: Add 2 points
LedgerTransactionLogEntryIntegrationAPI:
type: object
description: Log entry for a given loyalty card transaction.
required:
- created
- programId
- type
- name
- startDate
- expiryDate
- subledgerId
- amount
- id
properties:
created:
type: string
format: date-time
description: Date and time the loyalty transaction occurred.
example: '2022-01-02T15:04:05Z07:00'
programId:
type: integer
description: ID of the loyalty program.
example: 324
customerSessionId:
type: string
description: ID of the customer session where the transaction occurred.
maxLength: 255
example: 05c2da0d-48fa-4aa1-b629-898f58f1584d
type:
type: string
enum:
- addition
- subtraction
description: |
Type of transaction. Possible values:
- `addition`: Signifies added points.
- `subtraction`: Signifies deducted points.
maxLength: 255
example: addition
name:
type: string
description: Name or reason of the loyalty ledger transaction.
maxLength: 255
example: Reward 10% points of a purchase's current total
startDate:
type: string
description: |
When points become active. Possible values:
- `immediate`: Points are immediately active.
- a timestamp value: Points become active at a given date and time.
maxLength: 64
example: '2022-01-02T15:04:05Z07:00'
expiryDate:
type: string
description: |
Date when points expire. Possible values are:
- `unlimited`: Points have no expiration date.
- `timestamp value`: Points expire on the given date.
example: '2022-08-02T15:04:05Z07:00'
subledgerId:
type: string
description: ID of the subledger.
maxLength: 64
example: sub-123
amount:
type: number
description: Amount of loyalty points added or deducted in the transaction.
example: 10.25
id:
type: integer
description: ID of the loyalty ledger transaction.
example: 123
rulesetId:
type: integer
description: The ID of the ruleset containing the rule that triggered this effect.
example: 11
ruleName:
type: string
description: The name of the rule that triggered this effect.
example: Add 2 points
CardLedgerPointsEntryIntegrationAPI:
type: object
description: Loyalty card points with start and expiry dates.
required:
- id
- created
- programId
- name
- startDate
- expiryDate
- subledgerId
- amount
properties:
id:
type: integer
description: ID of the transaction that adds loyalty points.
example: 123
created:
type: string
format: date-time
description: Date and time the loyalty card points were added.
example: '2022-01-02T15:04:05Z07:00'
programId:
type: integer
description: ID of the loyalty program.
example: 324
customerProfileID:
type: string
description: Integration ID of the customer profile linked to the card.
example: URNGV8294NV
customerSessionId:
type: string
description: ID of the customer session where points were added.
maxLength: 255
example: 05c2da0d-48fa-4aa1-b629-898f58f1584d
name:
type: string
description: Name or reason of the transaction that adds loyalty points.
maxLength: 255
example: Reward 10% points of a purchase's current total
startDate:
type: string
description: |
When points become active. Possible values:
- `immediate`: Points are active immediately.
- `timestamp value`: Points become active at a given date and time.
maxLength: 64
example: '2022-01-02T15:04:05Z07:00'
expiryDate:
type: string
description: |
Date when points expire. Possible values are:
- `unlimited`: Points have no expiration date.
- `timestamp value`: Points expire on the given date and time.
example: '2022-08-02T15:04:05Z07:00'
subledgerId:
type: string
description: ID of the subledger.
maxLength: 64
example: sub-123
amount:
type: number
description: Amount of loyalty points added in the transaction.
example: 10.25
LedgerPointsEntryIntegrationAPI:
type: object
description: Loyalty profile points with start and expiry dates.
required:
- id
- created
- programId
- name
- startDate
- expiryDate
- subledgerId
- amount
properties:
id:
type: integer
description: ID of the transaction that adds loyalty points.
example: 123
created:
type: string
format: date-time
description: Date and time the loyalty points were added.
example: '2022-01-02T15:04:05Z07:00'
programId:
type: integer
description: ID of the loyalty program.
example: 324
customerSessionId:
type: string
description: ID of the customer session where points were added.
maxLength: 255
example: 05c2da0d-48fa-4aa1-b629-898f58f1584d
name:
type: string
description: Name or reason of the transaction that adds loyalty points.
maxLength: 255
example: Reward 10% points of a purchase's current total
startDate:
type: string
description: |
When points become active. Possible values:
- `immediate`: Points are active immediately.
- `timestamp value`: Points become active at a given date and time.
maxLength: 64
example: '2022-01-02T15:04:05Z07:00'
expiryDate:
type: string
description: |
Date when points expire. Possible values are:
- `unlimited`: Points have no expiration date.
- `timestamp value`: Points expire on the given date and time.
example: '2022-08-02T15:04:05Z07:00'
subledgerId:
type: string
description: ID of the subledger.
maxLength: 64
example: sub-123
amount:
type: number
description: Amount of loyalty points added in the transaction.
example: 10.25
LoyaltyProgramTransaction:
type: object
required:
- id
- created
- programId
- type
- amount
- name
- subledgerId
- startDate
- expiryDate
properties:
id:
type: integer
description: ID of the loyalty ledger transaction.
example: 123
programId:
type: integer
description: ID of the loyalty program.
example: 324
created:
type: string
format: date-time
description: Date and time the loyalty transaction occurred.
example: '2022-01-02T15:04:05Z07:00'
type:
type: string
enum:
- addition
- subtraction
description: |
Type of transaction. Possible values:
- `addition`: Signifies added points.
- `subtraction`: Signifies deducted points.
maxLength: 255
example: addition
amount:
type: number
description: Amount of loyalty points added or deducted in the transaction.
example: 10.25
name:
type: string
description: Name or reason for the loyalty ledger transaction.
maxLength: 255
example: Reward 50 points for each $500 purchase
startDate:
type: string
description: |
When points become active. Possible values:
- `immediate`: Points are immediately active.
- a timestamp value: Points become active at a given date and time.
maxLength: 64
example: '2022-01-02T15:04:05Z07:00'
expiryDate:
type: string
description: |
When points expire. Possible values:
- `unlimited`: Points have no expiration date.
- a timestamp value: Points expire at a given date and time.
example: '2022-01-02T15:04:05Z07:00'
customerProfileId:
type: string
description: Customer profile integration ID used in the loyalty program.
maxLength: 255
example: kda0fajs0-fad9f-fd9dfsa9-fd9dasjf9
cardIdentifier:
$ref: '#/definitions/LoyaltyCardIdentifier'
subledgerId:
type: string
description: ID of the subledger.
maxLength: 64
example: sub-123
customerSessionId:
type: string
description: ID of the customer session where the transaction occurred.
maxLength: 255
example: 05c2da0d-48fa-4aa1-b629-898f58f1584d
importId:
type: integer
description: ID of the import where the transaction occurred.
example: 4
userId:
type: integer
description: >-
ID of the user who manually added or deducted points. Applies only to
manual transactions.
example: 5
userEmail:
type: string
description: >-
The email of the Campaign Manager account that manually added or
deducted points. Applies only to manual transactions.
example: john.doe@example.com
rulesetId:
type: integer
description: >-
ID of the ruleset containing the rule that triggered the effect.
Applies only for transactions that resulted from a customer session.
example: 11
ruleName:
type: string
description: >-
Name of the rule that triggered the effect. Applies only for
transactions that resulted from a customer session.
example: 10 points for every $100 spent
TransferLoyaltyCard:
type: object
required:
- newCardIdentifier
properties:
newCardIdentifier:
$ref: '#/definitions/LoyaltyCardIdentifier'
UpdateLoyaltyCard:
type: object
required:
- status
properties:
status:
type: string
description: |
Status of the loyalty card. Can be one of: ['active', 'inactive']
example: active
LoyaltyCardProfileRegistration:
type: object
required:
- integrationId
- timestamp
properties:
integrationId:
type: string
maxLength: 1000
description: Integration ID of the customer profile linked to the card.
example: R195412
timestamp:
type: string
format: date-time
description: Timestamp of the registration to the card.
example: '2021-09-12T10:12:42Z'
LoyaltyCardRegistration:
type: object
required:
- integrationId
properties:
integrationId:
type: string
title: Customer Profile ID
description: The integrationId of the customer profile.
example: R195412
LoyaltyProgramBalance:
type: object
required:
- currentBalance
- pendingBalance
- expiredBalance
- spentBalance
- tentativeCurrentBalance
description: The balance in a Loyalty Program for some Customer.
properties:
currentBalance:
type: number
title: Current balance
description: Sum of currently active points.
example: 100
pendingBalance:
type: number
title: Pending balance
description: Sum of pending points.
example: 10
expiredBalance:
type: number
title: Expired balance
description: |
**DEPRECATED** Value is shown as 0.
example: 0
spentBalance:
type: number
title: Spent balance
description: |
**DEPRECATED** Value is shown as 0.
example: 0
tentativeCurrentBalance:
type: number
title: Tentative current balance
description: >-
Sum of the tentative active points (including additions and
deductions) inside the currently open session. The `currentBalance` is
updated to this value when you close the session, and the effects are
applied.
example: 100
tentativePendingBalance:
type: number
title: Tentative pending balance
description: >-
Sum of pending points (including additions and deductions) inside the
currently open session. The `pendingBalance` is updated to this value
when you close the session, and the effects are applied.
example: 20
CustomerProfileSearchQuery:
type: object
properties:
attributes:
type: object
description: >-
Properties to match against a customer profile. All provided
attributes will be exactly matched against profile attributes.
additionalProperties: true
integrationIDs:
type: array
items:
type: string
profileIDs:
type: array
items:
type: integer
NewCustomerProfile:
type: object
properties:
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
example:
Language: english
ShippingCountry: DE
EvaluableCampaignIds:
type: object
properties:
evaluableCampaignIds:
type: array
items:
type: integer
maxLength: 999
description: >
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.
title: Campaigns to evaluate
example:
- 10
- 12
CustomerProfile:
type: object
description: ''
required:
- id
- created
- integrationId
- accountId
- closedSessions
- totalSales
- lastActivity
- attributes
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
description: The time this entity was created. The time this entity was created.
format: date-time
integrationId:
type: string
format: string
example: URNGV8294NV
maxLength: 1000
description: The integration ID set by your integration layer.
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
example:
Language: english
ShippingCountry: DE
accountId:
type: integer
title: Profile belongs to Account
description: The ID of the Talon.One account that owns this profile.
example: 31
closedSessions:
type: integer
title: Closed sessions
description: >-
The total amount of closed sessions by a customer. A closed session is
a successful purchase.
example: 3
totalSales:
type: number
description: >
The total amount of money spent by the customer **before** discounts
are applied.
The total sales amount excludes the following:
- Cancelled or reopened sessions.
- Returned items.
example: 299.99
title: Total Sales
loyaltyMemberships:
type: array
description: |
**DEPRECATED** A list of loyalty programs joined by the customer.
items:
$ref: '#/definitions/LoyaltyMembership'
title: Loyalty programed joined
audienceMemberships:
type: array
description: The audiences the customer belongs to.
items:
$ref: '#/definitions/AudienceMembership'
title: Audience memberships
lastActivity:
type: string
format: date-time
title: Last activity
description: >
Timestamp of the most recent event received from this customer.
This field is updated on calls that trigger the Rule Engine and that
are
not [dry
requests](https://docs.talon.one/docs/dev/integration-api/dry-requests/#overlay).
For example, [reserving a
coupon](https://docs.talon.one/integration-api#operation/createCouponReservation)
for a customer doesn't impact this field.
example: '2020-02-08T14:15:20Z'
sandbox:
type: boolean
description: >
Shows whether the customer is part of a sandbox or live Application.
See the
[docs](https://docs.talon.one/docs/product/applications/overview#application-environments).
title: Sandbox
example: false
additionalProperties: false
CustomerInventory:
type: object
properties:
profile:
$ref: '#/definitions/CustomerProfile'
loyalty:
$ref: '#/definitions/Loyalty'
referrals:
type: array
items:
$ref: '#/definitions/InventoryReferral'
coupons:
type: array
description: >
The coupons reserved by this profile. This array includes hard and
soft reservations. See each coupon's `reservation` property.
items:
$ref: '#/definitions/InventoryCoupon'
giveaways:
type: array
items:
$ref: '#/definitions/Giveaway'
NewCustomerSession:
type: object
description: ''
properties:
profileId:
type: string
description: >
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`.
example: URNGV8294NV
coupon:
type: string
maxLength: 100
description: Any coupon code entered.
title: Coupon entered in session
example: XMAS-2021
referral:
type: string
maxLength: 100
description: Any referral code entered.
title: Referral code entered in session
example: 2740-tbjua-6720
state:
type: string
enum:
- open
- closed
- partially_returned
- cancelled
default: open
example: open
description: >
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. `closed` → `cancelled` or `partially_returned`
4. `partially_returned` → `cancelled`
For more information, see [Customer session
states](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).
title: Customer's session state
cartItems:
type: array
description: Serialized JSON representation.
title: Items in customer's cart
items:
$ref: '#/definitions/CartItem'
identifiers:
type: array
maxItems: 5
items:
type: string
title: Session identifiers
description: >
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](https://docs.talon.one/docs/dev/tutorials/using-identifiers).
example:
- 91.11.156.141
total:
type: number
title: Session Total
description: The total sum of the cart in one session.
attributes:
type: object
description: >
A key-value map of the sessions attributes. The potentially valid
attributes are configured in your accounts developer settings.
additionalProperties: true
additionalProperties: false
NewCustomerSessionV2:
type: object
description: The representation of the customer session.
properties:
profileId:
type: string
description: >
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`.
example: URNGV8294NV
storeIntegrationId:
type: string
minLength: 1
maxLength: 1000
description: >-
The integration ID of the store. You choose this ID when you create a
store.
example: STORE-001
evaluableCampaignIds:
type: array
items:
type: integer
maxLength: 999
description: >
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.
title: Campaigns to evaluate
example:
- 10
- 12
couponCodes:
type: array
items:
type: string
maxLength: 100
description: >
Any coupon codes entered.
**Important**: If you [create a coupon
budget](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets/#budget-types)
for your campaign, ensure the session contains a coupon code by the
time you close it.
title: Coupons entered in session
example:
- XMAS-20-2021
referralCode:
type: string
description: >
Any referral code entered.
**Important**: If you [create a referral
budget](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets/#budget-types)
for your campaign, ensure the session contains a referral code by the
time you close it.
title: Referral code entered in session
maxLength: 100
example: NT2K54D9
loyaltyCards:
type: array
maxItems: 1
items:
type: string
description: Any loyalty cards used.
example:
- loyalty-card-1
state:
type: string
enum:
- open
- closed
- partially_returned
- cancelled
default: open
example: open
description: >
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:
- `closed` → `cancelled` (**only** via [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)) or
- `closed` → `partially_returned` (**only** via [Return cart items](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/returnCartItems))
- `closed` → `open` (**only** via [Reopen customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/reopenCustomerSession))
4. `partially_returned` → `cancelled`
For more information, see [Customer session
states](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).
title: Customer's session state
cartItems:
type: array
description: >
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.
title: Customer session's cart items
items:
$ref: '#/definitions/CartItem'
additionalCosts:
type: object
description: >
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](https://docs.talon.one/docs/product/account/dev-tools/managing-additional-costs).
additionalProperties:
$ref: '#/definitions/AdditionalCost'
example:
shipping:
price: 9
identifiers:
type: array
maxItems: 5
items:
type: string
title: Session identifiers
description: >
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](https://docs.talon.one/docs/dev/tutorials/using-identifiers).
**Important**: Ensure the session contains an identifier by the time
you close it if:
- You [create a unique identifier
budget](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets/#budget-types)
for your campaign.
- Your campaign has
[coupons](https://docs.talon.one/docs/product/campaigns/coupons/coupon-page-overview).
example:
- 91.11.156.141
attributes:
type: object
description: >
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](https://docs.talon.one/docs/dev/concepts/attributes#built-in-attributes)
or [custom
ones](https://docs.talon.one/docs/dev/concepts/attributes#custom-attributes).
Custom attributes must be created in the Campaign Manager before you
set them with this property.
additionalProperties: true
example:
ShippingCity: Berlin
additionalProperties: false
CustomerAnalytics:
type: object
description: A summary report of customer activity for a given time range.
required:
- acceptedCoupons
- createdCoupons
- freeItems
- totalOrders
- totalDiscountedOrders
- totalRevenue
- totalDiscounts
properties:
acceptedCoupons:
type: integer
description: Total accepted coupons for this customer.
createdCoupons:
type: integer
description: Total created coupons for this customer.
freeItems:
type: integer
description: Total free items given to this customer.
totalOrders:
type: integer
description: Total orders made by this customer.
totalDiscountedOrders:
type: integer
description: Total orders made by this customer that had a discount.
totalRevenue:
type: number
description: Total Revenue across all closed sessions.
totalDiscounts:
type: number
description: The sum of discounts that were given across all closed sessions.
additionalProperties: false
CustomerActivityReport:
type: object
description: A summary report of customer activity for a given time range.
required:
- integrationId
- created
- name
- customerId
- couponRedemptions
- couponUseAttempts
- couponFailedAttempts
- accruedDiscounts
- accruedRevenue
- totalOrders
- totalOrdersNoCoupon
- campaignName
properties:
integrationId:
type: string
format: string
example: URNGV8294NV
maxLength: 1000
description: The integration ID set by your integration layer.
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-02-07T08:15:22Z'
name:
type: string
description: The name for this customer profile.
customerId:
type: integer
description: The internal Talon.One ID of the customer.
lastActivity:
type: string
format: date-time
description: The last activity of the customer.
couponRedemptions:
type: integer
description: Number of coupon redemptions in all customer campaigns.
couponUseAttempts:
type: integer
description: Number of coupon use attempts in all customer campaigns.
couponFailedAttempts:
type: integer
description: Number of failed coupon use attempts in all customer campaigns.
accruedDiscounts:
type: number
description: Number of accrued discounts in all customer campaigns.
accruedRevenue:
type: number
description: Amount of accrued revenue in all customer campaigns.
totalOrders:
type: integer
description: Number of orders in all customer campaigns.
totalOrdersNoCoupon:
type: integer
description: Number of orders without coupon used in all customer campaigns.
campaignName:
type: string
description: The name of the campaign this customer belongs to.
additionalProperties: false
CustomerSession:
type: object
description: ''
required:
- integrationId
- created
- applicationId
- profileId
- firstSession
- coupon
- referral
- state
- cartItems
- attributes
- discounts
- total
- updated
properties:
integrationId:
type: string
description: The integration ID set by your integration layer.
maxLength: 1000
format: string
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-02-07T08:15:22Z'
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
profileId:
type: string
description: >
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`.
example: URNGV8294NV
coupon:
type: string
maxLength: 100
description: Any coupon code entered.
title: Coupon entered in session
example: XMAS-2021
referral:
type: string
maxLength: 100
description: Any referral code entered.
title: Referral code entered in session
example: 2740-tbjua-6720
state:
type: string
enum:
- open
- closed
- partially_returned
- cancelled
default: open
example: open
description: >
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. `closed` → `cancelled` or `partially_returned`
4. `partially_returned` → `cancelled`
For more information, see [Customer session
states](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).
title: Customer's session state
cartItems:
type: array
description: Serialized JSON representation.
title: Items in customer's cart
items:
$ref: '#/definitions/CartItem'
identifiers:
type: array
maxItems: 5
items:
type: string
title: Session identifiers
description: >
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](https://docs.talon.one/docs/dev/tutorials/using-identifiers).
example:
- 91.11.156.141
total:
type: number
title: Session Total
description: The total sum of the cart in one session.
attributes:
type: object
description: >
A key-value map of the sessions attributes. The potentially valid
attributes are configured in your accounts developer settings.
additionalProperties: true
firstSession:
type: boolean
description: >-
Indicates whether this is the first session for the customer's
profile. Will always be true for anonymous sessions.
title: First session ever?
example: true
discounts:
type: object
title: Customer's current discounts
description: >-
A map of labelled discount values, values will be in the same currency
as the application associated with the session.
additionalProperties:
type: number
updated:
type: string
format: date-time
description: Timestamp of the most recent event received on this session.
title: Last activity on the session
example: '2021-09-12T10:12:42Z'
additionalProperties: false
CustomerSessionV2:
type: object
description: ''
required:
- id
- created
- integrationId
- applicationId
- profileId
- firstSession
- coupon
- referral
- state
- cartItems
- attributes
- total
- cartItemTotal
- additionalCostTotal
- updated
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
description: The time this entity was created. The time this entity was created.
format: date-time
integrationId:
type: string
format: string
example: URNGV8294NV
maxLength: 1000
description: The integration ID set by your integration layer.
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
profileId:
type: string
description: >
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`.
example: URNGV8294NV
storeIntegrationId:
type: string
minLength: 1
maxLength: 1000
description: >-
The integration ID of the store. You choose this ID when you create a
store.
example: STORE-001
evaluableCampaignIds:
type: array
items:
type: integer
maxLength: 999
description: >
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.
title: Campaigns to evaluate
example:
- 10
- 12
couponCodes:
type: array
items:
type: string
maxLength: 100
description: >
Any coupon codes entered.
**Important**: If you [create a coupon
budget](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets/#budget-types)
for your campaign, ensure the session contains a coupon code by the
time you close it.
title: Coupons entered in session
example:
- XMAS-20-2021
referralCode:
type: string
description: >
Any referral code entered.
**Important**: If you [create a referral
budget](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets/#budget-types)
for your campaign, ensure the session contains a referral code by the
time you close it.
title: Referral code entered in session
maxLength: 100
example: NT2K54D9
loyaltyCards:
type: array
maxItems: 1
items:
type: string
description: Any loyalty cards used.
example:
- loyalty-card-1
state:
type: string
enum:
- open
- closed
- partially_returned
- cancelled
default: open
example: open
description: >
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:
- `closed` → `cancelled` (**only** via [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)) or
- `closed` → `partially_returned` (**only** via [Return cart items](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/returnCartItems))
- `closed` → `open` (**only** via [Reopen customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/reopenCustomerSession))
4. `partially_returned` → `cancelled`
For more information, see [Customer session
states](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).
title: Customer's session state
cartItems:
type: array
description: >
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.
title: Customer session's cart items
items:
$ref: '#/definitions/CartItem'
additionalCosts:
type: object
description: >
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](https://docs.talon.one/docs/product/account/dev-tools/managing-additional-costs).
additionalProperties:
$ref: '#/definitions/AdditionalCost'
example:
shipping:
price: 9
identifiers:
type: array
maxItems: 5
items:
type: string
title: Session identifiers
description: >
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](https://docs.talon.one/docs/dev/tutorials/using-identifiers).
**Important**: Ensure the session contains an identifier by the time
you close it if:
- You [create a unique identifier
budget](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets/#budget-types)
for your campaign.
- Your campaign has
[coupons](https://docs.talon.one/docs/product/campaigns/coupons/coupon-page-overview).
example:
- 91.11.156.141
attributes:
type: object
description: >
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](https://docs.talon.one/docs/dev/concepts/attributes#built-in-attributes)
or [custom
ones](https://docs.talon.one/docs/dev/concepts/attributes#custom-attributes).
Custom attributes must be created in the Campaign Manager before you
set them with this property.
additionalProperties: true
example:
ShippingCity: Berlin
firstSession:
type: boolean
description: >-
Indicates whether this is the first session for the customer's
profile. Will always be true for anonymous sessions.
title: First session ever?
example: true
total:
type: number
title: Session Total
description: >-
The total value of cart items and additional costs in the session,
before any discounts are applied.
example: 119.99
cartItemTotal:
type: number
title: Cart Items Total
description: 'The total value of cart items, before any discounts are applied.'
example: 99.99
additionalCostTotal:
type: number
title: Additional Costs Total
description: 'The total value of additional costs, before any discounts are applied.'
example: 20
updated:
type: string
format: date-time
description: Timestamp of the most recent event received on this session.
title: Last activity on the session
example: '2020-02-08T14:15:22Z'
additionalProperties: false
CartItem:
type: object
required:
- sku
- quantity
x-attributable: true
properties:
name:
title: Name of item
type: string
description: Name of item.
example: Air Glide
sku:
title: SKU of item
type: string
description: Stock keeping unit of item.
minLength: 1
example: SKU1241028
quantity:
title: Quantity of item
type: integer
description: >
Number of units of this item. Due to [cart item
flattening](https://docs.talon.one/docs/product/rules/understanding-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.
minimum: 1
example: 1
returnedQuantity:
title: Returned quantity of item
type: integer
description: >-
Number of returned items, calculated internally based on returns of
this item.
example: 1
remainingQuantity:
title: Remaining quantity of item
type: integer
description: >-
Remaining quantity of the item, calculated internally based on returns
of this item.
example: 1
price:
title: Price of item
type: number
description: >
Price of the item in the currency defined by your Application. This
field is required if this item is not part of a
[catalog](https://docs.talon.one/docs/product/account/dev-tools/managing-cart-item-catalogs).
If it is part of a catalog, setting a price here overrides the price
from the catalog.
example: 99.99
category:
title: Item category
type: string
description: 'Type, group or model of the item.'
example: shoes
weight:
title: Weight of item
type: number
description: Weight of item in grams.
example: 1130
height:
title: Height of item
type: number
description: Height of item in mm.
width:
title: Width of item
type: number
description: Width of item in mm.
length:
title: Length of item
type: number
description: Length of item in mm.
position:
title: Position of Cart Item
type: number
description: Position of the Cart Item in the Cart (calculated internally).
attributes:
title: Item attributes
type: object
description: >
Use this property to set a value for the attributes of your choice.
[Attributes](https://docs.talon.one/docs/dev/concepts/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.
additionalProperties: true
example:
image: 11.jpeg
material: leather
additionalCosts:
type: object
description: >
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](https://docs.talon.one/docs/product/account/dev-tools/managing-additional-costs).
additionalProperties:
$ref: '#/definitions/AdditionalCost'
example:
shipping:
price: 9
catalogItemID:
title: The catalog item ID
type: integer
description: >-
The [catalog item
ID](https://docs.talon.one/docs/product/account/dev-tools/managing-cart-item-catalogs/#synchronizing-a-cart-item-catalog).
AdditionalCost:
type: object
required:
- price
properties:
price:
title: Price of additional cost
type: number
example: 4.5
IntegrationEvent:
type: object
description: ''
required:
- type
- attributes
properties:
profileId:
type: string
description: >
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`.
example: URNGV8294NV
storeIntegrationId:
type: string
minLength: 1
maxLength: 1000
description: >-
The integration ID of the store. You choose this ID when you create a
store.
example: STORE-001
type:
type: string
title: Event Type
description: A string representing the event. Must not be a reserved event name.
minLength: 1
example: pageViewed
attributes:
type: object
description: Arbitrary additional JSON data associated with the event.
additionalProperties: true
example:
myAttribute: myValue
additionalProperties: false
NewEvent:
type: object
description: ''
required:
- type
- attributes
- sessionId
properties:
profileId:
type: string
description: >
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`.
example: URNGV8294NV
storeIntegrationId:
type: string
minLength: 1
maxLength: 1000
description: >-
The integration ID of the store. You choose this ID when you create a
store.
example: STORE-001
type:
type: string
title: Event Type
description: A string representing the event. Must not be a reserved event name.
minLength: 1
example: pageViewed
attributes:
type: object
description: Arbitrary additional JSON data associated with the event.
additionalProperties: true
example:
myAttribute: myValue
sessionId:
type: string
description: The ID of the session that this event occurred in.
minLength: 1
example: 175KJPS947296
additionalProperties: false
Event:
type: object
description: ''
required:
- id
- created
- applicationId
- type
- attributes
- effects
- ledgerEntries
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
profileId:
type: string
description: >
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`.
example: URNGV8294NV
storeIntegrationId:
type: string
minLength: 1
maxLength: 1000
description: >-
The integration ID of the store. You choose this ID when you create a
store.
example: STORE-001
type:
type: string
title: Event Type
description: A string representing the event. Must not be a reserved event name.
minLength: 1
example: pageViewed
attributes:
type: object
description: Arbitrary additional JSON data associated with the event.
additionalProperties: true
example:
myAttribute: myValue
sessionId:
type: string
title: Session ID of Event
description: The ID of the session that this event occurred in.
example: 175KJPS947296
effects:
type: array
description: >
An array of effects generated by the rules of the enabled campaigns of
the Application.
You decide how to apply them in your system. See the list of [API
effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
items:
type: object
ledgerEntries:
type: array
description: Ledger entries for the event.
items:
$ref: '#/definitions/LedgerEntry'
meta:
$ref: '#/definitions/Meta'
additionalProperties: false
IntegrationState:
type: object
description: >
Contains all state that might interest application integration plugins.
This is the response type returned by all of the Integration API
operations.
properties:
session:
$ref: '#/definitions/CustomerSession'
profile:
$ref: '#/definitions/CustomerProfile'
event:
$ref: '#/definitions/Event'
loyalty:
$ref: '#/definitions/Loyalty'
coupon:
$ref: '#/definitions/Coupon'
required:
- session
- profile
- event
IntegrationStateV2:
type: object
description: |
Contains all entities that might interest Talon.One integrations.
required:
- effects
- createdCoupons
- createdReferrals
properties:
customerSession:
$ref: '#/definitions/CustomerSessionV2'
customerProfile:
$ref: '#/definitions/CustomerProfile'
event:
$ref: '#/definitions/Event'
loyalty:
$ref: '#/definitions/Loyalty'
referral:
$ref: '#/definitions/InventoryReferral'
coupons:
type: array
items:
$ref: '#/definitions/IntegrationCoupon'
triggeredCampaigns:
type: array
items:
$ref: '#/definitions/Campaign'
effects:
type: array
description: >-
The effects generated by the rules in your running campaigns. See [API
effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
items:
$ref: '#/definitions/Effect'
ruleFailureReasons:
type: array
items:
$ref: '#/definitions/RuleFailureReason'
createdCoupons:
type: array
items:
$ref: '#/definitions/Coupon'
createdReferrals:
type: array
items:
$ref: '#/definitions/Referral'
awardedGiveaways:
type: array
items:
$ref: '#/definitions/Giveaway'
return:
$ref: '#/definitions/Return'
previousReturns:
type: array
items:
$ref: '#/definitions/Return'
CustomerProfileIntegrationResponseV2:
type: object
description: >
This is the response type returned by the updateCustomerProfileV2
endpoint.
required:
- effects
- createdCoupons
- createdReferrals
properties:
customerProfile:
$ref: '#/definitions/CustomerProfile'
event:
$ref: '#/definitions/Event'
loyalty:
$ref: '#/definitions/Loyalty'
triggeredCampaigns:
type: array
items:
$ref: '#/definitions/Campaign'
ruleFailureReasons:
type: array
items:
$ref: '#/definitions/RuleFailureReason'
awardedGiveaways:
type: array
items:
$ref: '#/definitions/Giveaway'
effects:
type: array
description: >-
The effects generated by the rules in your running campaigns. See [API
effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
items:
$ref: '#/definitions/Effect'
createdCoupons:
type: array
items:
$ref: '#/definitions/Coupon'
createdReferrals:
type: array
items:
$ref: '#/definitions/Referral'
TrackEventV2Response:
type: object
description: |
This is the response type returned by the trackEventV2 endpoint.
required:
- effects
- createdCoupons
- createdReferrals
properties:
customerProfile:
$ref: '#/definitions/CustomerProfile'
event:
$ref: '#/definitions/Event'
loyalty:
$ref: '#/definitions/Loyalty'
triggeredCampaigns:
type: array
items:
$ref: '#/definitions/Campaign'
ruleFailureReasons:
type: array
items:
$ref: '#/definitions/RuleFailureReason'
awardedGiveaways:
type: array
items:
$ref: '#/definitions/Giveaway'
effects:
type: array
description: >-
The effects generated by the rules in your running campaigns. See [API
effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
items:
$ref: '#/definitions/Effect'
createdCoupons:
type: array
items:
$ref: '#/definitions/Coupon'
createdReferrals:
type: array
items:
$ref: '#/definitions/Referral'
ReopenSessionResponse:
type: object
description: >
This is the response type returned by the Reopen customer sessions
endpoint. It contains the rolled back effects.
required:
- effects
properties:
effects:
type: array
description: >-
The effects generated by the rules in your running campaigns. See [API
effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
items:
$ref: '#/definitions/Effect'
CustomerProfileUpdateV2Response:
type: object
description: >
Contains the updated customer profiles entities. This is the response type
returned by the V2 PUT customer_profiles endpoint
required:
- customerProfile
properties:
customerProfile:
$ref: '#/definitions/CustomerProfile'
IntegrationCustomerSessionResponse:
type: object
properties:
customerSession:
$ref: '#/definitions/CustomerSessionV2'
effects:
type: array
items:
$ref: '#/definitions/Effect'
ApplicationCustomer:
type: object
description: ''
required:
- id
- created
- integrationId
- accountId
- closedSessions
- totalSales
- lastActivity
- attributes
properties:
id:
type: integer
description: Internal ID of this entity. Internal ID of this entity.
created:
type: string
description: >-
The time this entity was created. The time this entity was created.
The time this entity was created. The time this entity was created.
format: date-time
integrationId:
type: string
description: >-
The integration ID set by your integration layer. The integration ID
set by your integration layer.
maxLength: 1000
format: string
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
example:
Language: english
ShippingCountry: DE
accountId:
type: integer
description: >-
The ID of the Talon.One account that owns this profile. The ID of the
Talon.One account that owns this profile.
closedSessions:
type: integer
title: Closed sessions
description: >-
The total amount of closed sessions by a customer. A closed session is
a successful purchase.
example: 3
totalSales:
type: number
description: >
The total amount of money spent by the customer **before** discounts
are applied.
The total sales amount excludes the following:
- Cancelled or reopened sessions.
- Returned items.
example: 299.99
title: Total Sales
loyaltyMemberships:
type: array
description: |
**DEPRECATED** A list of loyalty programs joined by the customer.
items:
$ref: '#/definitions/LoyaltyMembership'
title: Loyalty programed joined
audienceMemberships:
type: array
description: The audiences the customer belongs to.
items:
$ref: '#/definitions/AudienceMembership'
title: Audience memberships
lastActivity:
type: string
format: date-time
title: Last activity
description: >
Timestamp of the most recent event received from this customer.
This field is updated on calls that trigger the Rule Engine and that
are
not [dry
requests](https://docs.talon.one/docs/dev/integration-api/dry-requests/#overlay).
For example, [reserving a
coupon](https://docs.talon.one/integration-api#operation/createCouponReservation)
for a customer doesn't impact this field.
example: '2020-02-08T14:15:20Z'
sandbox:
type: boolean
description: >
Shows whether the customer is part of a sandbox or live Application.
See the
[docs](https://docs.talon.one/docs/product/applications/overview#application-environments).
title: Sandbox
example: false
advocateIntegrationId:
type: string
maxLength: 1000
description: >-
The Integration ID of the Customer Profile that referred this Customer
in the Application.
additionalProperties: false
AudienceCustomer:
type: object
description: ''
required:
- id
- created
- integrationId
- accountId
- closedSessions
- totalSales
- lastActivity
- attributes
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
description: The time this entity was created. The time this entity was created.
format: date-time
integrationId:
type: string
format: string
example: URNGV8294NV
maxLength: 1000
description: The integration ID set by your integration layer.
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
example:
Language: english
ShippingCountry: DE
accountId:
type: integer
title: Profile belongs to Account
description: The ID of the Talon.One account that owns this profile.
example: 31
closedSessions:
type: integer
title: Closed sessions
description: >-
The total amount of closed sessions by a customer. A closed session is
a successful purchase.
example: 3
totalSales:
type: number
description: >
The total amount of money spent by the customer **before** discounts
are applied.
The total sales amount excludes the following:
- Cancelled or reopened sessions.
- Returned items.
example: 299.99
title: Total Sales
loyaltyMemberships:
type: array
description: |
**DEPRECATED** A list of loyalty programs joined by the customer.
items:
$ref: '#/definitions/LoyaltyMembership'
title: Loyalty programed joined
audienceMemberships:
type: array
description: The audiences the customer belongs to.
items:
$ref: '#/definitions/AudienceMembership'
title: Audience memberships
lastActivity:
type: string
format: date-time
title: Last activity
description: >
Timestamp of the most recent event received from this customer.
This field is updated on calls that trigger the Rule Engine and that
are
not [dry
requests](https://docs.talon.one/docs/dev/integration-api/dry-requests/#overlay).
For example, [reserving a
coupon](https://docs.talon.one/integration-api#operation/createCouponReservation)
for a customer doesn't impact this field.
example: '2020-02-08T14:15:20Z'
sandbox:
type: boolean
description: >
Shows whether the customer is part of a sandbox or live Application.
See the
[docs](https://docs.talon.one/docs/product/applications/overview#application-environments).
title: Sandbox
example: false
connectedApplicationsIds:
type: array
description: >-
A list of the IDs of the Applications that are connected to this
customer profile.
example:
- 1
- 2
- 3
items:
type: integer
connectedAudiences:
type: array
description: >-
A list of the IDs of the audiences that are connected to this customer
profile.
example:
- 1
- 2
- 3
items:
type: integer
additionalProperties: false
ApplicationReferee:
type: object
description: ''
required:
- applicationId
- sessionId
- advocateIntegrationId
- friendIntegrationId
- code
- created
properties:
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
sessionId:
type: string
description: >-
Integration ID of the session in which the customer redeemed the
referral.
advocateIntegrationId:
type: string
maxLength: 1000
title: Advocate's Profile ID
description: Integration ID of the Advocate's Profile.
friendIntegrationId:
type: string
maxLength: 1000
title: Friend's Profile ID
description: Integration ID of the Friend's Profile.
code:
type: string
description: Advocate's referral code.
created:
type: string
format: date-time
description: Timestamp of the moment the customer redeemed the referral.
additionalProperties: false
ApplicationSession:
type: object
description: ''
required:
- id
- created
- integrationId
- applicationId
- coupon
- referral
- state
- cartItems
- discounts
- total
- totalDiscounts
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
description: The time this entity was created. The time this entity was created.
format: date-time
integrationId:
type: string
format: string
example: URNGV8294NV
maxLength: 1000
description: The integration ID set by your integration layer.
storeIntegrationId:
type: string
minLength: 1
maxLength: 1000
description: >-
The integration ID of the store. You choose this ID when you create a
store.
example: STORE-001
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
profileId:
type: integer
description: >-
The globally unique Talon.One ID of the customer that created this
entity.
example: 138
profileintegrationid:
type: string
maxLength: 1000
description: Integration ID of the customer for the session.
example: 382370BKDB946
coupon:
type: string
description: Any coupon code entered.
example: BKDB946
referral:
type: string
description: Any referral code entered.
example: BKDB946
state:
type: string
enum:
- open
- closed
- partially_returned
- cancelled
description: >
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. `closed` → `cancelled` or `partially_returned`
4. `partially_returned` → `cancelled`
For more information, see [Customer session
states](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).
example: closed
cartItems:
type: array
description: Serialized JSON representation.
items:
$ref: '#/definitions/CartItem'
discounts:
type: object
description: >
**API V1 only.** A map of labeled discount values, in the same
currency as the session.
If you are using the V2 endpoints, refer to the `totalDiscounts`
property instead.
additionalProperties:
type: number
totalDiscounts:
type: number
description: The total sum of the discounts applied to this session.
example: 100
total:
type: number
description: The total sum of the session before any discounts applied.
example: 200
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
additionalProperties: false
ApplicationEvent:
type: object
description: ''
required:
- id
- created
- applicationId
- type
- attributes
- effects
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
profileId:
type: integer
description: >-
The globally unique Talon.One ID of the customer that created this
entity.
example: 138
storeId:
type: integer
description: The ID of the store.
storeIntegrationId:
type: string
minLength: 1
maxLength: 1000
description: >-
The integration ID of the store. You choose this ID when you create a
store.
example: STORE-001
sessionId:
type: integer
description: >-
The globally unique Talon.One ID of the session that contains this
event.
type:
type: string
description: A string representing the event. Must not be a reserved event name.
attributes:
type: object
description: Additional JSON serialized data associated with the event.
additionalProperties: true
effects:
type: array
description: >-
An array containing the effects that were applied as a result of this
event.
items:
$ref: '#/definitions/Effect'
ruleFailureReasons:
type: array
description: >-
An array containing the rule failure reasons which happened during
this event.
items:
$ref: '#/definitions/RuleFailureReason'
additionalProperties: false
NewAccount:
type: object
required:
- companyName
properties:
companyName:
type: string
minLength: 1
AccountAnalytics:
type: object
required:
- applications
- liveApplications
- sandboxApplications
- campaigns
- activeCampaigns
- liveActiveCampaigns
- coupons
- activeCoupons
- expiredCoupons
- referralCodes
- activeReferralCodes
- expiredReferralCodes
- activeRules
- users
- roles
- customAttributes
- webhooks
- loyaltyPrograms
- liveLoyaltyPrograms
- lastUpdatedAt
properties:
applications:
type: integer
description: Total number of applications in the account.
example: 11
liveApplications:
type: integer
description: Total number of live applications in the account.
example: 6
sandboxApplications:
type: integer
description: Total number of sandbox applications in the account.
example: 2
campaigns:
type: integer
description: Total number of campaigns in the account.
example: 35
activeCampaigns:
type: integer
description: Total number of active campaigns in the account.
example: 15
liveActiveCampaigns:
type: integer
description: Total number of active campaigns in live applications in the account.
example: 10
coupons:
type: integer
description: Total number of coupons in the account.
example: 850
activeCoupons:
type: integer
description: Total number of active coupons in the account.
example: 650
expiredCoupons:
type: integer
description: Total number of expired coupons in the account.
example: 200
referralCodes:
type: integer
description: Total number of referral codes in the account.
example: 500
activeReferralCodes:
type: integer
description: Total number of active referral codes in the account.
example: 100
expiredReferralCodes:
type: integer
description: Total number of expired referral codes in the account.
example: 400
activeRules:
type: integer
description: Total number of active rules in the account.
example: 35
users:
type: integer
description: Total number of users in the account.
roles:
type: integer
description: Total number of roles in the account.
example: 10
customAttributes:
type: integer
description: Total number of custom attributes in the account.
example: 18
webhooks:
type: integer
description: Total number of webhooks in the account.
example: 2
loyaltyPrograms:
type: integer
description: Total number of all loyalty programs in the account.
example: 5
liveLoyaltyPrograms:
type: integer
description: Total number of live loyalty programs in the account.
example: 5
lastUpdatedAt:
type: string
format: date-time
description: The point in time when the analytics numbers were updated last.
example: 2022-12-12T12:12:12.000Z
AccountLimits:
type: object
required:
- liveApplications
- sandboxApplications
- activeCampaigns
- coupons
- referralCodes
- activeRules
- liveLoyaltyPrograms
- sandboxLoyaltyPrograms
- webhooks
- users
- apiVolume
- promotionTypes
properties:
liveApplications:
type: integer
description: Total number of allowed live applications in the account.
sandboxApplications:
type: integer
description: Total number of allowed sandbox applications in the account.
activeCampaigns:
type: integer
description: >-
Total number of allowed active campaigns in live applications in the
account.
coupons:
type: integer
description: Total number of allowed coupons in the account.
referralCodes:
type: integer
description: Total number of allowed referral codes in the account.
activeRules:
type: integer
description: Total number of allowed active rulesets in the account.
liveLoyaltyPrograms:
type: integer
description: Total number of allowed live loyalty programs in the account.
sandboxLoyaltyPrograms:
type: integer
description: Total number of allowed sandbox loyalty programs in the account.
webhooks:
type: integer
description: Total number of allowed webhooks in the account.
users:
type: integer
description: Total number of allowed users in the account.
apiVolume:
type: integer
description: Allowed volume of API requests to the account.
promotionTypes:
type: array
description: Array of promotion types that are employed in the account.
items:
type: string
UpdateAccount:
type: object
required:
- companyName
- billingEmail
properties:
attributes:
type: object
description: Arbitrary properties associated with this campaign.
additionalProperties: true
companyName:
type: string
minLength: 1
description: Name of your company.
billingEmail:
type: string
format: email
description: The billing email address associated with your company account.
state:
type: string
enum:
- active
- deactivated
description: 'State of the account (active, deactivated).'
planExpires:
type: string
format: date-time
description: The point in time at which your current plan expires.
Account:
type: object
description: ''
required:
- id
- created
- modified
- companyName
- domainName
- state
- billingEmail
- applicationCount
- userCount
- campaignsActiveCount
- campaignsInactiveCount
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
companyName:
type: string
minLength: 1
domainName:
type: string
description: Subdomain Name for yourcompany.talon.one.
state:
type: string
enum:
- active
- deactivated
description: 'State of the account (active, deactivated).'
billingEmail:
type: string
format: email
description: The billing email address associated with your company account.
planName:
type: string
description: The name of your booked plan.
planExpires:
type: string
format: date-time
description: The point in time at which your current plan expires.
applicationLimit:
type: integer
description: The maximum number of Applications covered by your plan.
userLimit:
type: integer
description: The maximum number of Campaign Manager Users covered by your plan.
campaignLimit:
type: integer
description: The maximum number of Campaigns covered by your plan.
apiLimit:
type: integer
description: >-
The maximum number of Integration API calls covered by your plan per
billing period.
applicationCount:
type: integer
description: The current number of Applications in your account.
userCount:
type: integer
description: The current number of Campaign Manager Users in your account.
campaignsActiveCount:
type: integer
description: The current number of active Campaigns in your account.
campaignsInactiveCount:
type: integer
description: The current number of inactive Campaigns in your account.
attributes:
type: object
description: Arbitrary properties associated with this campaign.
additionalProperties: true
additionalProperties: false
NewAccountSignUp:
type: object
description: ''
required:
- email
- password
- companyName
properties:
email:
type: string
format: email
example: john.doe@example.com
description: The email address associated with your account.
password:
type: string
description: The password for your account.
example: admin123456
companyName:
type: string
minLength: 1
additionalProperties: false
NewUser:
type: object
description: ''
required:
- email
- password
- inviteToken
properties:
email:
type: string
format: email
example: john.doe@example.com
description: The email address associated with your account.
password:
type: string
description: The password for your account.
example: admin123456
name:
type: string
description: Your name.
inviteToken:
type: string
minLength: 1
example: Gy9b8w1irmQtEPo5RmbMmSPheL5h4
additionalProperties: false
UpdateUser:
type: object
properties:
name:
type: string
description: The user name.
example: John Doe
policy:
type: string
description: >-
The `Access Control List` json defining the role of the user. This
represents the access control on the user level.
example:
Role: 127
Applications: null
state:
type: string
enum:
- deactivated
- active
description: >-
New state ("deactivated" or "active") for the user. Only usable by
admins for the user.
example: deactivated
roles:
type: array
items:
type: integer
description: List of roles to assign to the user.
example:
- 1
- 3
applicationNotificationSubscriptions:
type: object
additionalProperties: true
isAdmin:
type: boolean
description: An indication of whether the user has admin permissions.
example: false
ChangeProfilePassword:
type: object
required:
- password
- newPassword
properties:
password:
type: string
description: Your old password.
example: Admin&12943!7
newPassword:
type: string
description: Your new password.
example: Admin*4552$70
NewInviteEmail:
type: object
required:
- email
- token
properties:
email:
type: string
format: email
minLength: 1
token:
type: string
minLength: 1
NewPasswordEmail:
type: object
required:
- email
properties:
email:
type: string
format: email
minLength: 1
NewPassword:
type: object
required:
- password
- resetToken
properties:
password:
type: string
description: The new password for your account.
example: Admin&12943!7
resetToken:
type: string
minLength: 1
example: Z2VgacVNkexLKBUIzsRDDZSGxnIkC53y
Environment:
type: object
description: ''
required:
- id
- created
- applicationId
- slots
- functions
- templates
- variables
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
slots:
type: array
description: The slots defined for this application.
items:
$ref: '#/definitions/SlotDef'
functions:
type: array
description: The functions defined for this application.
items:
$ref: '#/definitions/FunctionDef'
templates:
type: array
description: The templates defined for this application.
items:
$ref: '#/definitions/TemplateDef'
variables:
type: string
description: A stringified version of the environment's Talang variables scope.
giveawaysPools:
type: array
description: The giveaways pools that the application is subscribed to.
items:
$ref: '#/definitions/GiveawaysPool'
loyaltyPrograms:
type: array
description: The loyalty programs that the application is subscribed to.
items:
$ref: '#/definitions/LoyaltyProgram'
attributes:
type: array
description: The attributes that the application is subscribed to.
items:
$ref: '#/definitions/Attribute'
additionalCosts:
type: array
description: The additional costs that the application is subscribed to.
items:
$ref: '#/definitions/AccountAdditionalCost'
audiences:
type: array
description: >-
The audiences contained in the account which the application belongs
to.
items:
$ref: '#/definitions/Audience'
collections:
type: array
description: The account-level collections that the application is subscribed to.
items:
$ref: '#/definitions/Collection'
additionalProperties: false
SlotDef:
type: object
required:
- name
- type
- title
- writable
properties:
name:
type: string
description: The dot-separated path to this slot for use in Talang.
type:
type: string
description: 'The type of this slot, one of string, number, boolean, or list[type].'
title:
type: string
description: Campaigner-friendly name for the slot.
description:
type: string
description: A short description of the slot.
help:
type: string
description: Extended help text for the slot.
writable:
type: boolean
description: Whether or not this slot can be updated by rule effects.
FuncArgDef:
type: object
required:
- type
- description
properties:
type:
type: string
enum:
- string
- boolean
- number
- time
- (list string)
description: The type of value this argument expects.
minLength: 1
description:
type: string
description: >-
A campaigner-friendly description of the argument, this will also be
shown in the rule editor.
TemplateArgDef:
type: object
description: ''
required:
- type
- description
- ui
- title
properties:
type:
type: string
enum:
- string
- boolean
- number
- time
- (list string)
description: The type of value this argument expects.
minLength: 1
description:
type: string
description: >-
A campaigner-friendly description of the argument, this will also be
shown in the rule editor.
title:
type: string
description: >-
A campaigner friendly name for the argument, this will be shown in the
rule editor.
minLength: 1
ui:
type: object
description: >-
Arbitrary metadata that may be used to render an input for this
argument.
additionalProperties: true
picklistID:
type: integer
description: ID of the picklist linked to a template.
restrictedByPicklist:
type: boolean
description: >-
Whether or not this attribute's value is restricted by picklist
(`picklist` property)
additionalProperties: false
FunctionDef:
type: object
required:
- name
- type
- args
properties:
name:
type: string
description: The function name used in Talang.
minLength: 1
type:
type: string
description: The type of this function argument.
description:
type: string
description: A short description of the function.
help:
type: string
description: Extended help text for the function.
args:
type: array
description: An array of argument definitions.
items:
$ref: '#/definitions/FuncArgDef'
CampaignTemplateParams:
type: object
required:
- name
- type
- description
properties:
name:
type: string
description: Name of the campaign template parameter.
minLength: 1
example: discount_value
type:
type: string
enum:
- string
- number
- boolean
- percent
- (list string)
- time
description: Defines the type of parameter value.
example: number
description:
type: string
description: >-
Explains the meaning of this template parameter and the placeholder
value that will define it. It is used on campaign creation from this
template.
example: This is a template parameter of type `number`.
attributeId:
type: integer
description: ID of the corresponding attribute.
example: 42
NewCampaignTemplate:
type: object
required:
- name
- state
- description
- instructions
- campaignType
properties:
name:
type: string
description: The campaign template name.
minLength: 1
description:
type: string
description: Customer-facing text that explains the objective of the template.
instructions:
type: string
description: >-
Customer-facing text that explains how to use the template. For
example, you can use this property to explain the available attributes
of this template, and how they can be modified when a user uses this
template to create a new campaign.
campaignAttributes:
type: object
description: >-
The campaign attributes that campaigns created from this template will
have by default.
additionalProperties: true
couponAttributes:
type: object
description: >-
The campaign attributes that coupons created from this template will
have by default.
additionalProperties: true
state:
type: string
enum:
- draft
- enabled
- disabled
description: >-
Only Campaign Templates in 'available' state may be used to create
Campaigns.
tags:
type: array
description: A list of tags for the campaign template.
maxItems: 50
items:
type: string
minLength: 1
maxLength: 50
features:
type: array
description: A list of features for the campaign template.
items:
type: string
enum:
- coupons
- referrals
- loyalty
- giveaways
- strikethrough
couponSettings:
$ref: '#/definitions/CodeGeneratorSettings'
referralSettings:
$ref: '#/definitions/CodeGeneratorSettings'
limits:
type: array
description: The set of limits that will operate for this campaign template.
items:
$ref: '#/definitions/TemplateLimitConfig'
templateParams:
type: array
description: Fields which can be used to replace values in a rule.
items:
$ref: '#/definitions/CampaignTemplateParams'
campaignCollections:
type: array
description: The campaign collections from the blueprint campaign for the template.
items:
$ref: '#/definitions/CampaignTemplateCollection'
defaultCampaignGroupId:
type: integer
description: The default campaign group ID.
example: 42
campaignType:
type: string
enum:
- cartItem
- advanced
default: advanced
example: advanced
description: |
The campaign type. Possible type values:
- `cartItem`: Type of campaign that can apply effects only to cart items.
- `advanced`: Type of campaign that can apply effects to customer sessions and cart items.
UpdateCampaignTemplate:
type: object
required:
- name
- state
- description
- instructions
- applicationsIds
properties:
name:
type: string
description: The campaign template name.
minLength: 1
example: Discount campaign
description:
type: string
description: Customer-facing text that explains the objective of the template.
example: This is a template for a discount campaign.
instructions:
type: string
description: >-
Customer-facing text that explains how to use the template. For
example, you can use this property to explain the available attributes
of this template, and how they can be modified when a user uses this
template to create a new campaign.
example: >-
Use this template for discount campaigns. Set the campaign properties
according to the campaign goals, and don't forget to set an end date.
campaignAttributes:
type: object
description: >-
The campaign attributes that campaigns created from this template will
have by default.
additionalProperties: true
couponAttributes:
type: object
description: >-
The campaign attributes that coupons created from this template will
have by default.
additionalProperties: true
state:
type: string
enum:
- draft
- enabled
- disabled
description: >-
Only campaign templates in 'available' state may be used to create
campaigns.
activeRulesetId:
type: integer
description: The ID of the ruleset this campaign template will use.
example: 5
tags:
type: array
description: A list of tags for the campaign template.
maxItems: 50
example:
- discount
items:
type: string
minLength: 1
maxLength: 50
features:
type: array
description: A list of features for the campaign template.
items:
type: string
enum:
- coupons
- referrals
- loyalty
- giveaways
- strikethrough
couponSettings:
$ref: '#/definitions/CodeGeneratorSettings'
referralSettings:
$ref: '#/definitions/CodeGeneratorSettings'
limits:
type: array
description: The set of limits that operate for this campaign template.
items:
$ref: '#/definitions/TemplateLimitConfig'
templateParams:
type: array
description: Fields which can be used to replace values in a rule.
items:
$ref: '#/definitions/CampaignTemplateParams'
applicationsIds:
type: array
description: >-
A list of IDs of the Applications that are subscribed to this campaign
template.
items:
type: integer
example:
- 1
- 2
- 3
campaignCollections:
type: array
description: The campaign collections from the blueprint campaign for the template.
items:
$ref: '#/definitions/CampaignTemplateCollection'
defaultCampaignGroupId:
type: integer
description: The default campaign group ID.
example: 42
campaignType:
type: string
enum:
- cartItem
- advanced
default: advanced
example: advanced
description: |
The campaign type. Possible type values:
- `cartItem`: Type of campaign that can apply effects only to cart items.
- `advanced`: Type of campaign that can apply effects to customer sessions and cart items.
CampaignTemplateCollection:
type: object
required:
- name
properties:
name:
type: string
minLength: 1
pattern: '^[A-Za-z](\w|\s)*$'
description: The name of this collection.
example: My collection
description:
type: string
description: A short description of the purpose of this collection.
example: My collection of SKUs
CampaignTemplate:
type: object
description: ''
required:
- id
- created
- accountId
- userId
- name
- state
- description
- instructions
- applicationsIds
- validApplicationIds
- applicationIds
- campaignType
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
userId:
type: integer
description: The ID of the user associated with this entity.
example: 388
name:
type: string
description: The campaign template name.
minLength: 1
example: Discount campaign
description:
type: string
description: Customer-facing text that explains the objective of the template.
example: This is a template for a discount campaign.
instructions:
type: string
description: >-
Customer-facing text that explains how to use the template. For
example, you can use this property to explain the available attributes
of this template, and how they can be modified when a user uses this
template to create a new campaign.
example: >-
Use this template for discount campaigns. Set the campaign properties
according to the campaign goals, and don't forget to set an end date.
campaignAttributes:
type: object
description: >-
The campaign attributes that campaigns created from this template will
have by default.
additionalProperties: true
couponAttributes:
type: object
description: >-
The campaign attributes that coupons created from this template will
have by default.
additionalProperties: true
state:
type: string
enum:
- draft
- enabled
- disabled
description: >-
Only campaign templates in 'available' state may be used to create
campaigns.
activeRulesetId:
type: integer
description: The ID of the ruleset this campaign template will use.
example: 5
tags:
type: array
description: A list of tags for the campaign template.
maxItems: 50
example:
- discount
items:
type: string
minLength: 1
maxLength: 50
features:
type: array
description: A list of features for the campaign template.
items:
type: string
enum:
- coupons
- referrals
- loyalty
- giveaways
- strikethrough
couponSettings:
$ref: '#/definitions/CodeGeneratorSettings'
referralSettings:
$ref: '#/definitions/CodeGeneratorSettings'
limits:
type: array
description: The set of limits that operate for this campaign template.
items:
$ref: '#/definitions/TemplateLimitConfig'
templateParams:
type: array
description: Fields which can be used to replace values in a rule.
items:
$ref: '#/definitions/CampaignTemplateParams'
applicationsIds:
type: array
description: >-
A list of IDs of the Applications that are subscribed to this campaign
template.
items:
type: integer
description: ''
campaignCollections:
type: array
description: The campaign collections from the blueprint campaign for the template.
items:
$ref: '#/definitions/CampaignTemplateCollection'
defaultCampaignGroupId:
type: integer
description: The default campaign group ID.
example: 42
campaignType:
type: string
enum:
- cartItem
- advanced
default: advanced
example: advanced
description: |
The campaign type. Possible type values:
- `cartItem`: Type of campaign that can apply effects only to cart items.
- `advanced`: Type of campaign that can apply effects to customer sessions and cart items.
updated:
type: string
format: date-time
description: >-
Timestamp of the most recent update to the campaign template or any of
its elements.
example: '2022-08-24T14:15:22.000Z'
updatedBy:
type: string
description: >-
Name of the user who last updated this campaign template, if
available.
example: Jane Doe
validApplicationIds:
type: array
description: The IDs of the Applications that are related to this entity.
items:
type: integer
example:
- 1
- 2
- 3
additionalProperties: false
CreateTemplateCampaign:
type: object
required:
- name
- templateId
properties:
name:
type: string
title: Campaign Name
description: A user-facing name for this campaign.
example: Discount campaign
minLength: 1
description:
type: string
title: Campaign Description
description: A detailed description of the campaign.
example: This template is for discount campaigns.
templateId:
type: integer
description: >-
The ID of the Campaign Template which will be used in order to create
the Campaign.
example: 4
campaignAttributesOverrides:
type: object
description: >-
Custom Campaign Attributes. If the Campaign Template defines the same
values, they will be overridden.
additionalProperties: true
templateParamValues:
type: array
description: >-
Actual values to replace the template placeholder values in the
Ruleset bindings. Values for all Template Parameters must be provided.
items:
$ref: '#/definitions/Binding'
limitOverrides:
type: array
description: >-
Limits for this Campaign. If the Campaign Template or Application
define default values for the same limits, they will be overridden.
items:
$ref: '#/definitions/LimitConfig'
campaignGroups:
type: array
description: >
The IDs of the [campaign
groups](https://docs.talon.one/docs/product/account/account-settings/managing-campaign-groups)
this campaign belongs to.
example:
- 1
- 3
items:
type: integer
tags:
type: array
description: >-
A list of tags for the campaign. If the campaign template has tags,
they will be overridden by this list.
example:
- summer
maxItems: 50
items:
type: string
minLength: 1
maxLength: 50
evaluationGroupId:
type: integer
example: 2
description: The ID of the campaign evaluation group the campaign belongs to.
linkedStoreIds:
type: array
description: >
A list of store IDs that are linked to the campaign.
**Note:** Campaigns with linked store IDs will only be evaluated when
there is a
[customer session
update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
that references a linked store.
items:
type: integer
example:
- 1
- 2
- 3
CreateTemplateCampaignResponse:
type: object
required:
- campaign
- ruleset
properties:
campaign:
$ref: '#/definitions/Campaign'
ruleset:
$ref: '#/definitions/Ruleset'
collections:
type: array
items:
$ref: '#/definitions/Collection'
NewTemplateDef:
type: object
required:
- title
- category
- args
- expr
properties:
title:
type: string
description: >-
Campaigner-friendly name for the template that will be shown in the
rule editor.
minLength: 1
description:
type: string
description: >-
A short description of the template that will be shown in the rule
editor.
help:
type: string
description: Extended help text for the template.
category:
description: Used for grouping templates in the rule editor sidebar.
type: string
minLength: 1
expr:
type: array
description: A Talang expression that contains variable bindings referring to args.
items:
type: object
args:
type: array
description: An array of argument definitions.
items:
$ref: '#/definitions/TemplateArgDef'
expose:
type: boolean
description: A flag to control exposure in Rule Builder.
default: false
TemplateDef:
type: object
description: ''
required:
- id
- created
- applicationId
- title
- category
- args
- expr
- name
- description
- help
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
title:
type: string
description: >-
Campaigner-friendly name for the template that will be shown in the
rule editor.
minLength: 1
description:
type: string
description: >-
A short description of the template that will be shown in the rule
editor.
help:
type: string
description: Extended help text for the template.
category:
description: Used for grouping templates in the rule editor sidebar.
type: string
minLength: 1
expr:
type: array
description: A Talang expression that contains variable bindings referring to args.
items:
type: object
args:
type: array
description: An array of argument definitions.
items:
$ref: '#/definitions/TemplateArgDef'
expose:
type: boolean
description: A flag to control exposure in Rule Builder.
default: false
name:
type: string
description: The template name used in Talang.
minLength: 1
additionalProperties: false
NewAttribute:
type: object
description: ''
required:
- entity
- name
- title
- type
- description
- suggestions
- editable
properties:
entity:
type: string
description: >-
The name of the entity that can have this attribute. When creating or
updating the entities of a given type, you can include an `attributes`
object with keys corresponding to the `name` of the custom attributes
for that type.
enum:
- Account
- Application
- Campaign
- CustomerProfile
- CustomerSession
- CartItem
- Coupon
- Event
- Giveaway
- Referral
- Store
example: Event
eventType:
type: string
example: pageViewed
name:
type: string
pattern: '^[A-Za-z]\w*$'
description: >-
The attribute name that will be used in API requests and Talang. E.g.
if `name == "region"` then you would set the region attribute by
including an `attributes.region` property in your request payload.
example: pageViewed
title:
type: string
pattern: '^[A-Za-z][A-Za-z0-9_.!~*''() -]*$'
description: >-
The human-readable name for the attribute that will be shown in the
Campaign Manager. Like `name`, the combination of entity and title
must also be unique.
example: Page view event
type:
type: string
enum:
- string
- number
- boolean
- time
- (list string)
- (list number)
- (list time)
- location
- (list location)
description: >-
The data type of the attribute, a `time` attribute must be sent as a
string that conforms to the
[RFC3339](https://www.ietf.org/rfc/rfc3339.txt) timestamp format.
example: string
description:
type: string
description: A description of this attribute.
example: Event triggered when a customer displays a page.
suggestions:
type: array
description: A list of suggestions for the attribute.
maxItems: 50
items:
type: string
minLength: 1
hasAllowedList:
type: boolean
description: >-
Whether or not this attribute has an allowed list of values associated
with it.
default: false
example: false
restrictedBySuggestions:
type: boolean
description: >
Whether or not this attribute's value is restricted by suggestions
(`suggestions` property)
or by an allowed list of value (`hasAllowedList` property).
default: false
example: false
editable:
type: boolean
description: Whether or not this attribute can be edited.
example: true
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications where this attribute is
available.
items:
type: integer
example:
- 1
- 4
- 9
subscribedCatalogsIds:
type: array
description: A list of the IDs of the catalogs where this attribute is available.
items:
type: integer
example:
- 2
- 5
allowedSubscriptions:
type: array
description: >
A list of allowed subscription types for this attribute.
**Note:** This only applies to attributes associated with the
`CartItem` entity.
example:
- application
- catalog
maxItems: 2
items:
type: string
enum:
- application
- catalog
additionalProperties: false
Attribute:
type: object
description: ''
required:
- id
- created
- accountId
- entity
- name
- title
- type
- description
- suggestions
- editable
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
entity:
type: string
description: >-
The name of the entity that can have this attribute. When creating or
updating the entities of a given type, you can include an `attributes`
object with keys corresponding to the `name` of the custom attributes
for that type.
enum:
- Account
- Application
- Campaign
- CustomerProfile
- CustomerSession
- CartItem
- Coupon
- Event
- Giveaway
- Referral
- Store
example: Event
eventType:
type: string
example: pageViewed
name:
type: string
pattern: '^[A-Za-z]\w*$'
description: >-
The attribute name that will be used in API requests and Talang. E.g.
if `name == "region"` then you would set the region attribute by
including an `attributes.region` property in your request payload.
example: pageViewed
title:
type: string
pattern: '^[A-Za-z][A-Za-z0-9_.!~*''() -]*$'
description: >-
The human-readable name for the attribute that will be shown in the
Campaign Manager. Like `name`, the combination of entity and title
must also be unique.
example: Page view event
type:
type: string
enum:
- string
- number
- boolean
- time
- (list string)
- (list number)
- (list time)
- location
- (list location)
description: >-
The data type of the attribute, a `time` attribute must be sent as a
string that conforms to the
[RFC3339](https://www.ietf.org/rfc/rfc3339.txt) timestamp format.
example: string
description:
type: string
description: A description of this attribute.
example: Event triggered when a customer displays a page.
suggestions:
type: array
description: A list of suggestions for the attribute.
maxItems: 50
items:
type: string
minLength: 1
hasAllowedList:
type: boolean
description: >-
Whether or not this attribute has an allowed list of values associated
with it.
default: false
example: false
restrictedBySuggestions:
type: boolean
description: >
Whether or not this attribute's value is restricted by suggestions
(`suggestions` property)
or by an allowed list of value (`hasAllowedList` property).
default: false
example: false
editable:
type: boolean
description: Whether or not this attribute can be edited.
example: true
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications where this attribute is
available.
items:
type: integer
example:
- 1
- 4
- 9
subscribedCatalogsIds:
type: array
description: A list of the IDs of the catalogs where this attribute is available.
items:
type: integer
example:
- 2
- 5
allowedSubscriptions:
type: array
description: >
A list of allowed subscription types for this attribute.
**Note:** This only applies to attributes associated with the
`CartItem` entity.
example:
- application
- catalog
maxItems: 2
items:
type: string
enum:
- application
- catalog
eventTypeId:
type: integer
example: 22
additionalProperties: false
NewAdditionalCost:
type: object
description: ''
required:
- name
- title
- description
properties:
name:
type: string
pattern: '^[A-Za-z]\w*$'
description: The internal name used in API requests.
example: shippingFee
title:
type: string
pattern: '^[A-Za-z][A-Za-z0-9_.!~*''() -]*$'
description: >-
The human-readable name for the additional cost that will be shown in
the Campaign Manager. Like `name`, the combination of entity and title
must also be unique.
example: Shipping fee
description:
type: string
description: A description of this additional cost.
example: A shipping fee
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications that are subscribed to this
additional cost.
items:
type: integer
example:
- 3
- 13
type:
type: string
enum:
- session
- item
- both
example: session
description: |
The type of additional cost. Possible value:
- `session`: Additional cost will be added per session.
- `item`: Additional cost will be added per item.
- `both`: Additional cost will be added per item and session.
default: session
additionalProperties: false
AccountAdditionalCost:
type: object
description: ''
required:
- id
- created
- accountId
- name
- title
- description
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
name:
type: string
pattern: '^[A-Za-z]\w*$'
description: The internal name used in API requests.
example: shippingFee
title:
type: string
pattern: '^[A-Za-z][A-Za-z0-9_.!~*''() -]*$'
description: >-
The human-readable name for the additional cost that will be shown in
the Campaign Manager. Like `name`, the combination of entity and title
must also be unique.
example: Shipping fee
description:
type: string
description: A description of this additional cost.
example: A shipping fee
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications that are subscribed to this
additional cost.
items:
type: integer
example:
- 3
- 13
type:
type: string
enum:
- session
- item
- both
example: session
description: |
The type of additional cost. Possible value:
- `session`: Additional cost will be added per session.
- `item`: Additional cost will be added per item.
- `both`: Additional cost will be added per item and session.
default: session
additionalProperties: false
NewEventType:
type: object
description: ''
required:
- title
- name
properties:
title:
type: string
minLength: 1
description: The human-friendly name for this event type.
example: Survey Completed
name:
type: string
minLength: 1
description: >-
The integration name for this event type. This will be used in URLs
and cannot be changed after an event type has been created.
example: surveyCompleted
description:
type: string
description: |
A description of what the event represents.
example: The survey was submitted by the customer.
additionalProperties: false
EventType:
type: object
description: ''
required:
- id
- created
- title
- name
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
title:
type: string
minLength: 1
description: The human-friendly name for this event type.
example: Survey Completed
name:
type: string
minLength: 1
description: >-
The integration name for this event type. This will be used in URLs
and cannot be changed after an event type has been created.
example: surveyCompleted
description:
type: string
description: |
A description of what the event represents.
example: The survey was submitted by the customer.
additionalProperties: false
NewWebhook:
type: object
description: ''
required:
- applicationIds
- title
- verb
- url
- headers
- params
- enabled
properties:
applicationIds:
type: array
minItems: 1
description: The IDs of the Applications that are related to this entity.
items:
type: integer
title:
type: string
pattern: '^[A-Za-z][A-Za-z0-9_.!~*''() -]*$'
description: Name or title for this webhook.
example: Send message
verb:
type: string
enum:
- POST
- PUT
- GET
- DELETE
- PATCH
description: API method for this webhook.
example: POST
url:
type: string
description: API URL (supports templating using parameters) for this webhook.
example: www.my-company.com/my-endpoint-name
headers:
type: array
description: List of API HTTP headers for this webhook.
items:
type: string
pattern: '^([^:,]*):([^]*|[^,]*)$'
example:
- '{"Authorization": "Basic bmF2ZWVua3VtYXIU="}'
- '{"Content-Type": "application/json"}'
payload:
type: string
description: API payload (supports templating using parameters) for this webhook.
example: "{\n\t\"message\": \"${message}\"\n}"
params:
type: array
description: Array of template argument definitions.
items:
$ref: '#/definitions/TemplateArgDef'
example: []
enabled:
type: boolean
description: Enables or disables webhook from showing in the Rule Builder.
example: true
additionalProperties: false
Webhook:
type: object
description: ''
required:
- id
- created
- modified
- applicationIds
- title
- verb
- url
- headers
- params
- enabled
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
applicationIds:
type: array
description: >-
The IDs of the Applications that are related to this entity. The IDs
of the Applications that are related to this entity.
minItems: 1
items:
type: integer
description: ''
title:
type: string
pattern: '^[A-Za-z][A-Za-z0-9_.!~*''() -]*$'
description: Name or title for this webhook.
example: Send message
verb:
type: string
enum:
- POST
- PUT
- GET
- DELETE
- PATCH
description: API method for this webhook.
example: POST
url:
type: string
description: API URL (supports templating using parameters) for this webhook.
example: www.my-company.com/my-endpoint-name
headers:
type: array
description: List of API HTTP headers for this webhook.
items:
type: string
pattern: '^([^:,]*):([^]*|[^,]*)$'
example:
- '{"Authorization": "Basic bmF2ZWVua3VtYXIU="}'
- '{"Content-Type": "application/json"}'
payload:
type: string
description: API payload (supports templating using parameters) for this webhook.
example: "{\n\t\"message\": \"${message}\"\n}"
params:
type: array
description: Array of template argument definitions.
items:
$ref: '#/definitions/TemplateArgDef'
example: []
enabled:
type: boolean
description: Enables or disables webhook from showing in the Rule Builder.
example: true
additionalProperties: false
WebhookWithOutgoingIntegrationDetails:
type: object
description: ''
required:
- id
- created
- modified
- applicationIds
- title
- verb
- url
- headers
- params
- enabled
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
applicationIds:
type: array
description: >-
The IDs of the Applications that are related to this entity. The IDs
of the Applications that are related to this entity.
minItems: 1
items:
type: integer
description: ''
title:
type: string
pattern: '^[A-Za-z][A-Za-z0-9_.!~*''() -]*$'
description: Name or title for this webhook.
example: Send message
verb:
type: string
enum:
- POST
- PUT
- GET
- DELETE
- PATCH
description: API method for this webhook.
example: POST
url:
type: string
description: API URL (supports templating using parameters) for this webhook.
example: www.my-company.com/my-endpoint-name
headers:
type: array
description: List of API HTTP headers for this webhook.
items:
type: string
pattern: '^([^:,]*):([^]*|[^,]*)$'
example:
- '{"Authorization": "Basic bmF2ZWVua3VtYXIU="}'
- '{"Content-Type": "application/json"}'
payload:
type: string
description: API payload (supports templating using parameters) for this webhook.
example: "{\n\t\"message\": \"${message}\"\n}"
params:
type: array
description: Array of template argument definitions.
items:
$ref: '#/definitions/TemplateArgDef'
example: []
enabled:
type: boolean
description: Enables or disables webhook from showing in the Rule Builder.
example: true
outgoingIntegrationTemplateId:
type: integer
description: Identifier of the outgoing integration template.
example: 1
outgoingIntegrationTypeId:
type: integer
description: Identifier of the outgoing integration type.
example: 1
outgoingIntegrationTypeName:
type: string
description: Name of the outgoing integration.
example: Braze
additionalProperties: false
MultipleNewAudiences:
type: object
required:
- audiences
properties:
audiences:
type: array
items:
$ref: '#/definitions/NewMultipleAudiencesItem'
MultipleAudiences:
type: object
required:
- accountId
- audiences
properties:
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
audiences:
type: array
items:
$ref: '#/definitions/MultipleAudiencesItem'
AudienceIntegrationID:
type: object
properties:
integrationId:
type: string
minLength: 1
maxLength: 1000
description: The ID of this audience in the third-party integration.
example: 382370BKDB946
NewMultipleAudiencesItem:
type: object
description: ''
required:
- name
properties:
name:
type: string
minLength: 1
description: The human-friendly display name for this audience.
example: Travel audience
integrationId:
type: string
minLength: 1
maxLength: 1000
description: The ID of this audience in the third-party integration.
example: 382370BKDB946
additionalProperties: false
MultipleAudiencesItem:
type: object
description: ''
required:
- id
- created
- name
- integrationId
- status
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
name:
type: string
minLength: 1
description: The human-friendly display name for this audience.
example: Travel audience
integrationId:
type: string
minLength: 1
maxLength: 1000
description: The ID of this audience in the third-party integration.
example: 382370BKDB946
status:
type: string
description: >
Indicates whether the audience is new, updated or unmodified by the
request.
enum:
- unmodified
- updated
- new
example: new
additionalProperties: false
NewInternalAudience:
type: object
required:
- name
properties:
name:
type: string
minLength: 1
description: The human-friendly display name for this audience.
example: Travel audience
sandbox:
type: boolean
description: Indicates if this is a live or sandbox Application.
example: true
description:
type: string
description: A description of the audience.
example: Travel audience 18-25
NewAudience:
type: object
description: ''
required:
- name
properties:
name:
type: string
minLength: 1
description: The human-friendly display name for this audience.
example: Travel audience
sandbox:
type: boolean
description: Indicates if this is a live or sandbox Application.
example: true
description:
type: string
description: A description of the audience.
example: Travel audience 18-25
integration:
type: string
description: >
The Talon.One-supported [3rd-party
platform](https://docs.talon.one/docs/dev/technology-partners/overview)
that this audience was created in.
For example, `mParticle`, `Segment`, `Selligent`, `Braze`, or
`Iterable`.
**Note:** If you do not integrate with any of these platforms, do not
use this property.
example: mparticle
integrationId:
type: string
minLength: 1
maxLength: 1000
description: >
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.
example: 382370BKDB946
createdIn3rdParty:
type: boolean
description: Determines if this audience is a 3rd party audience or not.
example: false
lastUpdate:
type: string
format: date-time
description: The last time that the audience memberships changed.
example: '2022-04-26T11:02:38.000Z'
additionalProperties: false
UpdateAudience:
type: object
required:
- name
properties:
name:
type: string
minLength: 1
description: The human-friendly display name for this audience.
example: Travel audience
Audience:
type: object
description: ''
required:
- accountId
- id
- created
- name
properties:
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
name:
type: string
minLength: 1
description: The human-friendly display name for this audience.
example: Travel audience
sandbox:
type: boolean
description: Indicates if this is a live or sandbox Application.
example: true
description:
type: string
description: A description of the audience.
example: Travel audience 18-25
integration:
type: string
description: >
The Talon.One-supported [3rd-party
platform](https://docs.talon.one/docs/dev/technology-partners/overview)
that this audience was created in.
For example, `mParticle`, `Segment`, `Selligent`, `Braze`, or
`Iterable`.
**Note:** If you do not integrate with any of these platforms, do not
use this property.
example: mparticle
integrationId:
type: string
minLength: 1
maxLength: 1000
description: >
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.
example: 382370BKDB946
createdIn3rdParty:
type: boolean
description: Determines if this audience is a 3rd party audience or not.
example: false
lastUpdate:
type: string
format: date-time
description: The last time that the audience memberships changed.
example: '2022-04-26T11:02:38.000Z'
additionalProperties: false
AudienceAnalytics:
type: object
description: The audiences and their members count.
properties:
audienceId:
type: integer
description: The ID of the audience.
example: 1
membersCount:
type: integer
description: The count of members under a single audience.
example: 1234
ManagerConfig:
type: object
required:
- schemaVersion
properties:
schemaVersion:
type: integer
additionalProperties: true
Export:
type: object
description: ''
required:
- id
- created
- accountId
- userId
- entity
- filter
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
userId:
type: integer
description: The ID of the user associated with this entity.
example: 388
entity:
type: string
enum:
- Coupon
- Referral
- Effect
- CustomerSession
- LoyaltyLedger
- LoyaltyLedgerLog
- Collection
description: The name of the entity that was exported.
filter:
type: object
description: Map of keys and values that were used to filter the exported rows.
additionalProperties: true
additionalProperties: false
Import:
type: object
description: ''
required:
- id
- created
- accountId
- userId
- amount
- entity
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
userId:
type: integer
description: The ID of the user associated with this entity.
example: 388
entity:
type: string
example: AttributeAllowedList
description: |
The name of the entity that was imported.
amount:
type: integer
minimum: 0
example: 10
description: The number of values that were imported.
additionalProperties: false
FeaturesFeed:
type: object
description: ''
properties:
title:
type: string
pubDate:
type: string
additionalProperties: false
LibraryAttribute:
type: object
description: ''
required:
- entity
- name
- title
- type
- description
- presets
- tags
- suggestions
properties:
entity:
type: string
description: >-
The name of the entity that can have this attribute. When creating or
updating the entities of a given type, you can include an `attributes`
object with keys corresponding to the `name` of the custom attributes
for that type.
enum:
- Application
- Campaign
- CustomerProfile
- CustomerSession
- CartItem
- Coupon
- Event
name:
type: string
description: >
The attribute name that will be used in API requests and Talang. E.g.
if `name == "region"` then you would set the region attribute by
including an `attributes.region` property in your request payload.
title:
type: string
description: >-
The human-readable name for the attribute that will be shown in the
Campaign Manager. Like `name`, the combination of entity and title
must also be unique.
type:
type: string
enum:
- string
- number
- boolean
- time
description: >-
The data type of the attribute, a `time` attribute must be sent as a
string that conforms to the
[RFC3339](https://www.ietf.org/rfc/rfc3339.txt) timestamp format.
description:
type: string
description: A description of the attribute.
presets:
type: array
description: The presets that indicate to which industry the attribute applies to.
items:
type: string
suggestions:
type: array
description: Short suggestions that are used to group attributes.
items:
type: string
additionalProperties: false
TalangAttribute:
type: object
description: ''
required:
- name
- type
- visible
- kind
- campaignsCount
properties:
entity:
type: string
description: The name of the entity of the attribute.
enum:
- AdvocateProfile
- Account
- Application
- AwardedGiveaway
- Bundle
- Campaign
- CartItem
- Coupon
- CustomerProfile
- CustomerSession
- Event
- Item
- Loyalty
- Profile
- Giveaway
- Referral
- Session
- Store
name:
type: string
description: >
The attribute name that will be used in API requests and Talang. E.g.
if `name == "region"` then you would set the region attribute by
including an `attributes.region` property in your request payload.
title:
type: string
description: >-
The name of the attribute that is displayed to the user in the
Campaign Manager.
type:
type: string
description: The talang type of the attribute.
description:
type: string
description: A description of the attribute.
visible:
type: boolean
default: true
description: Indicates whether the attribute is visible in the UI or not.
kind:
type: string
description: Indicate the kind of the attribute.
enum:
- built-in
- custom
campaignsCount:
type: integer
description: The number of campaigns that refer to the attribute.
exampleValue:
type: array
description: Examples of values that can be assigned to the attribute.
items:
type: string
additionalProperties: false
TalangAttributeVisibility:
type: object
properties:
invisible:
type: array
description: List of attribute names to hide in the UI.
items:
type: string
visible:
type: array
description: List of attribute names to show in the UI.
items:
type: string
Role:
type: object
description: ''
required:
- id
- created
- modified
- accountId
- name
- acl
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
campaignGroupID:
type: integer
description: >
The ID of the [Campaign
Group](https://docs.talon.one/docs/product/account/account-settings/managing-campaign-groups)
this role was created for.
example: 3
name:
type: string
description: Name of the role.
example: Campaign Reviewer
description:
type: string
description: Description of the role.
example: Reviews the campaigns
members:
type: array
items:
type: integer
description: A list of user identifiers assigned to this role.
example:
- 48
- 562
- 475
- 18
acl:
type: object
format: aclRole
description: >-
The `Access Control List` json defining the role of the user. This
represents the access control on the user level.
example:
Role: 127
Applications: null
additionalProperties: false
NewRole:
type: object
description: ''
required:
- name
- acl
- members
properties:
name:
type: string
description: Name of the role.
example: Campaign Manager
description:
type: string
description: Description of the role.
example: Manages the campaigns
acl:
type: string
description: >-
The `Access Control List` json defining the role of the user. This
represents the access control on the user level.
example:
Role: 128
Applications: null
members:
type: array
items:
type: integer
description: An array of user identifiers.
example:
- 48
- 562
- 475
- 18
additionalProperties: false
UpdateRole:
type: object
properties:
name:
type: string
description: Name of the role.
example: Campaign Manager
description:
type: string
description: Description of the role.
example: Manages the campaigns
acl:
type: string
description: >-
The `Access Control List` json defining the role of the user. This
represents the access control on the user level.
example:
Role: 128
Applications: null
members:
type: array
items:
type: integer
description: An array of user identifiers.
example:
- 48
- 562
- 475
- 18
RoleAssign:
type: object
description: ''
required:
- users
- roles
properties:
users:
type: array
items:
type: integer
description: An array of user IDs.
example:
- 48
- 562
- 475
- 18
roles:
type: array
items:
type: integer
description: An array of role IDs.
example:
- 128
- 147
additionalProperties: false
NewRoleV2:
type: object
description: ''
required:
- name
- description
properties:
name:
type: string
description: Name of the role.
example: Campaign and campaign access group manager
description:
type: string
description: Description of the role.
example: >-
Allows you to create and edit campaigns for specific Applications,
delete specific campaign access groups, and view loyalty programs.
permissions:
type: object
$ref: '#/definitions/RoleV2Permissions'
description: The permissions that this role gives.
members:
type: array
items:
type: integer
description: A list of user identifiers the role is assigned to.
example:
- 10
- 12
additionalProperties: false
UpdateRoleV2:
$ref: '#/definitions/RoleV2Base'
RoleV2:
type: object
description: ''
required:
- id
- created
- modified
- accountId
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
name:
type: string
description: Name of the role.
example: Campaign and campaign access group manager
description:
type: string
description: Description of the role.
example: >-
Allows you to create and edit campaigns for specific Applications,
delete specific campaign access groups, and view loyalty programs.
permissions:
type: object
$ref: '#/definitions/RoleV2Permissions'
description: The permissions that this role gives.
members:
type: array
items:
type: integer
description: A list of user identifiers the role is assigned to.
example:
- 10
- 12
additionalProperties: false
RoleV2Base:
type: object
properties:
name:
type: string
description: Name of the role.
example: Campaign and campaign access group manager
description:
type: string
description: Description of the role.
example: >-
Allows you to create and edit campaigns for specific Applications,
delete specific campaign access groups, and view loyalty programs.
permissions:
type: object
$ref: '#/definitions/RoleV2Permissions'
description: The permissions that this role gives.
members:
type: array
items:
type: integer
description: A list of user identifiers the role is assigned to.
example:
- 10
- 12
RoleV2Permissions:
type: object
properties:
permissionSets:
type: array
description: >-
List of grouped logical operations to use as a reference in the roles
section. Each group of logical operations has a name.
maxItems: 100
items:
type: object
$ref: '#/definitions/RoleV2PermissionSet'
example:
- name: Application permission set
logicalOperations:
- getApplicationOperations
- editApplicationOperations
- name: Campaign manager permission set
logicalOperations:
- getCampaignOperations
- createCampaignOperations
- updateCampaignOperations
- name: Campaign read-only permission set
logicalOperations:
- getCampaignOperations
- name: Loyalty program read-only permission set
logicalOperations:
- getLoyaltyProgramOperations
- name: Campaign access group manager permission set
logicalOperations:
- getCampaignAccessGroupOperations
- updateCampaignAccessGroupOperations
- deleteCampaignAccessGroupOperations
roles:
type: object
$ref: '#/definitions/RoleV2RolesGroup'
RoleV2RolesGroup:
type: object
properties:
applications:
type: object
$ref: '#/definitions/RoleV2Application'
loyaltyPrograms:
type: object
$ref: '#/definitions/RoleV2LoyaltyGroup'
campaignAccessGroups:
type: object
$ref: '#/definitions/RoleV2CampaignAccessGroup'
RoleV2Application:
type: object
description: >-
A map of the link between the Application, campaign, or draft
campaign-related permission set and the Application ID the permissions
apply to.
additionalProperties:
type: object
$ref: '#/definitions/RoleV2ApplicationDetails'
example:
'1':
application: Application permission set
'3':
campaign: Campaign manager permission set
'4':
draftCampaign: Campaign read-only permission set
'5':
tools: Tools permission set
RoleV2ApplicationDetails:
type: object
properties:
application:
type: string
description: >-
Name of the Application-related permission set for the given
Application.
campaign:
type: string
description: Name of the campaign-related permission set for the given Application.
draftCampaign:
type: string
description: >-
Name of the draft campaign-related permission set for the given
Application.
tools:
type: string
description: Name of the tools-related permission set.
example: Tools permission set
RoleV2LoyaltyGroup:
type: object
description: >-
A map of the link between the loyalty program-related permission set and
the Application ID the permissions apply to.
additionalProperties:
type: string
description: Name of the loyalty program-related permission set.
example:
'10': Loyalty program manager permission set
RoleV2CampaignAccessGroup:
type: object
description: >-
A map of the link between the campaign access group-related permission set
and the Application ID the permissions apply to.
additionalProperties:
type: string
description: Name of the campaign access group-related permission set.
example:
'5': Campaign access group manager permission set
RoleV2PermissionSet:
type: object
required:
- name
- logicalOperations
properties:
name:
type: string
description: Name of the permission set.
example: Campaign manager permission set
logicalOperations:
type: array
maxItems: 1000
description: >
List of logical operations in the permission set.
Each logical operation must be shown under the `x-permission` tag on
an endpoint level.
items:
type: string
example:
- createCampaignOperations
- getCampaignOperations
- deleteCampaignOperations
RoleMembership:
type: object
required:
- RoleID
- UserID
properties:
RoleID:
type: integer
description: ID of role.
UserID:
type: integer
description: ID of User.
CouponReservations:
type: object
required:
- integrationIDs
properties:
integrationIDs:
type: array
description: List of customer integration IDs.
example:
- URNGV8294NV
- BZGGC2454PA
maxItems: 1000
items:
type: string
LedgerEntry:
type: object
description: ''
required:
- id
- created
- eventId
- accountId
- profileId
- loyaltyProgramId
- amount
- reason
- expiryDate
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
profileId:
type: string
description: >
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`.
example: URNGV8294NV
accountId:
type: integer
description: The ID of the Talon.One account that owns this profile.
loyaltyProgramId:
type: integer
description: ID of the ledger.
example: 323414846
eventId:
type: integer
description: ID of the related event.
example: 3
amount:
type: integer
description: Amount of loyalty points.
example: 100
reason:
type: string
description: reason for awarding/deducting points.
example: Customer appeasement.
expiryDate:
type: string
format: date-time
description: Expiration date of the points.
example: '2022-04-26T11:02:38.000Z'
referenceId:
type: integer
description: The ID of the balancing ledgerEntry.
additionalProperties: false
LoyaltyMembership:
type: object
required:
- loyaltyProgramId
properties:
joined:
type: string
format: date-time
title: Loyalty program joined at
description: The moment in which the loyalty program was joined.
example: 2012-03-20T14:15:22.000Z
loyaltyProgramId:
type: integer
title: Loyalty program ID
description: The ID of the loyalty program belonging to this entity.
example: 323414846
Meta:
type: object
properties:
campaigns:
description: >-
Maps each evaluated campaign ID to a key-value list of that campaigns
attributes. Campaigns without attributes will be omitted.
type: object
additionalProperties: true
coupons:
description: Maps the coupon value to a key-value list of that coupons attributes.
type: object
additionalProperties: true
couponRejectionReason:
$ref: '#/definitions/CouponRejectionReason'
referralRejectionReason:
$ref: '#/definitions/ReferralRejectionReason'
warnings:
description: Contains warnings about possible misuse.
type: object
additionalProperties: true
CouponRejectionReason:
description: >-
Holds a reference to the campaign, the coupon and the reason for which
that coupon was rejected. Should only be present when there is a
'rejectCoupon' effect.
type: object
required:
- campaignId
- couponId
- reason
properties:
campaignId:
type: integer
example: 244
couponId:
type: integer
example: 4928
reason:
type: string
enum:
- CouponNotFound
- CouponPartOfNotRunningCampaign
- CampaignLimitReached
- ProfileLimitReached
- CouponRecipientDoesNotMatch
- CouponExpired
- CouponStartDateInFuture
- CouponRejectedByCondition
- EffectCouldNotBeApplied
- CouponPartOfNotTriggeredCampaign
- CouponReservationRequired
- ProfileRequired
example: CouponNotFound
ReferralRejectionReason:
description: >-
Holds a reference to the campaign, the referral and the reason for which
that referral was rejected. Should only be present when there is a
'rejectReferral' effect.
type: object
required:
- campaignId
- referralId
- reason
properties:
campaignId:
type: integer
referralId:
type: integer
reason:
type: string
enum:
- ReferralNotFound
- ReferralRecipientIdSameAsAdvocate
- ReferralPartOfNotRunningCampaign
- ReferralLimitReached
- CampaignLimitReached
- ProfileLimitReached
- ReferralRecipientDoesNotMatch
- ReferralExpired
- ReferralStartDateInFuture
- ReferralRejectedByCondition
- EffectCouldNotBeApplied
- ReferralPartOfNotTriggeredCampaign
example: ReferralNotFound
ApplicationAPIKey:
type: object
description: ''
required:
- title
- expires
- id
- accountID
- applicationID
- created
- createdBy
properties:
title:
type: string
description: Title for API Key.
example: My generated key
expires:
type: string
format: date-time
description: The date the API key expired.
example: '2023-08-24T14:00:00Z'
platform:
type: string
enum:
- none
- segment
- braze
- mparticle
- selligent
- iterable
- customer_engagement
- customer_data
- salesforce
description: >
The third-party platform the API key is valid for. Use `none` for a
generic API key to be used
from your own integration layer.
example: none
id:
type: integer
description: ID of the API Key.
example: 34
createdBy:
type: integer
description: ID of user who created.
example: 280
accountID:
type: integer
description: ID of account the key is used for.
example: 13
applicationID:
type: integer
description: ID of application the key is used for.
example: 54
created:
type: string
format: date-time
description: The date the API key was created.
example: '2022-03-02T16:46:17.758585Z'
additionalProperties: false
NewApplicationAPIKey:
type: object
description: ''
required:
- title
- expires
- id
- accountID
- applicationID
- created
- createdBy
- key
properties:
title:
type: string
description: Title for API Key.
example: My generated key
expires:
type: string
format: date-time
description: The date the API key expired.
example: '2023-08-24T14:00:00Z'
platform:
type: string
enum:
- none
- segment
- braze
- mparticle
- selligent
- iterable
- customer_engagement
- customer_data
- salesforce
description: >
The third-party platform the API key is valid for. Use `none` for a
generic API key to be used
from your own integration layer.
example: none
id:
type: integer
description: ID of the API Key.
example: 34
createdBy:
type: integer
description: ID of user who created.
example: 280
accountID:
type: integer
description: ID of account the key is used for.
example: 13
applicationID:
type: integer
description: ID of application the key is used for.
example: 54
created:
type: string
format: date-time
description: The date the API key was created.
example: '2022-03-02T16:46:17.758585Z'
key:
type: string
description: The API key.
example: f45f90d21dcd9bac965c45e547e9754a3196891d09948e35adbcbedc4e9e4b01
additionalProperties: false
CreateApplicationAPIKey:
type: object
required:
- title
- expires
properties:
title:
type: string
description: Title for API Key.
example: My generated key
expires:
type: string
format: date-time
description: The date the API key expired.
example: '2023-08-24T14:00:00Z'
platform:
type: string
enum:
- none
- segment
- braze
- mparticle
- selligent
- iterable
- customer_engagement
- customer_data
- salesforce
description: >
The third-party platform the API key is valid for. Use `none` for a
generic API key to be used
from your own integration layer.
example: none
CreateManagementKey:
type: object
required:
- name
- expiryDate
- endpoints
properties:
name:
type: string
description: Name for management key.
example: My generated key
expiryDate:
type: string
format: date-time
description: The date the management key expires.
example: '2023-08-24T14:00:00Z'
endpoints:
type: array
description: The list of endpoints that can be accessed with the key
items:
$ref: '#/definitions/Endpoint'
allowedApplicationIds:
type: array
description: >
A list of Application IDs that you can access with the management key.
An empty or missing list means the management key can be used for all
Applications in the account.
items:
type: integer
example:
- 1
- 2
- 3
ManagementKey:
type: object
description: ''
required:
- name
- expiryDate
- endpoints
- id
- accountID
- created
- createdBy
properties:
name:
type: string
description: Name for management key.
example: My generated key
expiryDate:
type: string
format: date-time
description: The date the management key expires.
example: '2023-08-24T14:00:00Z'
endpoints:
type: array
description: The list of endpoints that can be accessed with the key
items:
$ref: '#/definitions/Endpoint'
allowedApplicationIds:
type: array
description: >
A list of Application IDs that you can access with the management key.
An empty or missing list means the management key can be used for all
Applications in the account.
items:
type: integer
example:
- 1
- 2
- 3
id:
type: integer
description: ID of the management key.
example: 34
createdBy:
type: integer
description: ID of the user who created it.
example: 280
accountID:
type: integer
description: ID of account the key is used for.
example: 13
created:
type: string
format: date-time
description: The date the management key was created.
example: '2022-03-02T16:46:17.758585Z'
additionalProperties: false
NewManagementKey:
type: object
description: ''
required:
- name
- expiryDate
- endpoints
- id
- accountID
- created
- createdBy
- key
properties:
name:
type: string
description: Name for management key.
example: My generated key
expiryDate:
type: string
format: date-time
description: The date the management key expires.
example: '2023-08-24T14:00:00Z'
endpoints:
type: array
description: The list of endpoints that can be accessed with the key
items:
$ref: '#/definitions/Endpoint'
allowedApplicationIds:
type: array
description: >
A list of Application IDs that you can access with the management key.
An empty or missing list means the management key can be used for all
Applications in the account.
items:
type: integer
example:
- 1
- 2
- 3
id:
type: integer
description: ID of the management key.
example: 34
createdBy:
type: integer
description: ID of the user who created it.
example: 280
accountID:
type: integer
description: ID of account the key is used for.
example: 13
created:
type: string
format: date-time
description: The date the management key was created.
example: '2022-03-02T16:46:17.758585Z'
key:
type: string
description: The management key.
example: f45f90d21dcd9bac965c45e547e9754a3196891d09948e35adbcbedc4e9e4b01
additionalProperties: false
Endpoint:
type: object
required:
- path
properties:
path:
type: string
description: allowed endpoint
example: /coupons
Notification:
type: object
required:
- id
- name
- description
properties:
id:
type: integer
description: id of the notification.
name:
type: string
description: name of the notification.
description:
type: string
description: description of the notification.
Notifications:
type: array
items:
$ref: '#/definitions/Notification'
SamlConnection:
type: object
description: ''
required:
- assertionConsumerServiceURL
- audienceURI
- accountId
- name
- enabled
- issuer
- signOnURL
- id
- created
properties:
assertionConsumerServiceURL:
type: string
description: The location where the SAML assertion is sent with a HTTP POST.
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3885
name:
type: string
description: ID of the SAML service.
minLength: 1
enabled:
type: boolean
description: Determines if this SAML connection active.
issuer:
type: string
description: Identity Provider Entity ID.
minLength: 1
signOnURL:
type: string
description: Single Sign-On URL.
minLength: 1
signOutURL:
type: string
description: Single Sign-Out URL.
metadataURL:
type: string
description: Metadata URL.
audienceURI:
type: string
description: >
The application-defined unique identifier that is the intended
audience of the SAML assertion.
This is most often the SP Entity ID of your application. When not
specified, the ACS URL will be used.
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
additionalProperties: false
NewSamlConnection:
type: object
description: ''
required:
- x509certificate
- accountId
- name
- enabled
- issuer
- signOnURL
properties:
x509certificate:
type: string
description: X.509 Certificate.
minLength: 1
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3885
name:
type: string
description: ID of the SAML service.
minLength: 1
enabled:
type: boolean
description: Determines if this SAML connection active.
issuer:
type: string
description: Identity Provider Entity ID.
minLength: 1
signOnURL:
type: string
description: Single Sign-On URL.
minLength: 1
signOutURL:
type: string
description: Single Sign-Out URL.
metadataURL:
type: string
description: Metadata URL.
audienceURI:
type: string
description: >
The application-defined unique identifier that is the intended
audience of the SAML assertion.
This is most often the SP Entity ID of your application. When not
specified, the ACS URL will be used.
additionalProperties: false
SamlConnectionMetadata:
type: object
required:
- name
- enabled
- accountId
- metadataDocument
properties:
name:
type: string
description: ID of the SAML service.
minLength: 1
enabled:
type: boolean
description: Determines if this SAML connection active.
accountId:
type: number
metadataDocument:
type: string
description: Identity Provider metadata XML document.
minLength: 1
BaseSamlConnection:
type: object
required:
- accountId
- name
- enabled
- issuer
- signOnURL
properties:
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3885
name:
type: string
description: ID of the SAML service.
minLength: 1
enabled:
type: boolean
description: Determines if this SAML connection active.
issuer:
type: string
description: Identity Provider Entity ID.
minLength: 1
signOnURL:
type: string
description: Single Sign-On URL.
minLength: 1
signOutURL:
type: string
description: Single Sign-Out URL.
metadataURL:
type: string
description: Metadata URL.
audienceURI:
type: string
description: >
The application-defined unique identifier that is the intended
audience of the SAML assertion.
This is most often the SP Entity ID of your application. When not
specified, the ACS URL will be used.
SamlLoginEndpoint:
type: object
required:
- name
- loginURL
properties:
name:
type: string
description: ID of the SAML service.
minLength: 1
loginURL:
type: string
description: Single Sign-On URL.
minLength: 1
TwoFAConfig:
type: object
required:
- enabled
properties:
enabled:
type: boolean
description: >-
An indication of whether two-factor authentication is enabled for the
account.
example: true
requireEverySignIn:
type: boolean
description: >
Can be `true` or `false`.
- `true`: Two-factor authentication is required each time a user signs
in to their Talon.One account.
- `false`: Two-factor authentication is only required when a user
signs in to their Talon.One account on a new device, and every 30 days
after that.
example: true
SSOConfig:
type: object
required:
- enforced
properties:
enforced:
type: boolean
description: >
An indication of whether single sign-on is enforced for the account.
When enforced, users cannot use their email and password to sign in to
Talon.One.
It is not possible to change this to `false` after it is set to
`true`.
example: true
Effect:
type: object
description: ''
required:
- campaignId
- rulesetId
- ruleIndex
- ruleName
- effectType
- props
properties:
campaignId:
type: integer
description: The ID of the campaign that triggered this effect.
example: 244
rulesetId:
type: integer
description: >-
The ID of the ruleset that was active in the campaign when this effect
was triggered.
example: 73
ruleIndex:
type: integer
description: >-
The position of the rule that triggered this effect within the
ruleset.
example: 2
ruleName:
type: string
description: The name of the rule that triggered this effect.
example: Give 20% discount
effectType:
type: string
description: >-
The type of effect that was triggered. See [API
effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
example: rejectCoupon
triggeredByCoupon:
type: integer
example: 4928
description: >-
The ID of the coupon that was being evaluated when this effect was
triggered.
triggeredForCatalogItem:
type: integer
example: 786
description: >-
The ID of the catalog item that was being evaluated when this effect
was triggered.
conditionIndex:
type: integer
example: 786
description: The index of the condition that was triggered.
props:
$ref: '#/definitions/EffectProps'
additionalProperties: false
EffectEntity:
type: object
description: >-
Definition of all properties that are present on all effects, independent
of their type.
required:
- campaignId
- rulesetId
- ruleIndex
- ruleName
- effectType
properties:
campaignId:
type: integer
description: The ID of the campaign that triggered this effect.
example: 244
rulesetId:
type: integer
description: >-
The ID of the ruleset that was active in the campaign when this effect
was triggered.
example: 73
ruleIndex:
type: integer
description: >-
The position of the rule that triggered this effect within the
ruleset.
example: 2
ruleName:
type: string
description: The name of the rule that triggered this effect.
example: Give 20% discount
effectType:
type: string
description: >-
The type of effect that was triggered. See [API
effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
example: rejectCoupon
triggeredByCoupon:
type: integer
example: 4928
description: >-
The ID of the coupon that was being evaluated when this effect was
triggered.
triggeredForCatalogItem:
type: integer
example: 786
description: >-
The ID of the catalog item that was being evaluated when this effect
was triggered.
conditionIndex:
type: integer
example: 786
description: The index of the condition that was triggered.
EffectProps:
type: object
description: >-
The properties of the effect. See [API
effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
AcceptCouponEffectProps:
type: object
description: >-
The properties specific to the "acceptCoupon" effect. This gets triggered
whenever the coupon is valid and all other conditions in the rules of its
campaign are met.
required:
- value
properties:
value:
type: string
description: The coupon code that was accepted.
AcceptReferralEffectProps:
type: object
description: >-
The properties specific to the "acceptReferral" effect. TThis gets
triggered whenever the referral code is valid and all other conditions in
the rules of its campaign are met.
required:
- value
properties:
value:
type: string
description: The referral code that was accepted.
RedeemReferralEffectProps:
type: object
description: >
This effect is **deprecated**. The properties specific to the
"redeemReferral" effect.
This gets triggered whenever the referral code is valid, and a rule was
triggered that contains a "redeem referral" effect.
required:
- id
- value
properties:
id:
type: integer
description: The id of the referral code that was redeemed.
value:
type: string
description: The referral code that was redeemed.
RejectCouponEffectProps:
type: object
description: >-
The properties specific to the "rejectCoupon" effect. This gets triggered
whenever the coupon was rejected. See rejectionReason for more info on
why.
required:
- value
- rejectionReason
properties:
value:
type: string
description: The coupon code that was rejected.
rejectionReason:
type: string
description: The reason why this coupon was rejected.
conditionIndex:
type: integer
description: The index of the condition that caused the rejection of the coupon.
effectIndex:
type: integer
description: The index of the effect that caused the rejection of the coupon.
details:
type: string
description: More details about the failure.
RejectReferralEffectProps:
type: object
description: >-
The properties specific to the "rejectReferral" effect. This gets
triggered whenever the referral code was rejected. See rejectionReason for
more info on why.
required:
- value
- rejectionReason
properties:
value:
type: string
description: The referral code that was rejected.
rejectionReason:
type: string
description: The reason why this referral code was rejected.
conditionIndex:
type: integer
description: The index of the condition that caused the rejection of the referral.
effectIndex:
type: integer
description: The index of the effect that caused the rejection of the referral.
details:
type: string
description: More details about the failure.
CouponCreatedEffectProps:
type: object
description: >-
The properties specific to the "couponCreated" effect. This gets triggered
whenever a validated rule contained a "create coupon" effect, and a coupon
was created for a customer. See "createdCoupons" on the response for all
details of this coupon.
required:
- value
- profileId
properties:
value:
type: string
description: The coupon code that was created.
profileId:
type: string
description: >-
The integration identifier of the customer for whom this coupon was
created.
ReferralCreatedEffectProps:
type: object
description: >-
The properties specific to the "referralCreated" effect. This gets
triggered whenever a validated rule contained a "create referral" effect,
and a referral code was created for a customer. See "createdReferrals" on
the response for all details of this referral code.
required:
- value
properties:
value:
type: string
description: The referral code that was created.
SetDiscountEffectProps:
type: object
description: >-
The properties specific to the "setDiscount" effect. This gets triggered
whenever a validated rule contained a "set discount" effect. This is a
discount that should be applied on the scope of defined with it.
required:
- name
- value
properties:
name:
type: string
description: The name / description of this discount
value:
type: number
description: The total monetary value of the discount.
scope:
type: string
description: >-
The scope which the discount was applied on, can be one of
(cartItems,additionalCosts,sessionTotal).
desiredValue:
type: number
description: The original value of the discount.
SetDiscountPerItemEffectProps:
type: object
description: >
The properties specific to the `setDiscountPerItem` effect, triggered
whenever a validated rule contained a
"set per item discount" effect.
This is a discount that will be applied either on a specific item, on a
specific item + additional cost or on all additional costs per item.
This depends on the chosen scope.
required:
- name
- value
- position
properties:
name:
type: string
description: >
The name of the discount. Contains a hashtag character indicating the
index of the position of the item the discount applies
to. It is identical to the value of the `position` property.
value:
type: number
description: The total monetary value of the discount.
position:
type: number
description: >-
The index of the item in the cart items list on which this discount
should be applied.
subPosition:
type: number
description: >
For cart items with `quantity` > 1, the sub position indicates which
item the discount applies to.
desiredValue:
type: number
description: The original value of the discount.
scope:
type: string
description: >
The scope of the discount:
- `additionalCosts`: The discount applies to all the additional costs
of the item.
- `itemTotal`: The discount applies to the price of the item + the
additional costs of the item.
- `price`: The discount applies to the price of the item.
totalDiscount:
type: number
description: >-
The total discount given if this effect is a result of a prorated
discount.
desiredTotalDiscount:
type: number
description: >-
The original total discount to give if this effect is a result of a
prorated discount.
bundleIndex:
type: integer
description: >-
The position of the bundle in a list of item bundles created from the
same bundle definition.
bundleName:
type: string
description: The name of the bundle definition.
targetedItemPosition:
type: number
description: >-
The index of the targeted bundle item on which the applied discount is
based.
targetedItemSubPosition:
type: number
description: >
The sub-position of the targeted bundle item on which the applied
discount is based.
SetDiscountPerAdditionalCostPerItemEffectProps:
type: object
description: >-
The properties specific to the "setDiscountPerAdditionalCostPerItem"
effect. This gets triggered whenever a validated rule contained a "set
discount per additional cost per item" effect. This is a discount that
should be applied on a specific additional cost in a specific item.
required:
- name
- value
- additionalCostId
- additionalCost
- position
properties:
name:
type: string
description: The name / description of this discount
additionalCostId:
type: integer
description: The ID of the additional cost.
value:
type: number
description: The total monetary value of the discount.
position:
type: number
description: >-
The index of the item in the cart item list containing the additional
cost to be discounted.
subPosition:
type: number
description: >
For cart items with `quantity` > 1, the sub position indicates which
item the discount applies to.
additionalCost:
type: string
description: The name of the additional cost.
desiredValue:
type: number
description: >
Only with [partial discounts
enabled](https://docs.talon.one/docs/product/campaigns/campaign-evaluation/#partial-discounts).
Represents the monetary value of the discount to be applied to
additional discount without considering budget limitations.
ReserveCouponEffectProps:
type: object
description: >-
The properties specific to the "reserveCoupon" effect. This gets triggered
whenever a validated rule contained a "reserve coupon" effect. This
reserves the coupon currently on scope to the profile on scope.
required:
- couponValue
- profileIntegrationId
- isNewReservation
properties:
couponValue:
type: string
description: The value of the coupon currently on scope.
profileIntegrationId:
type: string
description: The ID of this customer profile in the third-party integration.
isNewReservation:
type: boolean
description: Indicates whether this is a new coupon reservation or not.
SetDiscountPerAdditionalCostEffectProps:
type: object
description: >-
The properties specific to the "setDiscountPerAdditionalCost" effect. This
gets triggered whenever a validated rule contained a "set per additional
cost discount" effect. This is a discount that should be applied on a
specific additional cost.
required:
- name
- value
- additionalCostId
- additionalCost
properties:
name:
type: string
description: The name / description of this discount
additionalCostId:
type: integer
description: The ID of the additional cost.
additionalCost:
type: string
description: The name of the additional cost.
value:
type: number
description: The total monetary value of the discount.
desiredValue:
type: number
description: The original value of the discount.
TriggerWebhookEffectProps:
type: object
description: >-
The properties specific to the "triggerWebhook" effect. This gets
triggered whenever a validated rule contained a "trigger webhook" effect.
This is communicated as an FYI and should usually not require action on
your side.
required:
- webhookId
- webhookName
properties:
webhookId:
type: number
description: The ID of the webhook that was triggered.
webhookName:
type: string
description: The name of the webhook that was triggered.
AddLoyaltyPointsEffectProps:
type: object
description: >
The properties specific to the "addLoyaltyPoints" effect. This gets
triggered whenever a validated rule contained an "add loyalty" effect.
These points are automatically stored and managed inside Talon.One.
required:
- name
- programId
- subLedgerId
- value
- recipientIntegrationId
- transactionUUID
properties:
name:
type: string
description: The name / description of this loyalty point addition.
programId:
type: integer
description: The ID of the loyalty program where these points were added.
subLedgerId:
type: string
description: >-
The ID of the subledger within the loyalty program where these points
were added.
value:
type: number
description: The amount of points that were added.
desiredValue:
type: number
description: The original amount of loyalty points to be awarded.
recipientIntegrationId:
type: string
maxLength: 1000
description: The user for whom these points were added.
example: URNGV8294NV
startDate:
type: string
format: date-time
description: Date after which points will be valid.
expiryDate:
type: string
format: date-time
description: Date after which points will expire.
transactionUUID:
type: string
description: The identifier of this addition in the loyalty ledger.
cartItemPosition:
type: number
description: >-
The index of the item in the cart items list on which the loyal points
addition should be applied.
cartItemSubPosition:
type: number
description: >
For cart items with `quantity` > 1, the sub position indicates to
which item the loyalty points addition is applied.
cardIdentifier:
description: The card on which these points were added.
$ref: '#/definitions/LoyaltyCardIdentifier'
bundleIndex:
type: integer
description: >-
The position of the bundle in a list of item bundles created from the
same bundle definition.
bundleName:
type: string
description: The name of the bundle definition.
DeductLoyaltyPointsEffectProps:
type: object
description: >-
The properties specific to the "deductLoyaltyPoints" effect. This gets
triggered whenever a validated rule contained a condition to only trigger
when the given number of loyalty points could be deduced. These points are
automatically stored and managed inside Talon.One.
required:
- ruleTitle
- programId
- subLedgerId
- value
- transactionUUID
- name
properties:
ruleTitle:
type: string
description: The title of the rule that contained triggered this points deduction.
programId:
type: integer
description: The ID of the loyalty program where these points were added.
subLedgerId:
type: string
description: >-
The ID of the subledger within the loyalty program where these points
were added.
value:
type: number
description: The amount of points that were deducted.
transactionUUID:
type: string
description: The identifier of this deduction in the loyalty ledger.
name:
type: string
description: >
The name property gets one of the following two values. It can be the
loyalty program name or it can represent a reason for the respective
deduction of loyalty points. The latter is an optional value defined
in a deduction rule.
cardIdentifier:
description: The card on which these points were added.
$ref: '#/definitions/LoyaltyCardIdentifier'
ChangeLoyaltyTierLevelEffectProps:
type: object
description: >
The properties specific to the "changeLoyaltyTierLevel" effect.
This is triggered whenever the user's loyalty tier is upgraded or
downgraded
due to a validated rule that contained an "add loyalty points" effect.
required:
- ruleTitle
- programId
- subLedgerId
- newTierName
properties:
ruleTitle:
type: string
description: The title of the rule that triggered the tier upgrade or downgrade.
programId:
type: integer
description: The ID of the loyalty program where these points were added.
subLedgerId:
type: string
description: >-
The ID of the subledger within the loyalty program where these points
were added.
previousTierName:
type: string
description: The name of the tier from which the user was upgraded or downgraded.
newTierName:
type: string
description: >-
The name of the tier to which the user has been upgraded or
downgraded.
expiryDate:
type: string
format: date-time
description: The expiration date of the new tier.
AddFreeItemEffectProps:
type: object
description: >-
The properties specific to the "addFreeItem" effect. This gets triggered
whenever a validated rule contained an "add free item" effect.
required:
- sku
- name
properties:
sku:
type: string
description: SKU of the item that needs to be added.
example: SKU1241028
name:
type: string
description: The name / description of the effect
ShowNotificationEffectProps:
type: object
description: >-
The properties specific to the "showNotification" effect. This gets
triggered whenever a validated rule contained a "show notification"
effect.
required:
- notificationType
- title
- body
properties:
notificationType:
type: string
description: >-
The type of notification that should be shown (e.g.
error/warning/info).
title:
type: string
description: Title of the notification.
body:
type: string
description: Body of the notification.
UpdateAttributeEffectProps:
type: object
description: >-
The properties specific to the "updateAttribute" effect. This gets
triggered whenever a validated rule contained an "update an attribute"
effect.
required:
- path
- value
properties:
path:
type: string
description: The exact path of the attribute that was updated.
value:
anyOf:
- type: string
- type: number
- type: integer
- type: boolean
- type: array
items: {}
- type: object
description: >
The new value of this attribute. The value can be of the following
types:
- boolean
- location
- number
- string
- time
- list of any of those types
RollbackCouponEffectProps:
type: object
description: >-
The properties specific to the "rollbackCoupon" effect. This gets
triggered whenever previously closed session is now cancelled and a coupon
redemption was cancelled on our internal usage limit counters.
required:
- value
properties:
value:
type: string
description: The coupon code whose usage has been rolled back.
RollbackReferralEffectProps:
type: object
description: >-
The properties specific to the "rollbackReferral" effect. This gets
triggered whenever previously closed session is now cancelled and a
referral redemption was cancelled on our internal usage limit counters.
required:
- value
properties:
value:
type: string
description: The referral code whose usage has been rolled back.
RollbackDiscountEffectProps:
type: object
description: >-
The properties specific to the "rollbackDiscount" effect. This gets
triggered whenever previously closed session is now cancelled or partially
returned and a setDiscount effect was cancelled on our internal discount
limit counters.
required:
- name
- value
properties:
name:
type: string
description: The name of the "setDiscount" effect that was rolled back.
value:
type: number
description: The value of the discount that was rolled back.
cartItemPosition:
type: number
description: >-
The index of the item in the cart items for which the discount was
rolled back.
cartItemSubPosition:
type: number
description: >
For cart items with `quantity` > 1, the subposition returns the index
of the item unit in its line item.
additionalCostId:
type: integer
description: The ID of the additional cost that was rolled back.
additionalCost:
type: string
description: The name of the additional cost that was rolled back.
scope:
type: string
description: >
The scope of the rolled back discount
- For a discount per session, it can be one of `cartItems`,
`additionalCosts` or `sessionTotal`
- For a discount per item, it can be one of `price`, `additionalCosts`
or `itemTotal`
RollbackAddedLoyaltyPointsEffectProps:
type: object
description: >-
The properties specific to the "rollbackAddedLoyaltyPoints" effect. This
gets triggered whenever previously a closed session with an
addLoyaltyPoints effect is cancelled.
required:
- programId
- subLedgerId
- value
- recipientIntegrationId
- transactionUUID
properties:
programId:
type: integer
description: The ID of the loyalty program where the points were originally added.
subLedgerId:
type: string
description: >-
The ID of the subledger within the loyalty program where these points
were originally added.
value:
type: number
description: The amount of points that were rolled back.
recipientIntegrationId:
type: string
maxLength: 1000
description: The user for whom these points were originally added.
example: URNGV8294NV
transactionUUID:
type: string
description: >-
The identifier of 'deduction' entry added to the ledger as the
`addLoyaltyPoints` effect is rolled back.
cartItemPosition:
type: number
description: >-
The index of the item in the cart items for which the loyalty points
were rolled back.
cartItemSubPosition:
type: number
description: >
For cart items with `quantity` > 1, the sub-position indicates to
which item the loyalty points were rolled back.
cardIdentifier:
description: The card on which these points were originally added.
$ref: '#/definitions/LoyaltyCardIdentifier'
RollbackDeductedLoyaltyPointsEffectProps:
type: object
description: >-
The properties specific to the "rollbackDeductedLoyaltyPoints" effect.
This effect is triggered whenever a previously closed session is cancelled
and a deductLoyaltyPoints effect was revoked.
required:
- programId
- subLedgerId
- value
- recipientIntegrationId
- transactionUUID
properties:
programId:
type: integer
description: The ID of the loyalty program where these points were reimbursed.
subLedgerId:
type: string
description: >-
The ID of the subledger within the loyalty program where these points
were reimbursed.
value:
type: number
description: The amount of reimbursed points that were added.
recipientIntegrationId:
type: string
maxLength: 1000
description: The user for whom these points were reimbursed.
example: URNGV8294NV
startDate:
type: string
format: date-time
description: Date after which the reimbursed points will be valid.
expiryDate:
type: string
format: date-time
description: Date after which the reimbursed points will expire.
transactionUUID:
type: string
description: >-
The identifier of 'addition' entries added to the ledger as the
`deductLoyaltyPoints` effect is rolled back.
cardIdentifier:
description: The card on which these points were added.
$ref: '#/definitions/LoyaltyCardIdentifier'
ShowBundleMetadataEffectProps:
type: object
description: >
This effect is **deprecated**.
The properties specific to the "ShowBundleMetadata" effect. This effect
contains information that allows you to associate the discounts from a
rule in a bundle campaign with specific cart items. This way you can
distinguish from "normal" discounts that were not the result of a product
bundle.
required:
- description
- bundleAttributes
- itemsIndices
properties:
description:
type: string
description: Description of the product bundle.
bundleAttributes:
type: array
items:
type: string
description: >-
The cart item attributes that determined which items are being bundled
together.
itemsIndices:
type: array
items:
type: number
description: The indices in the cart items array of the bundled items.
AwardGiveawayEffectProps:
type: object
description: >-
The properties specific to the "awardGiveaway" effect. This effect
contains information on the giveaway item, and which profile it was
awarded to.
required:
- poolId
- poolName
- recipientIntegrationId
- giveawayId
- code
properties:
poolId:
type: integer
description: The ID of the giveaways pool the code was taken from.
example: 2
poolName:
type: string
description: The name of the giveaways pool the code was taken from.
example: My pool
recipientIntegrationId:
type: string
maxLength: 1000
description: The integration ID of the profile that was awarded the giveaway.
example: URNGV8294NV
giveawayId:
type: integer
description: The internal ID for the giveaway that was awarded.
example: 5
code:
type: string
description: The giveaway code that was awarded.
example: 57638t-67439hty
WillAwardGiveawayEffectProps:
type: object
description: >-
The properties specific to the "awardGiveaway" effect when the session is
not closed yet. This effect replaces "awardGiveaway" only when updating a
session with any state other than "closed". This is to ensure no giveaway
codes are leaked when they are still not guaranteed to be awarded.
required:
- poolId
- poolName
- recipientIntegrationId
properties:
poolId:
type: integer
description: The ID of the giveaways pool the code will be taken from.
example: 2
poolName:
type: string
description: The name of the giveaways pool the code will be taken from.
example: My pool
recipientIntegrationId:
type: string
maxLength: 1000
description: The integration ID of the profile that will be awarded the giveaway.
example: URNGV8294NV
AddToAudienceEffectProps:
type: object
description: >-
The properties specific to the "addToAudience" effect. This gets triggered
whenever a validated rule contains an "addToAudience" effect.
properties:
audienceId:
type: integer
description: The internal ID of the audience.
example: 10
audienceName:
type: string
description: The name of the audience.
example: My audience
profileIntegrationId:
type: string
description: >-
The ID of the customer profile in the third-party integration
platform.
example: URNGV8294NV
profileId:
type: integer
description: The internal ID of the customer profile.
example: 150
RemoveFromAudienceEffectProps:
type: object
description: >-
The properties specific to the "removeFromAudience" effect. This gets
triggered whenever a validated rule contains a "removeFromAudience"
effect.
properties:
audienceId:
type: integer
description: The internal ID of the audience.
example: 10
audienceName:
type: string
description: The name of the audience.
example: My audience
profileIntegrationId:
type: string
description: >-
The ID of the customer profile in the third-party integration
platform.
example: URNGV8294NV
profileId:
type: integer
description: The internal ID of the customer profile.
example: 150
ErrorEffectProps:
type: object
description: >-
Whenever an error occurred during evaluation, we return an error effect.
This should never happen for rules created in the rule builder.
required:
- message
properties:
message:
type: string
description: The error message.
CustomEffectProps:
type: object
description: Effect containing custom payload.
required:
- effectId
- name
- payload
properties:
effectId:
type: integer
description: The ID of the custom effect that was triggered.
example: 1
name:
type: string
description: The type of the custom effect.
example: my_custom_effect
cartItemPosition:
type: number
description: >-
The index of the item in the cart item list to which the custom effect
is applied.
example: 1
cartItemSubPosition:
type: number
description: >
For cart items with quantity > 1, the sub position indicates to which
item unit the custom effect is applied.
example: 2
bundleIndex:
type: integer
description: >-
The position of the bundle in a list of item bundles created from the
same bundle definition.
example: 1
bundleName:
type: string
description: The name of the bundle definition.
example: my_bundle
payload:
description: The JSON payload of the custom effect.
type: object
additionalProperties: true
x-arbitraryJSON: true
IntegrationRequest:
type: object
description: >-
The body of a V2 integration API request (customer session update). Next
to the customer session details, this contains an optional listing of
extra properties that should be returned in the response.
required:
- customerSession
properties:
customerSession:
$ref: '#/definitions/NewCustomerSessionV2'
description: The customer session update details.
responseContent:
type: array
description: >
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.
example:
- customerSession
- customerProfile
items:
type: string
enum:
- customerSession
- customerProfile
- coupons
- triggeredCampaigns
- referral
- loyalty
- event
- awardedGiveaways
- ruleFailureReasons
- previousReturns
ReturnIntegrationRequest:
type: object
description: >-
The body of a return integration API request. Next to the cart items
details, this contains an optional listing of extra properties that should
be returned in the response.
required:
- return
properties:
return:
$ref: '#/definitions/NewReturn'
description: The returned cart items details.
responseContent:
type: array
description: >
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.
example:
- customerSession
- customerProfile
items:
type: string
enum:
- customerSession
- customerProfile
- coupons
- triggeredCampaigns
- referral
- loyalty
- event
- previousReturns
CustomerProfileIntegrationRequestV2:
type: object
description: ''
properties:
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
example:
Language: english
ShippingCountry: DE
evaluableCampaignIds:
type: array
items:
type: integer
maxLength: 999
description: >
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.
title: Campaigns to evaluate
example:
- 10
- 12
audiencesChanges:
type: object
description: Audiences memberships changes for this profile.
$ref: '#/definitions/ProfileAudiencesChanges'
responseContent:
type: array
description: >
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.
example:
- triggeredCampaigns
- customerProfile
items:
type: string
enum:
- customerProfile
- triggeredCampaigns
- loyalty
- event
- awardedGiveaways
- ruleFailureReasons
additionalProperties: false
ProfileAudiencesChanges:
type: object
required:
- adds
- deletes
properties:
adds:
title: Audiences to join
type: array
items:
type: integer
description: The IDs of the audiences for the customer to join.
example:
- 2
- 4
deletes:
title: Audiences to leave
type: array
items:
type: integer
description: The IDs of the audiences for the customer to leave.
example:
- 7
AudienceMembership:
type: object
required:
- id
- name
properties:
id:
type: integer
title: Audience ID
description: The ID of the audience belonging to this entity.
example: 2
name:
type: string
title: Audience Name
description: The Name of the audience belonging to this entity.
example: Travel audience
MultipleCustomerProfileIntegrationRequest:
type: object
properties:
customerProfiles:
type: array
items:
$ref: '#/definitions/MultipleCustomerProfileIntegrationRequestItem'
MultipleCustomerProfileIntegrationRequestItem:
type: object
description: ''
required:
- integrationId
properties:
attributes:
type: object
description: Arbitrary properties associated with this item.
additionalProperties: true
example:
Language: english
ShippingCountry: DE
integrationId:
description: >
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](https://docs.talon.one/integration-api#operation/updateCustomerSessionV2).
type: string
example: R195412
maxLength: 1000
additionalProperties: false
MultipleCustomerProfileIntegrationResponseV2:
type: object
properties:
integrationStates:
type: array
items:
$ref: '#/definitions/CustomerProfileUpdateV2Response'
CustomerProfileAudienceRequest:
type: object
properties:
data:
type: array
maximum: 1000
items:
$ref: '#/definitions/CustomerProfileAudienceRequestItem'
CustomerProfileAudienceRequestItem:
type: object
required:
- action
- profileIntegrationId
- audienceId
properties:
action:
type: string
enum:
- add
- delete
description: |
Defines the action to perform:
- `add`: Adds the customer profile to the audience.
- `delete`: Removes the customer profile from the audience.
example: add
profileIntegrationId:
type: string
description: The ID of this customer profile in the third-party integration.
example: R195412
maxLength: 1000
audienceId:
type: integer
description: >-
The ID of the audience. You get it via the `id` property when
[creating an audience](#operation/createAudienceV2).
example: 748
AccountCampaignStats:
type: object
additionalProperties:
$ref: '#/definitions/ApplicationCampaignStats'
ApplicationCampaignStats:
type: object
description: Provides statistics regarding an application's campaigns.
required:
- draft
- disabled
- scheduled
- running
- expired
- archived
properties:
draft:
type: integer
description: Number of draft campaigns.
disabled:
type: integer
description: Number of disabled campaigns.
scheduled:
type: integer
description: Number of scheduled campaigns.
running:
type: integer
description: Number of running campaigns.
expired:
type: integer
description: Number of expired campaigns.
archived:
type: integer
description: Number of archived campaigns.
RuleFailureReason:
type: object
description: Details about why a rule failed.
required:
- campaignID
- campaignName
- rulesetID
- ruleIndex
- ruleName
properties:
campaignID:
type: integer
description: The ID of the campaign that contains the rule that failed.
campaignName:
type: string
description: The name of the campaign that contains the rule that failed.
rulesetID:
type: integer
description: The ID of the ruleset that contains the rule that failed.
couponID:
type: integer
description: >-
The ID of the coupon that was being evaluated at the time of the rule
failure.
example: 4928
couponValue:
type: string
description: >-
The code of the coupon that was being evaluated at the time of the
rule failure.
referralID:
type: integer
description: >-
The ID of the referral that was being evaluated at the time of the
rule failure.
referralValue:
type: string
description: >-
The code of the referral that was being evaluated at the time of the
rule failure.
ruleIndex:
type: integer
description: The index of the rule that failed within the ruleset.
ruleName:
type: string
description: The name of the rule that failed within the ruleset.
conditionIndex:
type: integer
description: The index of the condition that failed.
effectIndex:
type: integer
description: The index of the effect that failed.
details:
type: string
description: More details about the failure.
Giveaway:
type: object
description: ''
required:
- id
- created
- code
- poolId
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
code:
type: string
description: The code value of this giveaway.
example: GIVEAWAY1
poolId:
type: integer
description: The ID of the pool to return giveaway codes from.
example: 1
startDate:
format: date-time
description: Timestamp at which point the giveaway becomes valid.
type: string
example: '2022-01-02T15:04:05Z07:00'
endDate:
format: date-time
description: Timestamp at which point the giveaway becomes invalid.
type: string
example: '2023-01-02T15:04:05Z07:00'
attributes:
type: object
description: Arbitrary properties associated with this giveaway.
additionalProperties: true
used:
type: boolean
description: Indicates whether this giveaway code was given before.
example: true
importId:
type: integer
description: The ID of the Import which created this giveaway.
example: 4
profileIntegrationId:
type: string
description: >-
The third-party integration ID of the customer profile that was
awarded the giveaway, if the giveaway was awarded.
example: R195412
profileId:
type: integer
description: >-
The internal ID of the customer profile that was awarded the giveaway,
if the giveaway was awarded and an internal ID exists.
example: 1
additionalProperties: false
NewGiveawaysPool:
type: object
required:
- name
- sandbox
properties:
name:
type: string
description: The name of this giveaways pool.
example: My giveaway pool
description:
type: string
description: The description of this giveaways pool.
example: Generic pool
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications that this giveaways pool is
enabled for.
items:
type: integer
example:
- 2
- 4
sandbox:
type: boolean
description: >-
Indicates if this program is a live or sandbox program. Programs of a
given type can only be connected to Applications of the same type.
title: Sandbox
example: true
GiveawaysPool:
type: object
description: Giveaways pools is an entity for managing multiple similar giveaways.
required:
- id
- created
- accountId
- name
- sandbox
- createdBy
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
name:
type: string
description: The name of this giveaways pool.
example: My giveaway pool
description:
type: string
description: The description of this giveaways pool.
example: Generic pool
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications that this giveaways pool is
enabled for.
items:
type: integer
example:
- 2
- 4
sandbox:
type: boolean
description: >-
Indicates if this program is a live or sandbox program. Programs of a
given type can only be connected to Applications of the same type.
title: Sandbox
example: true
modified:
type: string
format: date-time
description: Timestamp of the most recent update to the giveaways pool.
createdBy:
type: integer
description: ID of the user who created this giveaways pool.
modifiedBy:
type: integer
description: ID of the user who last updated this giveaways pool if available.
additionalProperties: false
NewCustomEffect:
type: object
description: ''
required:
- applicationIds
- name
- title
- enabled
- payload
properties:
applicationIds:
type: array
minItems: 1
description: The IDs of the Applications that are related to this entity.
items:
type: integer
isPerItem:
type: boolean
x-fieldType: bool
description: Indicates if this effect is per item or not.
name:
type: string
pattern: '^[A-Za-z](\w|\s)*$'
description: The name of this effect.
title:
type: string
pattern: '^[^[:cntrl:]\s][^[:cntrl:]]*$'
description: The title of this effect.
payload:
type: string
description: The JSON payload of this effect.
description:
type: string
description: The description of this effect.
enabled:
type: boolean
description: Determines if this effect is active.
params:
type: array
description: Array of template argument definitions.
items:
$ref: '#/definitions/TemplateArgDef'
additionalProperties: false
NewPicklist:
type: object
required:
- type
- values
properties:
type:
type: string
description: >-
The type of allowed values in the picklist. If type time is chosen, it
must be an RFC3339 timestamp string.
enum:
- string
- boolean
- number
- time
example: '2012-11-01T22:08:41+00:00'
values:
type: array
maxItems: 20
example:
- Jeans
- Shirt
- Coat
description: The list of allowed values provided by this picklist.
items:
type: string
Picklist:
type: object
description: ''
required:
- id
- created
- type
- values
- createdBy
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
type:
type: string
description: >-
The type of allowed values in the picklist. If type time is chosen, it
must be an RFC3339 timestamp string.
enum:
- string
- boolean
- number
- time
example: '2012-11-01T22:08:41+00:00'
values:
type: array
maxItems: 20
example:
- Jeans
- Shirt
- Coat
description: The list of allowed values provided by this picklist.
items:
type: string
modifiedBy:
type: integer
description: ID of the user who last updated this effect if available.
example: 124
createdBy:
type: integer
description: ID of the user who created this effect.
example: 134
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
imported:
type: boolean
description: Imported flag shows that a picklist is imported by a CSV file or not
example: true
additionalProperties: false
UpdatePicklist:
type: object
description: ''
required:
- type
- values
properties:
type:
type: string
description: >-
The type of allowed values in the picklist. If type time is chosen, it
must be an RFC3339 timestamp string.
enum:
- string
- boolean
- number
- time
example: '2012-11-01T22:08:41+00:00'
values:
type: array
maxItems: 20
example:
- Jeans
- Shirt
- Coat
description: The list of allowed values provided by this picklist.
items:
type: string
additionalProperties: false
UpdateCustomEffect:
type: object
description: ''
required:
- applicationIds
- name
- title
- enabled
- payload
properties:
applicationIds:
type: array
minItems: 1
description: The IDs of the Applications that are related to this entity.
items:
type: integer
isPerItem:
type: boolean
x-fieldType: bool
description: Indicates if this effect is per item or not.
name:
type: string
pattern: '^[A-Za-z](\w|\s)*$'
description: The name of this effect.
title:
type: string
pattern: '^[^[:cntrl:]\s][^[:cntrl:]]*$'
description: The title of this effect.
payload:
type: string
description: The JSON payload of this effect.
description:
type: string
description: The description of this effect.
enabled:
type: boolean
description: Determines if this effect is active.
params:
type: array
description: Array of template argument definitions.
items:
$ref: '#/definitions/TemplateArgDef'
additionalProperties: false
CustomEffect:
type: object
description: ''
required:
- id
- created
- accountId
- modified
- applicationIds
- name
- title
- enabled
- payload
- createdBy
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
applicationIds:
type: array
minItems: 1
description: The IDs of the Applications that are related to this entity.
items:
type: integer
isPerItem:
type: boolean
x-fieldType: bool
description: Indicates if this effect is per item or not.
name:
type: string
pattern: '^[A-Za-z](\w|\s)*$'
description: The name of this effect.
title:
type: string
pattern: '^[^[:cntrl:]\s][^[:cntrl:]]*$'
description: The title of this effect.
payload:
type: string
description: The JSON payload of this effect.
description:
type: string
description: The description of this effect.
enabled:
type: boolean
description: Determines if this effect is active.
params:
type: array
description: Array of template argument definitions.
items:
$ref: '#/definitions/TemplateArgDef'
modifiedBy:
type: integer
description: ID of the user who last updated this effect if available.
example: 334
createdBy:
type: integer
description: ID of the user who created this effect.
example: 216
additionalProperties: false
UpdateCampaignCollection:
type: object
properties:
description:
type: string
description: A short description of the purpose of this collection.
example: My collection of SKUs
NewCampaignCollection:
type: object
description: ''
required:
- name
properties:
description:
type: string
description: A short description of the purpose of this collection.
example: My collection of SKUs
name:
type: string
minLength: 1
pattern: '^[^[:cntrl:]\s][^[:cntrl:]]*$'
description: The name of this collection.
example: My collection
additionalProperties: false
CampaignCollectionWithoutPayload:
type: object
description: ''
required:
- id
- created
- accountId
- modified
- name
- createdBy
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
description:
type: string
description: A short description of the purpose of this collection.
example: My collection of SKUs
name:
type: string
minLength: 1
pattern: '^[^[:cntrl:]\s][^[:cntrl:]]*$'
description: The name of this collection.
example: My collection
modifiedBy:
type: integer
description: ID of the user who last updated this effect if available.
example: 48
createdBy:
type: integer
description: ID of the user who created this effect.
example: 134
applicationId:
type: integer
description: The ID of the Application that owns this entity.
example: 1
campaignId:
type: integer
description: The ID of the campaign that owns this entity.
example: 7
additionalProperties: false
CampaignCollection:
type: object
description: ''
required:
- id
- created
- accountId
- modified
- name
- createdBy
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
description:
type: string
description: A short description of the purpose of this collection.
example: My collection of SKUs
name:
type: string
minLength: 1
pattern: '^[^[:cntrl:]\s][^[:cntrl:]]*$'
description: The name of this collection.
example: My collection
modifiedBy:
type: integer
description: ID of the user who last updated this effect if available.
example: 48
createdBy:
type: integer
description: ID of the user who created this effect.
example: 134
applicationId:
type: integer
description: The ID of the Application that owns this entity.
example: 1
campaignId:
type: integer
description: The ID of the campaign that owns this entity.
example: 7
payload:
type: array
description: The content of the collection.
maxItems: 50
example:
- KTL-WH-ET-1
- KTL-BL-ET-1
items:
type: string
additionalProperties: false
UpdateCollection:
type: object
properties:
description:
type: string
description: A short description of the purpose of this collection.
example: My collection of SKUs
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the Applications where this collection is
enabled.
example:
- 1
- 2
- 3
items:
type: integer
NewCollection:
type: object
description: ''
required:
- name
properties:
description:
type: string
description: A short description of the purpose of this collection.
example: My collection of SKUs
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the Applications where this collection is
enabled.
example:
- 1
- 2
- 3
items:
type: integer
name:
type: string
minLength: 1
pattern: '^[^[:cntrl:]\s][^[:cntrl:]]*$'
description: The name of this collection.
example: My collection
additionalProperties: false
CollectionWithoutPayload:
type: object
description: ''
required:
- id
- created
- accountId
- modified
- name
- createdBy
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
description:
type: string
description: A short description of the purpose of this collection.
example: My collection of SKUs
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the Applications where this collection is
enabled.
example:
- 1
- 2
- 3
items:
type: integer
name:
type: string
minLength: 1
pattern: '^[^[:cntrl:]\s][^[:cntrl:]]*$'
description: The name of this collection.
example: My collection
modifiedBy:
type: integer
description: ID of the user who last updated this effect if available.
example: 48
createdBy:
type: integer
description: ID of the user who created this effect.
example: 134
applicationId:
type: integer
description: The ID of the Application that owns this entity.
example: 1
campaignId:
type: integer
description: The ID of the campaign that owns this entity.
example: 7
additionalProperties: false
Collection:
type: object
description: ''
required:
- id
- created
- accountId
- modified
- name
- createdBy
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
description:
type: string
description: A short description of the purpose of this collection.
example: My collection of SKUs
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the Applications where this collection is
enabled.
example:
- 1
- 2
- 3
items:
type: integer
name:
type: string
minLength: 1
pattern: '^[^[:cntrl:]\s][^[:cntrl:]]*$'
description: The name of this collection.
example: My collection
modifiedBy:
type: integer
description: ID of the user who last updated this effect if available.
example: 48
createdBy:
type: integer
description: ID of the user who created this effect.
example: 134
applicationId:
type: integer
description: The ID of the Application that owns this entity.
example: 1
campaignId:
type: integer
description: The ID of the campaign that owns this entity.
example: 7
payload:
type: array
description: The content of the collection.
maxItems: 50
example:
- KTL-WH-ET-1
- KTL-BL-ET-1
items:
type: string
additionalProperties: false
CollectionItem:
type: object
description: ''
required:
- item
properties:
item:
type: string
additionalProperties: false
NewCouponCreationJob:
type: object
description: ''
required:
- numberOfCoupons
- usageLimit
- attributes
properties:
usageLimit:
type: integer
minimum: 0
maximum: 999999
example: 100
description: >
The number of times the coupon code can be redeemed. `0` means
unlimited redemptions but any campaign usage limits will still apply.
discountLimit:
type: number
minimum: 0
maximum: 999999
example: 30
description: >
The total discount value that the code can give. Typically used to
represent a gift card value.
reservationLimit:
type: integer
minimum: 0
maximum: 999999
example: 45
description: |
The number of reservations that can be made with this coupon code.
startDate:
type: string
format: date-time
example: '2020-01-24T14:15:22Z'
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
example: '2023-08-24T14:15:22Z'
minimum: 0
description: >-
Expiration date of the coupon. Coupon never expires if this is
omitted, zero, or negative.
numberOfCoupons:
type: integer
description: The number of new coupon codes to generate for the campaign.
minimum: 1
maximum: 5000000
example: 200000
couponSettings:
$ref: '#/definitions/CodeGeneratorSettings'
attributes:
type: object
description: Arbitrary properties associated with coupons.
additionalProperties: true
additionalProperties: false
CouponCreationJob:
type: object
description: ''
required:
- id
- created
- campaignId
- applicationId
- accountId
- numberOfCoupons
- usageLimit
- attributes
- createdBy
- status
- batchId
- requestedAmount
- createdAmount
- failCount
- errors
- communicated
- chunkExecutionCount
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
campaignId:
type: integer
title: Campaign ID
description: The ID of the campaign that owns this entity.
example: 211
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
usageLimit:
type: integer
minimum: 0
maximum: 999999
example: 100
description: >
The number of times the coupon code can be redeemed. `0` means
unlimited redemptions but any campaign usage limits will still apply.
discountLimit:
type: number
minimum: 0
maximum: 999999
example: 30
description: >
The total discount value that the code can give. Typically used to
represent a gift card value.
reservationLimit:
type: integer
minimum: 0
maximum: 999999
example: 45
description: |
The number of reservations that can be made with this coupon code.
startDate:
type: string
format: date-time
example: '2020-01-24T14:15:22Z'
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
example: '2023-08-24T14:15:22Z'
minimum: 0
description: >-
Expiration date of the coupon. Coupon never expires if this is
omitted, zero, or negative.
numberOfCoupons:
type: integer
description: The number of new coupon codes to generate for the campaign.
minimum: 1
maximum: 5000000
example: 200000
couponSettings:
$ref: '#/definitions/CodeGeneratorSettings'
attributes:
type: object
description: Arbitrary properties associated with coupons.
additionalProperties: true
batchId:
title: Batch ID
type: string
description: The batch ID coupons created by this job will bear.
example: tqyrgahe
status:
title: Job Status
type: string
description: |
The current status of this request. Possible values:
- `pending`
- `completed`
- `failed`
- `coupon pattern full`
example: pending
createdAmount:
title: Created Amount
type: integer
description: The number of coupon codes that were already created for this request.
example: 1000000
failCount:
title: Fail Count
type: integer
description: The number of times this job failed.
example: 10
errors:
title: Errors
type: array
description: An array of individual problems encountered during the request.
example:
- Connection to database was reset
- failed to generate enough unique codes
- attribute 'PizzaLover' not found on entity 'Coupons'
items:
type: string
createdBy:
title: Created By
type: integer
description: ID of the user who created this effect.
example: 1
communicated:
type: boolean
description: >-
Whether or not the user that created this job was notified of its
final state.
example: false
chunkExecutionCount:
title: Iterations
type: integer
example: 0
description: >-
The number of times an attempt to create a chunk of coupons was made
during the processing of the job.
chunkSize:
title: Chunk size
type: integer
example: 20000
description: >-
The number of coupons that will be created in a single transactions.
Coupons will be created in chunks until arriving at the requested
amount.
additionalProperties: false
AsyncCouponCreationResponse:
type: object
required:
- batchId
properties:
batchId:
type: string
description: The batch ID that all coupons created by the request will have.
example: tqyrgahe
LimitCounter:
type: object
description: ''
required:
- campaignId
- applicationId
- accountId
- id
- action
- limit
- counter
properties:
campaignId:
type: integer
title: Campaign ID
description: The ID of the campaign that owns this entity.
example: 211
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
id:
type: integer
description: Unique ID for this entity.
example: 6
action:
type: string
example: setDiscount
description: The limitable action of the limit counter.
profileId:
type: integer
description: The profile ID for which this limit counter is used.
example: 335
profileIntegrationId:
type: string
maxLength: 1000
description: The profile integration ID for which this limit counter is used.
example: URNGV8294NV
couponId:
type: integer
description: The internal coupon ID for which this limit counter is used.
example: 34
couponValue:
type: string
description: The coupon value for which this limit counter is used.
example: XMAS-20-2021
referralId:
type: integer
description: The referral ID for which this limit counter is used.
example: 4
referralValue:
type: string
description: The referral value for which this limit counter is used.
example: ''
identifier:
type: string
description: The arbitrary identifier for which this limit counter is used.
example: 91.11.156.141
period:
type: string
example: Y2021M8
description: The time period for which this limit counter is used.
limit:
type: number
example: 10
description: The highest possible value for this limit counter.
counter:
type: number
example: 5
description: The current value for this limit counter.
additionalProperties: false
BulkCampaignNotification:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/CampaignNotification'
CampaignNotification:
type: object
required:
- event
properties:
event:
description: >
The type of the event. Can be one of the following:
['campaign_state_changed', 'campaign_ruleset_changed',
'campaign_edited', 'campaign_created', 'campaign_deleted']
type: string
example: campaign_state_changed
BulkApplicationNotification:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/definitions/ApplicationNotification'
ApplicationNotification:
type: object
required:
- event
properties:
event:
description: >
Event type. It can be one of the following:
['campaign_evaluation_tree_changed']
type: string
CampaignStateChangedNotification:
type: object
required:
- campaign
- newState
- oldState
description: A notification regarding a campaign whose state changed.
properties:
campaign:
type: object
description: The campaign whose state changed.
$ref: '#/definitions/CampaignForNotification'
oldState:
type: string
description: >
The campaign's old state. Can be one of the following: ['running',
'disabled', 'scheduled', 'expired', 'draft', 'archived']
example: disabled
newState:
type: string
description: >
The campaign's new state. Can be one of the following: ['running',
'disabled', 'scheduled', 'expired', 'draft', 'archived']
example: running
ruleset:
type: object
description: The current ruleset.
$ref: '#/definitions/Ruleset'
CampaignRulesetChangedNotification:
type: object
required:
- campaign
description: A notification regarding a campaign whose ruleset was changed.
properties:
campaign:
type: object
description: The campaign whose state changed.
$ref: '#/definitions/CampaignStateNotification'
oldRuleset:
type: string
description: 'The old ruleset, if the ruleset was changed.'
$ref: '#/definitions/Ruleset'
ruleset:
type: string
description: The current ruleset.
$ref: '#/definitions/Ruleset'
CampaignEditedNotification:
type: object
required:
- campaign
- oldCampaign
description: A notification regarding a campaign which was edited.
properties:
campaign:
type: object
description: The campaign whose state changed.
$ref: '#/definitions/CampaignStateNotification'
oldCampaign:
type: object
description: The campaign before the change.
$ref: '#/definitions/CampaignStateNotification'
ruleset:
type: object
description: The current ruleset.
$ref: '#/definitions/Ruleset'
CampaignCreatedNotification:
type: object
description: A notification regarding a campaign that was created.
required:
- campaign
- evaluationPosition
properties:
campaign:
type: object
description: The campaign whose state changed.
$ref: '#/definitions/CampaignStateNotification'
ruleset:
type: object
description: The current ruleset.
$ref: '#/definitions/Ruleset'
evaluationPosition:
type: object
description: The campaign position within the evaluation tree.
$ref: '#/definitions/CampaignEvaluationPosition'
CampaignEvaluationPosition:
type: object
description: The campaign position within the evaluation tree.
required:
- groupId
- groupName
- position
properties:
groupId:
type: integer
example: 2
description: The ID of the campaign evaluation group the campaign belongs to.
groupName:
type: string
description: The name of the campaign evaluation group the campaign belongs to.
example: Summer campaigns
position:
type: integer
description: The position of the campaign node in its parent group.
example: 2
CampaignDeletedNotification:
type: object
description: A notification regarding a campaign that was deleted.
required:
- campaign
- deletedAt
properties:
campaign:
type: object
description: The campaign whose state changed.
$ref: '#/definitions/CampaignStateNotification'
deletedAt:
type: string
format: date-time
example: '2022-11-10T23:00:00Z'
description: Time when the campaign was deleted.
CampaignStateNotification:
type: object
description: Campaign data and its state changes.
required:
- id
- created
- applicationId
- userId
- name
- state
- tags
- limits
- features
- description
- type
- budgets
- frontendState
properties:
id:
type: integer
description: Unique ID for this entity.
example: 4
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
userId:
type: integer
description: The ID of the user associated with this entity.
example: 388
name:
type: string
title: Campaign Name
description: A user-facing name for this campaign.
minLength: 1
example: Summer promotions
description:
type: string
title: Campaign Description
description: A detailed description of the campaign.
example: Campaign for all summer 2021 promotions
startTime:
type: string
format: date-time
description: Timestamp when the campaign will become active.
example: '2021-07-20T22:00:00Z'
endTime:
type: string
format: date-time
description: Timestamp when the campaign will become inactive.
example: '2021-09-22T22:00:00Z'
attributes:
type: object
description: Arbitrary properties associated with this campaign.
additionalProperties: true
state:
type: string
enum:
- enabled
- disabled
- archived
default: enabled
example: enabled
description: |
A disabled or archived campaign is not evaluated for rules or coupons.
activeRulesetId:
type: integer
description: >
[ID of
Ruleset](https://docs.talon.one/management-api#operation/getRulesets)
this
campaign applies on customer session evaluation.
example: 6
tags:
type: array
description: A list of tags for the campaign.
example:
- summer
maxItems: 50
items:
type: string
minLength: 1
maxLength: 50
features:
type: array
description: The features enabled in this campaign.
example:
- coupons
- referrals
items:
type: string
enum:
- coupons
- referrals
- loyalty
- giveaways
- strikethrough
couponSettings:
$ref: '#/definitions/CodeGeneratorSettings'
referralSettings:
$ref: '#/definitions/CodeGeneratorSettings'
limits:
type: array
description: >
The set of [budget
limits](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets)
for this campaign.
items:
$ref: '#/definitions/LimitConfig'
campaignGroups:
type: array
description: >
The IDs of the [campaign
groups](https://docs.talon.one/docs/product/account/managing-campaign-groups)
this campaign belongs to.
example:
- 1
- 3
items:
type: integer
evaluationGroupId:
type: integer
title: Evaluation Group ID
example: 2
description: The ID of the campaign evaluation group the campaign belongs to.
type:
type: string
title: Type
enum:
- cartItem
- advanced
default: advanced
example: advanced
description: |
The campaign type. Possible type values:
- `cartItem`: Type of campaign that can apply effects only to cart items.
- `advanced`: Type of campaign that can apply effects to customer sessions and cart items.
linkedStoreIds:
type: array
description: >
A list of store IDs that you want to link to the campaign.
**Note:** Campaigns with linked store IDs will only be evaluated when
there is a
[customer session
update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
that references a linked store.
items:
type: integer
example:
- 1
- 2
- 3
budgets:
type: array
items:
$ref: '#/definitions/CampaignBudget'
description: >
A list of all the budgets that are defined by this campaign and their
usage.
**Note:** Budgets that are not defined do not appear in this list and
their usage is
not counted until they are defined.
couponRedemptionCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Number of coupons redeemed in the campaign.
example: 163
referralRedemptionCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Number of referral codes redeemed in the campaign.
example: 3
discountCount:
type: number
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total amount of discounts redeemed in the campaign.
example: 288
discountEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of times discounts were redeemed in this campaign.
example: 343
couponCreationCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of coupons created by rules in this campaign.
example: 16
customEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of custom effects triggered by rules in this campaign.
example: 0
referralCreationCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of referrals created by rules in this campaign.
example: 8
addFreeItemEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of times the [add free item
effect](https://docs.talon.one/docs/dev/integration-api/api-effects#addfreeitem)
can be triggered in this campaign.
example: 0
awardedGiveawaysCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of giveaways awarded by rules in this campaign.
example: 9
createdLoyaltyPointsCount:
type: number
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty points created by rules in this campaign.
example: 9
createdLoyaltyPointsEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty point creation effects triggered by rules in
this campaign.
example: 2
redeemedLoyaltyPointsCount:
type: number
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty points redeemed by rules in this campaign.
example: 8
redeemedLoyaltyPointsEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of loyalty point redemption effects triggered by rules in
this campaign.
example: 9
callApiEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of webhooks triggered by rules in this campaign.
example: 0
reservecouponEffectCount:
type: integer
description: >
This property is **deprecated**. The count should be available under
*budgets* property.
Total number of reserve coupon effects triggered by rules in this
campaign.
example: 9
lastActivity:
type: string
format: date-time
example: '2022-11-10T23:00:00Z'
description: Timestamp of the most recent event received by this campaign.
updated:
type: string
format: date-time
example: '2022-10-97T35:00:00Z'
description: >
Timestamp of the most recent update to the campaign's property.
Updates to external entities used in this campaign
are **not** registered by this property, such as collection or coupon
updates.
createdBy:
type: string
description: Name of the user who created this campaign if available.
example: John Doe
updatedBy:
type: string
description: Name of the user who last updated this campaign if available.
example: Jane Doe
templateId:
type: integer
description: The ID of the Campaign Template this Campaign was created from.
example: 3
frontendState:
type: string
description: A campaign state described exactly as in the Campaign Manager.
enum:
- expired
- scheduled
- running
- draft
- disabled
example: running
additionalProperties: false
CampaignEvaluationTreeChangedNotification:
type: object
description: Notification about an Application whose campaign evaluation tree changed.
required:
- applicationId
- evaluationTree
properties:
applicationId:
type: integer
description: The ID of the Application whose campaign evaluation tree changed.
example: 78
oldEvaluationTree:
type: object
description: The previous campaign evaluation tree.
$ref: '#/definitions/CampaignSet'
evaluationTree:
type: object
description: The new campaign evaluation tree.
$ref: '#/definitions/CampaignSet'
StrikethroughLabelingNotification:
type: object
description: The strikethrough labels notification for an application.
required:
- applicationId
- currentBatch
- totalBatches
- trigger
- changedItems
properties:
applicationId:
type: integer
description: The ID of the application that catalog items labels belongs to.
example: 322
currentBatch:
type: integer
description: >-
The batch number of the notification. Notifications might be sent in
different batches.
example: 1
totalBatches:
type: integer
description: The total number of batches for the notification.
example: 10
trigger:
type: object
$ref: '#/definitions/StrikethroughTrigger'
changedItems:
type: array
items:
$ref: '#/definitions/StrikethroughChangedItem'
StrikethroughTrigger:
type: object
description: Information about the event that triggered the strikethrough labeling.
required:
- id
- type
- triggeredAt
- totalAffectedItems
- payload
properties:
id:
type: integer
description: The ID of the event that triggered the strikethrough labeling.
example: 1
type:
type: string
description: The type of event that triggered the strikethrough labeling.
example: CATALOG_SYNC
triggeredAt:
type: string
description: >-
The creation time of the event that triggered the strikethrough
labeling.
format: date-time
example: '2020-06-10T09:05:27.993483Z'
totalAffectedItems:
type: integer
description: >-
The total number of items affected by the event that triggered the
strikethrough labeling.
format: date-time
example: 1500
payload:
type: object
description: The arbitrary properties associated with this trigger type.
additionalProperties: true
example:
catalogId: 2
catalogVersion: 100
StrikethroughChangedItem:
type: object
description: The information of affected items.
required:
- id
- catalogId
- sku
- version
- price
- evaluatedAt
properties:
id:
type: integer
description: The ID of the event that triggered the strikethrough labeling.
example: 1
catalogId:
type: integer
description: The ID of the catalog that the changed item belongs to.
example: 10
sku:
type: string
description: The unique SKU of the changed item.
example: SKU1241028
version:
type: integer
minimum: 1
description: The version of the changed item.
example: 6
price:
type: number
description: The price of the changed item.
example: 99.99
evaluatedAt:
type: string
description: The evaluation time of the changed item.
format: date-time
example: '2020-06-10T09:05:27.993483Z'
effects:
type: array
items:
$ref: '#/definitions/StrikethroughEffect'
StrikethroughEffect:
type: object
description: The effect produced for the catalog item.
required:
- campaignId
- rulesetId
- ruleIndex
- ruleName
- type
- props
properties:
campaignId:
type: integer
description: The ID of the campaign that effect belongs to.
example: 3
rulesetId:
type: integer
description: The ID of the ruleset containing the rule that triggered this effect.
example: 11
ruleIndex:
type: integer
description: >-
The position of the rule that triggered this effect within the
ruleset.
example: 2
ruleName:
type: string
description: The name of the rule that triggered this effect.
example: Add 2 points
type:
type: string
description: The type of this effect.
example: setDiscountPerItem
props:
description: Arbitrary properties associated with this effect type.
$ref: '#/definitions/StrikethroughEffectProps'
StrikethroughEffectProps:
type: object
StrikethroughSetDiscountPerItemEffectProps:
type: object
description: setDiscountPerItem effect in strikethrough pricing payload.
required:
- name
- value
properties:
name:
description: effect name.
type: string
example: 1EuroOff
value:
description: discount value.
example: 1
StrikethroughCustomEffectPerItemProps:
type: object
description: customEffectPerItem effect in strikethrough pricing payload.
required:
- effectId
- name
- payload
properties:
effectId:
description: ID of the effect.
type: integer
example: 1
name:
type: string
description: The type of the custom effect.
example: my_custom_effect
payload:
description: The JSON payload of the custom effect.
type: object
additionalProperties: true
x-arbitraryJSON: true
NewBaseNotification:
type: object
description: ''
required:
- policy
- webhook
properties:
policy:
$ref: '#/definitions/BaseNotificationPolicy'
enabled:
type: boolean
description: Indicates whether the notification is activated.
default: true
webhook:
$ref: '#/definitions/NewNotificationWebhook'
additionalProperties: false
BaseNotificationEntity:
type: object
required:
- policy
properties:
policy:
$ref: '#/definitions/BaseNotificationPolicy'
enabled:
type: boolean
description: Indicates whether the notification is activated.
default: true
BaseNotificationPolicy:
type: object
ExpiringPointsNotificationPolicy:
type: object
required:
- name
- triggers
properties:
name:
type: string
description: Notification name.
example: Notification to Google
minLength: 1
triggers:
type: array
maxItems: 3
minItems: 1
items:
$ref: '#/definitions/ExpiringPointsNotificationTrigger'
AddedDeductedPointsNotificationPolicy:
type: object
required:
- name
- scopes
properties:
name:
type: string
description: Notification name.
example: Christmas Sale
minLength: 1
scopes:
type: array
minItems: 1
maxItems: 4
items:
type: string
enum:
- all
- campaign_manager
- management_api
- rule_engine
CouponsNotificationPolicy:
type: object
required:
- name
- scopes
properties:
name:
type: string
description: Notification name.
example: Christmas Sale
minLength: 1
scopes:
type: array
minItems: 1
maxItems: 4
items:
type: string
enum:
- all
- campaign_manager
- management_api
- rule_engine
CatalogsStrikethroughNotificationPolicy:
type: object
required:
- name
properties:
name:
type: string
description: Notification name.
example: Christmas Sale
minLength: 1
PendingPointsNotificationPolicy:
type: object
required:
- name
properties:
name:
type: string
description: Notification name.
example: Christmas Sale
minLength: 1
TierUpgradeNotificationPolicy:
type: object
required:
- name
properties:
name:
type: string
description: Notification name.
example: Christmas Sale
minLength: 1
TierDowngradeNotificationPolicy:
type: object
required:
- name
properties:
name:
type: string
description: The name of the notification.
example: Christmas Sale
minLength: 1
CampaignNotificationPolicy:
type: object
required:
- name
properties:
name:
type: string
description: Notification name.
example: Christmas Sale
minLength: 1
TierWillDowngradeNotificationPolicy:
type: object
required:
- name
- triggers
properties:
name:
type: string
description: The name of the notification.
example: Notification to Google
minLength: 1
triggers:
type: array
maxItems: 3
minItems: 1
items:
$ref: '#/definitions/TierWillDowngradeNotificationTrigger'
ExpiringPointsNotificationTrigger:
type: object
required:
- amount
- period
properties:
amount:
type: integer
description: The amount of period.
minimum: 1
period:
type: string
description: >-
Notification period indicated by a letter; "w" means week, "d" means
day.
enum:
- w
- d
TierWillDowngradeNotificationTrigger:
type: object
required:
- amount
- period
properties:
amount:
type: integer
description: The amount of period.
period:
type: string
description: >-
Notification period indicated by a letter; "w" means week, "d" means
day.
enum:
- w
- d
BaseNotifications:
type: object
properties:
data:
type: array
description: List of notifications.
items:
$ref: '#/definitions/BaseNotification'
BaseNotification:
type: object
description: ''
required:
- policy
- webhook
- id
- type
properties:
policy:
$ref: '#/definitions/BaseNotificationPolicy'
enabled:
type: boolean
description: Indicates whether the notification is activated.
default: true
webhook:
$ref: '#/definitions/BaseNotificationWebhook'
id:
type: integer
description: Unique ID for this entity.
example: 6
minimum: 1
type:
type: string
enum:
- campaign
- loyalty_added_deducted_points
- coupon
- expiring_points
- pending_to_active_points
- strikethrough_pricing
- tier_downgrade
- tier_upgrade
- tier_will_downgrade
description: The notification type.
example: loyalty_added_deducted_points
additionalProperties: false
BaseNotificationWebhook:
type: object
description: ''
required:
- id
- created
- modified
- url
- headers
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
url:
type: string
description: API URL for the given webhook-based notification.
example: www.my-company.com/my-endpoint-name
headers:
type: array
description: List of API HTTP headers for the given webhook-based notification.
example: 'content-type: application/json'
items:
type: string
pattern: '^[^:,]+:[^,]*$'
enabled:
type: boolean
description: Indicates whether the notification is activated.
default: true
example: true
additionalProperties: false
NewNotificationWebhook:
type: object
required:
- url
- headers
properties:
url:
type: string
description: API URL for the given webhook-based notification.
example: www.my-company.com/my-endpoint-name
headers:
type: array
description: List of API HTTP headers for the given webhook-based notification.
example: 'content-type: application/json'
items:
type: string
pattern: '^[^:,]+:[^,]*$'
enabled:
type: boolean
description: Indicates whether the notification is activated.
default: true
example: true
NotificationActivation:
type: object
required:
- enabled
properties:
enabled:
type: boolean
description: Indicates whether the notification is activated.
OutgoingIntegrationTypes:
type: object
properties:
data:
type: array
description: List of outgoing integrations.
items:
$ref: '#/definitions/OutgoingIntegrationType'
OutgoingIntegrationType:
type: object
required:
- id
- name
properties:
id:
type: integer
description: Unique ID for this entity.
example: 6
name:
type: string
description: Name of the outgoing integration.
example: Braze
minLength: 1
maxLength: 64
description:
type: string
description: Description of the outgoing integration.
example: Braze is a customer data platform
minLength: 1
maxLength: 1000
category:
type: string
description: Category of the outgoing integration.
example: customer engagement platform
minLength: 1
maxLength: 64
documentationLink:
type: string
description: Http link to the outgoing integration's documentation.
example: 'https://docs.talon.one/docs/dev/technology-partners/braze'
minLength: 1
maxLength: 255
OutgoingIntegrationConfiguration:
type: object
required:
- id
- accountId
- typeId
- policy
properties:
id:
type: integer
description: Unique ID for this entity.
example: 6
accountId:
type: integer
description: The ID of the account to which this configuration belongs.
example: 3886
typeId:
type: integer
description: The outgoing integration type ID.
example: 12
policy:
$ref: '#/definitions/OutgoingIntegrationConfigurationPolicy'
OutgoingIntegrationConfigurationPolicy:
type: object
description: The outgoing integration policy specific to each integration type.
OutgoingIntegrationBrazePolicy:
type: object
required:
- baseUrl
- apiKey
properties:
baseUrl:
type: string
description: The base URL of your Braze deployment.
example: your-braze-url.com
apiKey:
type: string
description: The API key of your Braze deployment.
example: Your-REST-API-Key
OutgoingIntegrationCleverTapPolicy:
type: object
required:
- baseUrl
- accountId
- passcode
properties:
baseUrl:
type: string
description: >-
The base URL that is based on the region key of your CleverTap
account.
example: your-clevertap-url.com
accountId:
type: string
description: The CleverTap Project ID.
example: A9X-7A6-4A6B
passcode:
type: string
description: The CleverTap Project passcode.
example: ABB-BAF-AWZP
OutgoingIntegrationMoEngagePolicy:
type: object
required:
- baseUrl
- appId
- dataApiId
- dataApiKey
properties:
baseUrl:
type: string
description: >-
The base URL of your MoEngage deployment, containing the MoEngage data
center number (represented by `0X`).
example: 'https://api-01.moengage.com'
appId:
type: string
description: >-
MoEngage APP ID. See [MoEngage Developer
Guide](https://developers.moengage.com/hc/en-us/articles/4404674776724-Overview).
example: LDUBEU9PLTPYXV30SMTYAAAA
dataApiId:
type: string
description: >-
MoEngage DATA API ID. See [MoEngage Developer
Guide](https://developers.moengage.com/hc/en-us/articles/4404674776724-Overview).
example: LDUBEU9PLTPYXV30SMTYAAAA
dataApiKey:
type: string
description: >-
MoEngage DATA API Key. See [MoEngage Developer
Guide](https://developers.moengage.com/hc/en-us/articles/4404674776724-Overview).
example: R95crrAAdZ747QLXe8LwnGLX
OutgoingIntegrationIterablePolicy:
type: object
required:
- baseUrl
- apiKey
properties:
baseUrl:
type: string
description: The base URL that is based on the region key of your Iterable account.
example: 'https://api.iterable.com'
apiKey:
type: string
description: >-
The API key generated from your Iterable account. See [Iterable API
Key
Guide](https://support.iterable.com/hc/en-us/articles/360043464871-API-Keys-)
example: 1234df4ba16940ca59c9352936d080a8
OutgoingIntegrationTemplates:
type: object
properties:
data:
type: array
description: The list of templates for a given outgoing integration type.
items:
$ref: '#/definitions/OutgoingIntegrationTemplate'
OutgoingIntegrationTemplate:
type: object
required:
- id
- integrationType
- title
- description
- payload
- method
- relativeUrl
- headers
properties:
id:
type: integer
description: Unique ID for this entity.
example: 6
integrationType:
type: integer
description: Unique ID of outgoing integration type.
example: 2
title:
type: string
description: The title of the integration template.
example: Email coupon codes
minLength: 1
maxLength: 255
description:
type: string
description: The description of the specific outgoing integration template.
example: This template sends a coupon code to the specified audience by email.
minLength: 1
maxLength: 1000
payload:
type: string
description: >-
The API payload (supports templating using parameters) for this
integration template.
example: "{\n\t\"message\": \"${message}\"\n}"
method:
type: string
enum:
- POST
- PUT
- GET
- DELETE
- PATCH
description: API method for this webhook.
example: POST
relativeUrl:
type: string
description: The relative URL corresponding to each integration template.
example: /campaigns/trigger/send
headers:
type: array
description: The list of HTTP headers for this integration template.
items:
type: string
pattern: '^([^:,]*):([^]*|[^,]*)$'
example:
- '{"Content-Type": "application/json"}'
OutgoingIntegrationTemplateWithConfigurationDetails:
type: object
description: ''
required:
- id
- integrationType
- title
- description
- payload
- method
- relativeUrl
- headers
- policy
properties:
id:
type: integer
description: Unique ID for this entity.
example: 6
integrationType:
type: integer
description: Unique ID of outgoing integration type.
example: 2
title:
type: string
description: The title of the integration template.
example: Email coupon codes
minLength: 1
maxLength: 255
description:
type: string
description: The description of the specific outgoing integration template.
example: This template sends a coupon code to the specified audience by email.
minLength: 1
maxLength: 1000
payload:
type: string
description: >-
The API payload (supports templating using parameters) for this
integration template.
example: "{\n\t\"message\": \"${message}\"\n}"
method:
type: string
enum:
- POST
- PUT
- GET
- DELETE
- PATCH
description: API method for this webhook.
example: POST
relativeUrl:
type: string
description: The relative URL corresponding to each integration template.
example: /campaigns/trigger/send
headers:
type: array
description: The list of HTTP headers for this integration template.
items:
type: string
pattern: '^([^:,]*):([^]*|[^,]*)$'
example:
- '{"Content-Type": "application/json"}'
policy:
$ref: '#/definitions/OutgoingIntegrationConfigurationPolicy'
additionalProperties: false
NewOutgoingIntegrationWebhook:
type: object
required:
- title
- applicationIds
properties:
title:
type: string
description: Webhook title.
example: Send email to customer via Braze
applicationIds:
type: array
description: IDs of the Applications to which a webhook must be linked.
additionalProperties: true
items:
type: integer
example:
- 1
- 2
- 3
CouponLimitConfigs:
type: object
properties:
limits:
type: array
description: >
Limits configuration for a coupon. These limits will override the
limits
set from the campaign.
**Note:** Only usable when creating a single coupon which is not tied
to a specific recipient.
Only per-profile limits are allowed to be configured.
items:
$ref: '#/definitions/LimitConfig'
Return:
type: object
description: ''
required:
- id
- created
- applicationId
- accountId
- returnedCartItems
- eventId
- sessionId
- sessionIntegrationId
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
returnedCartItems:
type: array
description: List of cart items to be returned.
items:
$ref: '#/definitions/ReturnedCartItem'
eventId:
title: Event ID
type: integer
description: The event ID of that was generated for this return.
example: 123
sessionId:
title: Session ID
type: integer
description: The internal ID of the session this return was requested on.
example: 123
sessionIntegrationId:
title: Session Integration ID
type: string
maxLength: 1000
description: The integration ID of the session this return was requested on.
example: 0c0e0207-eb30-4e06-a56c-2b7c8a64953c
profileId:
title: Profile ID
type: integer
description: The internal ID of the profile this return was requested on.
example: 123
profileIntegrationId:
title: Profile Integration ID
type: string
maxLength: 1000
description: The integration ID of the profile this return was requested on.
example: 0c0e0207-eb30-4e06-a56c-2b7c8a64953c
createdBy:
title: Created By
type: integer
description: ID of the user who requested this return.
example: 123
additionalProperties: false
NewReturn:
type: object
required:
- returnedCartItems
properties:
returnedCartItems:
type: array
description: List of cart items to be returned.
items:
$ref: '#/definitions/ReturnedCartItem'
ReturnedCartItem:
type: object
required:
- position
properties:
position:
description: >-
The index of the cart item in the provided customer session's
`cartItems` property.
type: integer
example: 2
quantity:
description: |
Number of cart items to return.
type: integer
example: 1
EventV2:
type: object
description: ''
required:
- type
properties:
profileId:
type: string
description: >
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`.
example: URNGV8294NV
storeIntegrationId:
type: string
minLength: 1
maxLength: 1000
description: >-
The integration ID of the store. You choose this ID when you create a
store.
example: STORE-001
evaluableCampaignIds:
type: array
items:
type: integer
maxLength: 999
description: >
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.
title: Campaigns to evaluate
example:
- 10
- 12
type:
type: string
title: Event Type
description: >
A string representing the event name. Must not be a reserved event
name. You create this value when you [create an
attribute](https://docs.talon.one/docs/dev/concepts/entities/events#creating-a-custom-event)
of type `event` in the Campaign Manager.
minLength: 1
example: pageViewed
attributes:
type: object
description: >-
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](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes#creating-a-custom-attribute).
additionalProperties: true
example:
myAttribute: myValue
additionalProperties: false
IntegrationEventV2Request:
type: object
description: ''
required:
- type
properties:
profileId:
type: string
description: >
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`.
example: URNGV8294NV
storeIntegrationId:
type: string
minLength: 1
maxLength: 1000
description: >-
The integration ID of the store. You choose this ID when you create a
store.
example: STORE-001
evaluableCampaignIds:
type: array
items:
type: integer
maxLength: 999
description: >
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.
title: Campaigns to evaluate
example:
- 10
- 12
type:
type: string
title: Event Type
description: >
A string representing the event name. Must not be a reserved event
name. You create this value when you [create an
attribute](https://docs.talon.one/docs/dev/concepts/entities/events#creating-a-custom-event)
of type `event` in the Campaign Manager.
minLength: 1
example: pageViewed
attributes:
type: object
description: >-
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](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes#creating-a-custom-attribute).
additionalProperties: true
example:
myAttribute: myValue
responseContent:
type: array
description: >
Optional list of requested information to be present on the response
related to the tracking custom event.
example:
- triggeredCampaigns
- customerProfile
items:
type: string
enum:
- customerProfile
- triggeredCampaigns
- loyalty
- event
- awardedGiveaways
- ruleFailureReasons
additionalProperties: false
MultipleNewAttribute:
type: object
properties:
attributes:
type: array
items:
$ref: '#/definitions/NewAttribute'
MultipleAttribute:
type: object
properties:
attributes:
type: array
items:
$ref: '#/definitions/Attribute'
UpdateCatalog:
type: object
properties:
description:
type: string
description: A description of this cart item catalog.
example: seafood catalog
name:
type: string
description: Name of this cart item catalog.
example: seafood
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications that are subscribed to this
catalog.
example:
- 1
- 2
- 3
items:
type: integer
NewCatalog:
type: object
description: ''
required:
- name
- description
properties:
name:
type: string
description: The cart item catalog name.
example: seafood
description:
type: string
description: A description of this cart item catalog.
example: seafood catalog
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications that are subscribed to this
catalog.
example:
- 1
- 2
- 3
items:
type: integer
additionalProperties: false
Catalog:
type: object
description: ''
required:
- id
- created
- accountId
- modified
- name
- description
- version
- createdBy
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
modified:
type: string
format: date-time
description: The time this entity was last modified.
example: '2021-09-12T10:12:42Z'
name:
type: string
description: The cart item catalog name.
example: seafood
description:
type: string
description: A description of this cart item catalog.
example: seafood catalog
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications that are subscribed to this
catalog.
example:
- 1
- 2
- 3
items:
type: integer
version:
type: integer
description: The current version of this catalog.
example: 6
createdBy:
type: integer
description: The ID of user who created this catalog.
example: 6
additionalProperties: false
CatalogSyncRequest:
type: object
required:
- actions
properties:
actions:
type: array
maxItems: 1000
minItems: 1
items:
$ref: '#/definitions/CatalogAction'
version:
type: integer
minimum: 1
description: The version number of the catalog to apply the actions on.
example: 244
CatalogAction:
type: object
description: >-
Definition of all the properties that are needed for a single catalog sync
action.
required:
- type
- payload
properties:
type:
type: string
enum:
- ADD
- PATCH
- PATCH_MANY
- REMOVE
- REMOVE_MANY
description: The type of sync action.
example: ADD
payload:
$ref: '#/definitions/CatalogActionPayload'
description: The payload of sync action.
example:
sku: T123
attributes:
type: shoes
color: blue
replaceIfExists: true
CatalogActionPayload:
type: object
CatalogActionFilter:
type: object
description: The properties for a single filtering condition in a catalog sync action.
required:
- attr
- op
- value
properties:
attr:
description: The name of the attribute to filter on.
type: string
op:
description: The filtering operator.
type: string
enum:
- EQ
- LT
- LE
- GT
- GE
- IN
value:
description: The value to filter for.
AddItemCatalogAction:
type: object
description: The specific properties of the "ADD" catalog sync action.
required:
- sku
properties:
sku:
type: string
description: The unique SKU of the item to add.
example: SKU1241028
price:
type: number
description: Price of the item.
example: 99.99
attributes:
type: object
description: The attributes of the item to add.
additionalProperties: true
example:
origin: germany
color: blue
replaceIfExists:
type: boolean
default: false
description: >-
Indicates whether to replace the attributes of the item if the same
SKU exists.
example: false
PatchItemCatalogAction:
type: object
description: The specific properties of the "PATCH" catalog sync action.
required:
- sku
properties:
sku:
type: string
description: The unique SKU of the item to patch.
price:
type: number
description: Price of the item.
example: 99.99
attributes:
type: object
description: The attributes of the item to patch.
additionalProperties: true
createIfNotExists:
type: boolean
default: false
description: Indicates whether to create an item if the SKU does not exist.
PatchManyItemsCatalogAction:
type: object
description: The specific properties of the "PATCH_MANY" catalog sync action.
properties:
price:
type: number
description: Price of the item.
example: 99.99
filters:
type: array
items:
$ref: '#/definitions/CatalogActionFilter'
description: >
The list of filters used to select the items to patch, joined by
`AND`.
**Note:** Every item in the catalog will be modified if there are no
filters.
attributes:
type: object
description: The attributes of the items to patch.
additionalProperties: true
RemoveItemCatalogAction:
type: object
description: The specific properties of the "REMOVE" catalog sync action.
required:
- sku
properties:
sku:
type: string
description: The unique SKU of the item to remove.
RemoveManyItemsCatalogAction:
type: object
description: The specific properties of the "REMOVE_MANY" catalog sync action.
properties:
filters:
type: array
items:
$ref: '#/definitions/CatalogActionFilter'
description: >
The list of filters used to select the items to patch, joined by
`AND`.
**Note:** Every item in the catalog will be removed if there are no
filters.
CatalogItem:
type: object
description: ''
required:
- id
- created
- sku
- catalogid
- version
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
sku:
type: string
description: The stock keeping unit of the item.
example: SKU1241028
price:
type: number
description: Price of the item.
example: 99.99
x-fieldType: NullDecimal
catalogid:
type: integer
description: The ID of the catalog the item belongs to.
example: 6
version:
type: integer
minimum: 1
description: The version of the catalog item.
example: 5
attributes:
type: array
items:
$ref: '#/definitions/ItemAttribute'
additionalProperties: false
ItemAttribute:
type: object
description: ''
required:
- attributeid
- name
- value
properties:
attributeid:
type: integer
description: The ID of the attribute of the item.
example: 6
name:
type: string
description: The name of the attribute.
value:
description: The value of the attribute.
additionalProperties: false
CampaignActivationRequest:
type: object
required:
- userIds
properties:
userIds:
type: array
description: The list of IDs of the users who will receive the activation request.
items:
type: integer
example:
- 1
- 2
- 3
maxItems: 5
AccountDashboardStatisticRevenue:
type: object
required:
- total
- influenced
- datetime
properties:
total:
type: number
description: >-
All revenue that went through the client's shop (including purchases
that didn’t trigger an effect).
influenced:
type: number
description: >-
The revenue that was created by a purchase that triggered an effect
(excluding web hooks, notifications).
datetime:
type: string
format: date-time
description: Values aggregated for the specified date.
AccountDashboardStatisticDiscount:
type: object
required:
- total
- average
- datetime
properties:
total:
type: number
description: Total discount value redeemed by users.
average:
type: number
description: Average discount percentage.
datetime:
type: string
format: date-time
description: Values aggregated for the specified date.
AccountDashboardStatisticLoyaltyPoints:
type: object
required:
- total
- datetime
properties:
total:
type: number
description: Total loyalty points earned by users.
datetime:
type: string
format: date-time
description: Values aggregated for the specified date.
AccountDashboardStatisticReferrals:
type: object
required:
- total
- datetime
properties:
total:
type: number
description: Total number of referrals initiated by users.
datetime:
type: string
format: date-time
description: Values aggregated for the specified date.
AccountDashboardStatisticApiCalls:
type: object
required:
- total
- datetime
properties:
total:
type: number
description: Total number of API calls received.
datetime:
type: string
format: date-time
description: Values aggregated for the specified date.
AccountDashboardStatisticCampaigns:
type: object
required:
- live
- endingSoon
- lowOnBudget
properties:
live:
type: integer
description: >-
Number of campaigns that are active and live (across all
Applications).
endingSoon:
type: integer
description: Campaigns scheduled to expire sometime in the next 7 days.
lowOnBudget:
type: integer
description: Campaigns with less than 10% of budget left.
AccountDashboardStatistic:
type: object
required:
- campaigns
properties:
revenue:
type: array
description: Aggregated statistic for account revenue.
items:
$ref: '#/definitions/AccountDashboardStatisticRevenue'
discounts:
type: array
description: Aggregated statistic for account discount.
items:
$ref: '#/definitions/AccountDashboardStatisticDiscount'
loyaltyPoints:
type: array
description: Aggregated statistic for account loyalty points.
items:
$ref: '#/definitions/AccountDashboardStatisticLoyaltyPoints'
referrals:
type: array
description: Aggregated statistic for account referrals.
items:
$ref: '#/definitions/AccountDashboardStatisticReferrals'
apiCalls:
type: array
description: Aggregated statistic for the number of account API calls.
items:
$ref: '#/definitions/AccountDashboardStatisticApiCalls'
campaigns:
$ref: '#/definitions/AccountDashboardStatisticCampaigns'
UpdateStore:
type: object
required:
- name
- description
properties:
name:
type: string
description: The name of the store.
example: South US store
minLength: 1
maxLength: 200
description:
type: string
description: The description of the store.
example: This is the description of the store in south US.
attributes:
type: object
description: The attributes of the store.
additionalProperties: true
example:
country: USA
code: 1234
NewStore:
type: object
description: ''
required:
- name
- description
- integrationId
properties:
name:
type: string
description: The name of the store.
example: South US store
minLength: 1
maxLength: 200
description:
type: string
description: The description of the store.
example: This is the description of the store in south US.
attributes:
type: object
description: The attributes of the store.
additionalProperties: true
example:
country: USA
code: 1234
integrationId:
type: string
format: string
example: STORE-001
maxLength: 1000
minLength: 1
description: >-
The integration ID of the store. You choose this ID when you create a
store.
additionalProperties: false
Store:
type: object
description: ''
required:
- id
- created
- name
- description
- integrationId
- updated
- applicationId
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
description: The time this entity was created. The time this entity was created.
format: date-time
name:
type: string
description: The name of the store.
example: South US store
minLength: 1
maxLength: 200
description:
type: string
description: The description of the store.
example: This is the description of the store in south US.
attributes:
type: object
description: The attributes of the store.
additionalProperties: true
example:
country: USA
code: 1234
integrationId:
type: string
format: string
example: STORE-001
maxLength: 1000
minLength: 1
description: >-
The integration ID of the store. You choose this ID when you create a
store.
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
updated:
type: string
format: date-time
description: Timestamp of the most recent update on this entity.
example: '2021-09-23T10:12:42Z'
linkedCampaignIds:
type: array
description: A list of IDs of the campaigns that are linked with current store.
items:
type: integer
example:
- 4
- 6
- 8
additionalProperties: false
BulkOperationOnCampaigns:
type: object
required:
- campaignIds
- operation
properties:
operation:
type: string
enum:
- disable
- delete
description: |
The operation to perform on the specified campaign IDs.
campaignIds:
type: array
description: The list of campaign IDs on which the operation will be performed.
items:
type: integer
example:
- 1
- 2
- 3
maxItems: 50
CreateAchievement:
type: object
required:
- name
- title
- description
- target
- period
properties:
name:
type: string
pattern: '^[a-zA-Z]\w+$'
example: Order50Discount
maxLength: 1000
minLength: 1
description: >
The internal name of the achievement used in API requests.
**Note**: The name should start with a letter. This cannot be changed
after the achievement has been created.
title:
type: string
description: The display name for the achievement in the Campaign Manager.
example: 50% off on 50th purchase.
description:
type: string
format: string
description: A description of the achievement.
example: 50% off for every 50th purchase in a year.
target:
type: number
description: >-
The maximum number of times a specific action must be completed by a
customer profile over a defined period of time.
example: 50
period:
type: string
description: >
The relative duration after which the achievement is reset for a
particular customer profile.
**Note**: The `period` does not start when the achievement is
created.
The period is a **positive real number** followed by one letter
indicating the time unit.
Examples: `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`.
Available units:
- `s`: seconds
- `m`: minutes
- `h`: hours
- `D`: days
- `W`: weeks
- `M`: months
- `Y`: years
You can also round certain units down to the beginning of period and
up to the end of period.:
- `_D` for rounding down days only. Signifies the start of the day.
Example: `30D_D`
- `_U` for rounding up days, weeks, months and years. Signifies the
end of the day, week, month or year.
Example: `23W_U`
**Note**: You can either use the round down and round up option or set
an absolute period.
example: 1Y
periodEndOverride:
$ref: '#/definitions/TimePoint'
AchievementAdditionalProperties:
type: object
required:
- userId
- createdBy
properties:
userId:
type: integer
description: ID of the user that created this achievement.
example: 1234
createdBy:
type: string
description: |
Name of the user that created the achievement.
**Note**: This is not available if the user has been deleted.
example: John Doe
Achievement:
type: object
description: ''
required:
- id
- created
- name
- title
- description
- target
- period
- userId
- createdBy
properties:
id:
type: integer
description: Internal ID of this entity.
example: 6
created:
type: string
format: date-time
description: The time this entity was created.
example: '2020-06-10T09:05:27.993483Z'
name:
type: string
pattern: '^[a-zA-Z]\w+$'
example: Order50Discount
maxLength: 1000
minLength: 1
description: >
The internal name of the achievement used in API requests.
**Note**: The name should start with a letter. This cannot be changed
after the achievement has been created.
title:
type: string
description: The display name for the achievement in the Campaign Manager.
example: 50% off on 50th purchase.
description:
type: string
format: string
description: A description of the achievement.
example: 50% off for every 50th purchase in a year.
target:
type: number
description: >-
The maximum number of times a specific action must be completed by a
customer profile over a defined period of time.
example: 50
period:
type: string
description: >
The relative duration after which the achievement is reset for a
particular customer profile.
**Note**: The `period` does not start when the achievement is
created.
The period is a **positive real number** followed by one letter
indicating the time unit.
Examples: `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`.
Available units:
- `s`: seconds
- `m`: minutes
- `h`: hours
- `D`: days
- `W`: weeks
- `M`: months
- `Y`: years
You can also round certain units down to the beginning of period and
up to the end of period.:
- `_D` for rounding down days only. Signifies the start of the day.
Example: `30D_D`
- `_U` for rounding up days, weeks, months and years. Signifies the
end of the day, week, month or year.
Example: `23W_U`
**Note**: You can either use the round down and round up option or set
an absolute period.
example: 1Y
periodEndOverride:
$ref: '#/definitions/TimePoint'
userId:
type: integer
description: ID of the user that created this achievement.
example: 1234
createdBy:
type: string
description: |
Name of the user that created the achievement.
**Note**: This is not available if the user has been deleted.
example: John Doe
additionalProperties: false
UpdateAchievement:
type: object
properties:
title:
type: string
description: The display name for the achievement in the Campaign Manager.
example: 50% off on 50th purchase.
description:
type: string
format: string
description: A description of the achievement.
example: 50% off for every 50th purchase in a year.