swagger: '2.0'
info:
title: Integration API reference docs
version: 1.0.0
description: >
Use the Integration API to push data to and retrieve data from Talon.One in
real time.
For more background information about this API, see [Integration API
overview](/docs/dev/integration-api/overview)
For example, use this API to share shopping cart information as a session
with Talon.One and evaluate promotion
rules. You can also create custom events to track specific actions that do
not fit into the session data model.
Ensure you [authenticate](#section/Authentication) to make requests to the
API.
Are you looking for a different API? If you need the API to:
- Interact with the Campaign Manager for backoffice operations, see [the
Management API reference docs](https://docs.talon.one/management-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).
host: yourbaseurl.talon.one
schemes:
- https
produces:
- application/json
consumes:
- application/json
securityDefinitions:
api_key_v1:
type: apiKey
name: Authorization
in: header
description: >
To authenticate in order to use the Integration API, generate an API key
in the Campaign Manager
then prefix it with `ApiKey-v1`.
To generate an API key:
1. Log on to the Campaign Manager and open the Application of your choice,
or create one.
1. Click **Settings** > **Developer settings**.
1. Click **Create API Key** and give it a title and an expiration date,
then click **Create API Key**.
You can now use the API key in the HTTP header, prefixing it with
`ApiKey-v1`:
```
Authorization: ApiKey-v1 dbc644d33aa74d582bd9479c59e16f970fe13bf3
```
Or use it inside [an SDK](/docs/dev/sdks/overview), for example, with the
JAVA SDK:
```
iApi.getApiClient().setApiKeyPrefix("ApiKey-v1");
iApi.getApiClient().setApiKey("dbc644d33aa74d582bd9479c59e16f970fe13bf3");
```
tags:
- name: Audiences
description: >
Represents an arbitrary group of customer profiles. Audiences can be
synced from Customer Data Platforms such as mParticle or created from
scratch.
- 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
[documentation](https://docs.talon.one/docs/product/account/dev-tools/managing-cart-item-catalogs).
- 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.
- name: Customer profiles
description: >
Represents the customer's information. For instance, their contact
information.
- name: Customer sessions
description: >
Represents the data related to a customer session. Typically, a customer
session is the value and content of the customer's cart.
Sessions can be anonymous or linked to a customer profile and they have a
life cycle from `open` to `closed`.
In general, a session is closed when the customer completes the checkout
step.
Sessions are a key concept of Talon.One, we strongly recommend you read
the [documentation about customer
sessions](/docs/dev/concepts/entities#customer-session).
- name: Events
description: >
Represents a single occurrence of various customer actions. There are 2
versions:
- For V1 events, each customer **session** contains one or more events.
For example, updating a customer session records a `talon_session_updated`
event.
- For V2 events, each customer **profile** contains one or more events.
For example, updating a customer session records a `talon_session_updated`
event linked to the profile in question.
- name: Referrals
description: >
A referral is a code shared between a customer and a prospect.
A referral is defined by an advocate, a friend and a referral code. The
advocate is the person who
invited their friend via referral program. The friend is the person who
receives the invite from an advocate.
The referral code is a code which is generated similar to a coupon code
the code can be redeemed by
either one or multiple advocates.
paths:
'/v2/customer_sessions/{customerSessionId}':
get:
operationId: getCustomerSession
summary: Get customer session
description: |
Get customer session data.
security:
- api_key_v1: []
tags:
- Customer sessions
parameters:
- &ref_0
name: customerSessionId
in: path
type: string
required: true
description: >
The `integration ID` of the customer session. You set this ID when
you create a customer session.
You can see existing customer session integration IDs in the
Campaign Manager's **Sessions** menu, or via the
[List Application session
endpoint](https://docs.talon.one/management-api/#operation/getApplicationSessions).
responses:
'200':
description: OK
schema:
$ref: '#/definitions/IntegrationCustomerSessionResponse'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
put:
operationId: updateCustomerSessionV2
summary: Update customer session
description: >
Update or create a [customer
session](/docs/dev/concepts/entities#customer-session).
For example, use this endpoint to share the content of a customer's cart
with Talon.One and to check which
promotion rules apply.
**Note:** The currency for the session and the cart items in the session
is the same as the
Application that owns this session.
**Session management**
The Talon.One platform supports multiple simultaneous sessions for the
same profile. If you have multiple ways of accessing the same
Application you can either:
- Track multiple independent sessions or,
- Use the same session across all of them.
You should share sessions when application access points share other
state, such as the user's cart.
If two points of access to the application have independent states, for
example a user can have different
items in their cart across the two) they should use independent customer
session ID's.
See more information and tips about session management in the
[documentation](/docs/dev/concepts/entities#customer-session).
**Sessions and customer profiles**
- To link a session to a customer profile, set the `profileId` parameter
in the request body to a customer profile's `integrationId`.
- While you can create an anonymous session with `profileId=""`, we
recommend you use a guest ID instead.
**Note:** You do **not** have to create a customer profile first. If the
specified profile does not exist, an empty profile is created
automatically.
**Performance tips**
Updating a customer session returns a response with the requested
integration state.
You can use the `responseContent` property to save yourself extra API
calls. For example, you can get
the customer profile details directly without extra requests.
For more information, see the [integration
tutorial](https://docs.talon.one/docs/dev/tutorials/integrating-talon-one).
security:
- api_key_v1: []
tags:
- Customer sessions
parameters:
- &ref_1
name: dry
in: query
type: boolean
description: >-
Indicates whether to persist the changes. Changes are ignored when
`dry=true`.
required: false
- *ref_0
- name: body
in: body
required: true
schema:
$ref: '#/definitions/IntegrationRequest'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/IntegrationStateV2'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'409':
description: >-
Too many requests - Avoid parallel requests, see the
[docs](/docs/dev/tutorials/integrating-talon-one/#managing-parallel-requests)
schema:
properties:
message:
type: string
example: Too many requests are updating this session at the same time
errors:
type: array
items:
type: object
StatusCode:
type: integer
example: 409
'/v2/customer_sessions/{customerSessionId}/returns':
post:
operationId: returnCartItems
summary: Return cart items
description: >
Create a new return request for the specified cart items.
This endpoint automatically changes the session state from `closed` to
`partially_returned`.
Its behavior depends on whether [cart item
flattening](https://docs.talon.one/docs/product/campaigns/campaign-evaluation/#flattened-cart-items)
is enabled for the Application.
**Note:** This will roll back any effects associated with these cart
items. For more information, see
[our documentation on session
states](https://docs.talon.one/docs/dev/concepts/entities#customer-session-states)
and [this
tutorial](https://docs.talon.one/docs/dev/tutorials/partially-returning-a-session).
security:
- api_key_v1: []
tags:
- Customer sessions
parameters:
- *ref_1
- *ref_0
- name: body
in: body
required: true
schema:
$ref: '#/definitions/ReturnIntegrationRequest'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/IntegrationStateV2'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
/v2/customer_profiles:
put:
operationId: updateCustomerProfilesV2
summary: Update multiple customer profiles
description: >
Update (or create) up to 1000 [customer
profiles](/docs/dev/concepts/entities#customer-profile) in 1 request.
The `integrationId` must be any identifier that remains stable for
the customer. Do not use an ID that the customer can update
themselves. For example, you can use a database ID.
A customer profile [can be linked to one or more
sessions](/integration-api/#tag/Customer-sessions).
security:
- api_key_v1: []
tags:
- Customer profiles
parameters:
- &ref_3
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 essential data such as
the updated customer profiles and session-related information.
required: false
type: string
- name: body
in: body
required: true
schema:
$ref: '#/definitions/MultipleCustomerProfileIntegrationRequest'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/MultipleCustomerProfileIntegrationResponseV2'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v2/customer_profiles/{integrationId}':
put:
operationId: updateCustomerProfileV2
summary: Update customer profile
description: >
Update or create a [Customer
Profile](/docs/dev/concepts/entities#customer-profile).
**Performance tips**
Updating a customer profile returns a response with the requested
integration state.
You can use the `responseContent` property to save yourself extra API
calls. For example, you can get
the customer profile details directly without extra requests.
security:
- api_key_v1: []
tags:
- Customer profiles
parameters:
- in: path
type: string
required: true
name: integrationId
description: >
The integration identifier for this customer profile. Must be:
- Unique within the deployment.
- Stable for the customer. Do not use an ID that the customer can
update themselves. For example, you can use a database ID.
Once set, you cannot update this identifier.
- name: runRuleEngine
in: query
type: boolean
description: >
Indicates whether to run the Rule Engine.
If `true`, the response includes:
- The effects generated by the triggered campaigns are returned in
the `effects` property.
- The created coupons and referral objects.
If `false`:
- The rules are not executed and the `effects` property is always
empty.
- The response time improves.
- You cannot use `responseContent` in the body.
required: false
default: false
- name: dry
in: query
type: boolean
description: >
Indicates whether to persist the changes. Changes are ignored when
`dry=true`.
This property only works when `runRuleEngine=true`.
required: false
- name: body
in: body
required: true
schema:
$ref: '#/definitions/CustomerProfileIntegrationRequestV2'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/IntegrationStateV2'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'409':
description: >-
Too many requests - Avoid parallel requests, see the
[docs](/docs/dev/tutorials/integrating-talon-one/#managing-parallel-requests)
schema:
properties:
message:
type: string
example: Too many requests are updating this session at the same time
errors:
type: array
items:
type: object
StatusCode:
type: integer
example: 409
/v2/audiences:
post:
operationId: createAudienceV2
summary: Create audience
description: >
Create an audience. The audience can be created directly from scratch or
can come from third party platforms.
To create an audience from an existing audience from a [technology
partner](https://docs.talon.one/docs/dev/technology-partners/overview):
1. Set the `integration` property to `mparticle`, `segment` etc.,
depending on a third-party platform.
1. Set `integrationId` to the ID of this audience in a third-party
platform.
To create an audience from an existing audience in another platform:
1. Do not use the `integration` property.
1. Set `integrationId` to the ID of this audience in the 3rd-party
platform.
To create an audience from scratch:
1. Only set the `name` property.
Once you create your first audience, audience-specific rule conditions
are enabled in the Rule Builder.
security:
- api_key_v1: []
tags:
- Audiences
parameters:
- name: body
required: true
in: body
schema:
$ref: '#/definitions/NewAudience'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/Audience'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'409':
description: >-
Conflict. An Audience with this ID already exists for this
integration.
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v2/audiences/{audienceId}':
delete:
operationId: deleteAudienceV2
summary: Delete audience
description: >
Delete an audience created by a third-party integration.
**Warning:** This endpoint also removes any associations recorded
between a customer profile and this audience.
tags:
- Audiences
parameters:
- &ref_2
name: audienceId
in: path
required: true
type: integer
description: >-
The ID of the audience. You get it via the `id` property when
[creating an audience](#operation/createAudienceV2).
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'
put:
operationId: updateAudienceV2
summary: Update audience
description: |
Update an Audience created by a third-party integration.
security:
- api_key_v1: []
tags:
- Audiences
parameters:
- *ref_2
- name: body
in: body
required: true
schema:
$ref: '#/definitions/UpdateAudience'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Audience'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v2/audiences/{audienceId}/memberships':
delete:
operationId: deleteAudienceMembershipsV2
summary: Delete audience memberships
description: |
Remove all members from this audience.
tags:
- Audiences
parameters:
- *ref_2
responses:
'204':
description: No Content
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
/v2/customer_audiences:
post:
operationId: updateCustomerProfileAudiences
summary: Update multiple customer profiles' audiences
description: >
Update the specified customer profiles with the specified audiences. Use
this endpoint
when customers join or leave audiences.
The limit of customer profiles per request is 1000.
security:
- api_key_v1: []
tags:
- Audiences
parameters:
- name: body
in: body
required: true
schema:
$ref: '#/definitions/CustomerProfileAudienceRequest'
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'
'/v2/audience_customers/{audienceId}/attributes':
put:
operationId: updateAudienceCustomersAttributes
summary: Update profile attributes for all customers in audience
description: >
Update the specified profile attributes to the provided values for all
customers in the specified audience.
security:
- api_key_v1: []
tags:
- Audiences
parameters:
- *ref_2
- name: body
in: body
required: true
schema:
$ref: '#/definitions/AttributeQuery'
responses:
'204':
description: No Content
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
/v1/events:
post:
operationId: trackEvent
summary: Track event
description: >
**Important:** This endpoint is **DEPRECATED**. Use [Track Event
V2](https://docs.talon.one/integration-api/#tag/Events/operation/trackEventV2)
instead.
> Triggers a custom event in a customer session. You can then check this
event in your rules. **Important:** Talon.One offers a set of [built-in
events](/docs/dev/concepts/events), ensure you do not create a custom
event when you can use a built-in event.
> For example, use this endpoint to trigger an event when a user updates
their payment information.
> Before using this endpoint, create your event as a custom attribute of
type `event`. See the [Developer
docs](/docs/dev/concepts/events/#creating-a-custom-event).
> An event is always part of a session. If either the profile or the
session does not exist,
a new empty profile/session is created. If the specified session already
exists, it must belong to the same `profileId` or an error will be
returned.
security:
- api_key_v1: []
tags:
- Events
parameters:
- *ref_1
- name: body
required: true
in: body
schema:
$ref: '#/definitions/NewEvent'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/IntegrationState'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'409':
description: >-
Too many requests - Avoid parallel requests, see the
[docs](/docs/dev/tutorials/integrating-talon-one/#managing-parallel-requests)
schema:
properties:
message:
type: string
example: Too many requests are updating this session at the same time
errors:
type: array
items:
type: object
StatusCode:
type: integer
example: 409
/v2/events:
post:
operationId: trackEventV2
summary: Track event V2
description: >
Triggers a custom event. You can then check this event in your rules.
**Important:** Talon.One offers a set of [built-in
events](/docs/dev/concepts/events), ensure you do not create
a custom event when you can use a built-in event.
For example, use this endpoint to trigger an event when a user updates
their payment information.
Before using this endpoint, create your event as a custom attribute of
type `event`.
See the [Developer
docs](/docs/dev/concepts/events/#creating-a-custom-event).
**Important:** `profileId` is required. An event V2 is associated with a
customer profile.
security:
- api_key_v1: []
tags:
- Events
parameters:
- *ref_3
- *ref_1
- name: body
required: true
in: body
schema:
$ref: '#/definitions/IntegrationEventV2Request'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/IntegrationStateV2'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
/v1/referrals:
post:
operationId: createReferral
summary: Create referral code for an advocate
description: >
Creates a referral code for an advocate. The code will be valid for the
referral campaign for which is created, indicated in the `campaignId`
parameter, and will be associated with the profile specified in the
`advocateProfileIntegrationId` parameter as the advocate's profile.
security:
- api_key_v1: []
tags:
- Referrals
parameters:
- name: body
required: true
in: body
schema:
$ref: '#/definitions/NewReferral'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/Referral'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
/v1/referrals_for_multiple_advocates:
post:
operationId: createReferralsForMultipleAdvocates
summary: Create referral codes for multiple advocates
description: >
Creates unique referral codes for multiple advocates. The code will be
valid for the referral campaign for which it is created, indicated in
the `campaignId` parameter, and one referral code will be associated
with one advocate using the profile specified in the
`advocateProfileIntegrationId` parameter as the advocate's profile.
security:
- api_key_v1: []
tags:
- Referrals
parameters:
- *ref_3
- name: body
required: true
in: body
schema:
$ref: '#/definitions/NewReferralsForMultipleAdvocates'
responses:
'201':
description: Created
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
data:
type: array
items:
$ref: '#/definitions/Referral'
'204':
description: No Content
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/customer_data/{integrationId}':
delete:
operationId: deleteCustomerData
summary: Delete customer's personal data
description: >
Delete all attributes on the customer profile and on entities that
reference this customer profile.
**Important:** To preserve performance, we recommend avoiding deleting
customer data during peak-traffic hours.
security:
- api_key_v1: []
tags:
- Customer profiles
parameters:
- &ref_4
name: integrationId
in: path
type: string
description: >
The integration ID of the customer profile. You can get the
`integrationId` of a profile using:
- A customer session integration Id with the [Update customer
session
endpoint](https://docs.talon.one/integration-api/#operation/updateCustomerSessionV2).
- The Management API with the [List application's customers
endpoint](https://docs.talon.one/management-api/#operation/getApplicationCustomers).
responses:
'204':
description: No Content
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/coupon_reservations/{couponValue}':
post:
operationId: createCouponReservation
summary: Create coupon reservation
description: >
Create a coupon reservation for specified customer profiles on the
specified coupon.
Reserving a coupon allows you to associate a coupon code to a given
customer(s).
You can then list the reserved coupons of a given customer
with the [List customer data
endpoint](/integration-api/#operation/getCustomerInventory).
If a coupon gets created for a specific user, it will automatically show
up in their coupons.
When a user redeems a coupon, a reservation is automatically created
after the redemption and
the used coupon will be returned in the [List customer data
endpoint](/integration-api/#operation/getCustomerInventory).
**Important:**
- This endpoint creates a **soft** reservation. _Any_ customer
can use a reserved coupon code and proceed to checkout.
- To create a hard reservation, use the
[Create coupons](/management-api/#operation/createCoupons) or
[Create coupons for multiple recipients](/management-api/#operation/createCouponsForMultipleRecipients) endpoints
setting the `recipientsIntegrationId` property.
For example, you can use this endpoint and `List customer data` to
create a _coupon wallet_ by
reserving coupon codes for a customer, and then displaying their coupon
wallet
when they visit your store.
security:
- api_key_v1: []
tags:
- Coupons
parameters:
- name: couponValue
in: path
type: string
description: The code of the coupon.
required: true
- name: body
required: true
in: body
schema:
$ref: '#/definitions/CouponReservations'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/Coupon'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
delete:
operationId: deleteCouponReservation
summary: Delete coupon reservations
description: >
Remove all the coupon reservations from the provided customer profile
integration IDs and the provided
coupon code.
security:
- api_key_v1: []
tags:
- Coupons
parameters:
- name: couponValue
in: path
type: string
description: The code of the coupon.
required: true
- name: body
required: true
in: body
schema:
$ref: '#/definitions/CouponReservations'
responses:
'204':
description: No Content
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/coupon_reservations/customerprofiles/{couponValue}':
get:
operationId: getReservedCustomers
summary: List customers that have this coupon reserved
description: >
Return all customers that have this coupon marked as reserved.
Coupons are reserved in the following ways:
- To create a soft reservation (any customer can use the coupon), use
the [Create coupon reservation](#operation/createCouponReservation)
endpoint.
- To create a hard reservation (only the given customer can use the
coupon), create a coupon in the Campaign Manager for a given
`recipientIntegrationId` or use the [Create
coupons](/management-api/#operation/createCoupons) or [Create coupons
for multiple
recipients](/management-api/#operation/createCouponsForMultipleRecipients)
endpoints.
security:
- api_key_v1: []
tags:
- Coupons
parameters:
- name: couponValue
in: path
type: string
description: The code of the coupon.
required: true
responses:
'200':
description: OK
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
data:
type: array
items:
$ref: '#/definitions/CustomerProfile'
'400':
description: Bad request
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/customer_profiles/{integrationId}/inventory':
get:
operationId: getCustomerInventory
summary: List customer data
description: >
Return the customer inventory regarding entities referencing this
customer profile's `integrationId`.
Typical entities returned are: customer profile information, referral
codes, loyalty points and reserved coupons.
Reserved coupons also include redeemed coupons.
You can also use this endpoint to get the projected loyalty balances in
order to notify
your customers about points that are about to expire, or to remind them
how many points they have.
security:
- api_key_v1: []
tags:
- Customer profiles
parameters:
- *ref_4
- name: profile
in: query
required: false
type: boolean
description: >-
Set to `true` to include customer profile information in the
response.
- name: referrals
in: query
required: false
type: boolean
description: Set to `true` to include referral information in the response.
- name: coupons
in: query
required: false
type: boolean
description: Set to `true` to include coupon information in the response.
- name: loyalty
in: query
required: false
type: boolean
description: Set to `true` to include loyalty information in the response.
- name: giveaways
in: query
required: false
type: boolean
description: Set to `true` to include giveaways information in the response.
- name: loyaltyProjectionEndDate
in: query
required: false
type: string
format: date-time
description: >-
Set an end date to query the projected loyalty balances. You can
project results up to 31 days from today.
responses:
'200':
description: OK
schema:
$ref: '#/definitions/CustomerInventory'
'401':
description: Unauthorized - Invalid API key
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorResponseWithStatus'
'/v1/catalogs/{catalogId}/sync':
put:
operationId: syncCatalog
summary: Sync cart item catalog
description: >
Perform one or more of the following sync actions on this cart item
catalog, up to 1000 actions:
- Add an item to the catalog.
- Edit the attributes of an item in the catalog.
- Edit the attributes of more than one item in the catalog.
- Remove an item from the catalog.
- Remove more than one item from the catalog.
**Note**: For more information, see [our documentation on managing cart
item
catalogs](https://docs.talon.one/docs/product/account/dev-tools/managing-cart-item-catalogs).
### Filtering cart items
Use [cart item
attributes](https://docs.talon.one/docs/product/account/dev-tools/managing-cart-item-catalogs#displaying-the-details-and-content-of-a-catalog)
to filter items and select the ones you want to edit or delete when
editing or deleting more than one item
at a time.
The `filters` object contains the following properties:
- `attr`: A [cart item
attribute](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes)
connected to the catalog. It is applied to all items in the catalog.
- `op`: The filtering operator indicating the relationship between the
value of each
cart item in the catalog and the value of the `value` property for the attribute selected
in `attr`.
The value of `op` can be one of the following:
- `EQ`: Equal to `value`
- `LT`: Less than `value`
- `LE`: Less than or equal to `value`
- `GT`: Greater than `value`
- `GE`: Greater than or equal to `value`
- `IN`: One of the comma-separated values that `value` is set to.
**Note:** `GE`, `LE`, `GT`, `LT` are for numeric values only.
- `value`: The value of the attribute selected in `attr`.
### Payload examples
Synchronization actions are sent as `PUT` requests. See the structure
for each action:
Adding an item to the catalog
```json
{
"actions": [
{
"payload": {
"attributes": {
"color": "Navy blue",
"type": "shoe"
},
"replaceIfExists": true,
"sku": "SKU1241028"
},
"type": "ADD"
}
]
}
```
Editing the attributes of an item in the catalog
```json
{
"actions": [
{
"payload": {
"attributes": {
"age": 11,
"origin": "germany"
},
"createIfNotExists": false,
"sku": "SKU1241028"
},
"type": "PATCH"
}
]
}
```
Editing the attributes of several items at once
```json
{
"actions": [
{
"payload": {
"attributes": {
"color": "red"
},
"filters": [
{
"attr": "color",
"op": "EQ",
"value": "blue"
}
]
},
"type": "PATCH_MANY"
}
]
}
```
Removing an item from the catalog
```json
{
"actions": [
{
"payload": {
"sku": "SKU1241028"
},
"type": "REMOVE"
}
]
}
```
Removing several items from the catalog at once
```json
{
"actions": [
{
"payload": {
"filters": [
{
"attr": "color",
"op": "EQ",
"value": "blue"
}
]
},
"type": "REMOVE_MANY"
}
]
}
```
Removing shoes of sizes above 45 from the catalog
Let's imagine that we have a shoe store and we have decided to stop selling
shoes larger than size 45. We can remove from the catalog all the shoes of sizes above 45
with a single action:
```json
{
"actions": [
{
"payload": {
"filters": [
{
"attr": "size",
"op": "GT",
"value": "45"
}
]
},
"type": "REMOVE_MANY"
}
]
}
```
tags:
- Catalogs
parameters:
- name: catalogId
in: path
required: true
type: integer
- name: body
required: true
in: body
schema:
$ref: '#/definitions/CatalogSyncRequest'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Catalog'
'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'
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 for the featureflag
value:
type: string
description: The value for the featureflag
created:
type: string
format: date-time
description: The exact moment this entity was last created.
modified:
type: string
format: date-time
description: The exact moment this entity was last modified.
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
Entity:
type: object
required:
- id
- created
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
created:
type: string
format: date-time
description: The exact moment 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.
created:
type: string
format: date-time
description: The exact moment this entity was created.
MutableEntity:
type: object
required:
- modified
properties:
modified:
type: string
format: date-time
description: The exact moment 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 account that owns this entity.
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.
ApplicationCustomerEntity:
type: object
properties:
profileId:
type: integer
description: >-
The globally unique Talon.One ID of the customer that created this
entity.
example: 138
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 exact moment 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
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 amount of discounts that can be given with this coupon code.
startDate:
type: string
format: date-time
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
minimum: 0
description: >-
Expiry 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.
Defaults to a list equivalent to the
`[A-Z, 0-9]` regexp.
example:
- A
- B
- C
- D
- E
- '2'
- '0'
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.
required:
- userId
- token
- created
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'
campaignPriority:
type: string
description: >
Default
[priority](https://docs.talon.one/docs/product/applications/setting-up-campaign-priorities)
for campaigns
created in this Application.
enum:
- universal
- stackable
- exclusive
default: universal
example: universal
exclusiveCampaignsStrategy:
type: string
description: The strategy used when choosing exclusive campaigns for evaluation.
enum:
- listOrder
- lowestDiscount
- highestDiscount
default: listOrder
example: listOrder
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. See [the
docs](https://docs.talon.one/docs/product/campaigns/campaign-evaluation/#flattened-cart-items).
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
required:
- name
- timezone
- currency
NewApplication:
type: object
description: ''
required:
- name
- timezone
- currency
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'
campaignPriority:
type: string
description: >
Default
[priority](https://docs.talon.one/docs/product/applications/setting-up-campaign-priorities)
for campaigns
created in this Application.
enum:
- universal
- stackable
- exclusive
default: universal
example: universal
exclusiveCampaignsStrategy:
type: string
description: The strategy used when choosing exclusive campaigns for evaluation.
enum:
- listOrder
- lowestDiscount
- highestDiscount
default: listOrder
example: listOrder
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. See [the
docs](https://docs.talon.one/docs/product/campaigns/campaign-evaluation/#flattened-cart-items).
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}$'
additionalProperties: false
Application:
type: object
description: ''
required:
- id
- created
- modified
- accountId
- name
- timezone
- currency
- loyaltyPrograms
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
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The exact moment 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'
campaignPriority:
type: string
description: >
Default
[priority](https://docs.talon.one/docs/product/applications/setting-up-campaign-priorities)
for campaigns
created in this Application.
enum:
- universal
- stackable
- exclusive
default: universal
example: universal
exclusiveCampaignsStrategy:
type: string
description: The strategy used when choosing exclusive campaigns for evaluation.
enum:
- listOrder
- lowestDiscount
- highestDiscount
default: listOrder
example: listOrder
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. See [the
docs](https://docs.talon.one/docs/product/campaigns/campaign-evaluation/#flattened-cart-items).
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
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 group.
minLength: 1
description:
type: string
description: A longer description of the campaign group.
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications that this campaign group is
enabled for
items:
type: integer
campaignIds:
type: array
description: A list of the IDs of the campaigns that this campaign group owns
items:
type: integer
required:
- name
CampaignGroup:
type: object
description: ''
required:
- id
- created
- modified
- accountId
- name
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
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The exact moment 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 group.
minLength: 1
description:
type: string
description: A longer description of the campaign group.
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications that this campaign group is
enabled for
items:
type: integer
campaignIds:
type: array
description: A list of the IDs of the campaigns that this campaign group owns
items:
type: integer
additionalProperties: false
UpdateCampaignGroup:
type: object
description: ''
required:
- name
properties:
name:
type: string
description: The name of this campaign group.
minLength: 1
description:
type: string
description: A longer description of the campaign group.
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications that this campaign group is
enabled for
items:
type: integer
campaignIds:
type: array
description: A list of the IDs of the campaigns that this campaign group owns
items:
type: integer
additionalProperties: false
NewCampaign:
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 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
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.
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
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
required:
- name
- state
- tags
- limits
- features
UpdateCampaign:
type: object
properties:
name:
type: string
title: Campaign Name
description: A user-facing name for this campaign.
minLength: 1
description:
type: string
title: Campaign Description
description: A detailed description of the campaign.
startTime:
type: string
format: date-time
description: Timestamp when the campaign will become active.
endTime:
type: string
format: date-time
description: Timestamp when the campaign will become inactive.
attributes:
type: object
description: Arbitrary properties associated with this campaign
additionalProperties: true
state:
type: string
enum:
- enabled
- disabled
- archived
default: enabled
description: |
A disabled or archived campaign is not evaluated for rules or coupons.
activeRulesetId:
type: integer
description: ID of Ruleset this campaign applies on customer session evaluation.
tags:
type: array
description: A list of tags for the campaign.
maxItems: 50
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
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 that own this entity.
items:
type: integer
required:
- name
- tags
- limits
- features
Campaign:
type: object
description: ''
required:
- id
- created
- applicationId
- userId
- name
- state
- tags
- limits
- features
- description
properties:
id:
type: integer
description: Unique ID for this entity.
created:
type: string
format: date-time
description: The exact moment this entity was created.
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
userId:
type: integer
description: The ID of the account that owns this entity.
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 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
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.
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
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
couponRedemptionCount:
type: integer
description: Number of coupons redeemed in the campaign.
example: 163
referralRedemptionCount:
type: integer
description: Number of referral codes redeemed in the campaign.
example: 3
discountCount:
type: number
description: Total amount of discounts redeemed in the campaign.
example: 288
discountEffectCount:
type: integer
description: Total number of times discounts were redeemed in this campaign.
example: 343
couponCreationCount:
type: integer
description: Total number of coupons created by rules in this campaign.
example: 16
customEffectCount:
type: integer
description: Total number of custom effects triggered by rules in this campaign.
example: 0
referralCreationCount:
type: integer
description: Total number of referrals created by rules in this campaign.
example: 8
addFreeItemEffectCount:
type: integer
description: >-
Total number of times triggering add free item effext is allowed in
this campaign.
example: 0
awardedGiveawaysCount:
type: integer
description: Total number of giveaways awarded by rules in this campaign.
example: 9
createdLoyaltyPointsCount:
type: number
description: Total number of loyalty points created by rules in this campaign.
example: 9
createdLoyaltyPointsEffectCount:
type: integer
description: >-
Total number of loyalty point creation effects triggered by rules in
this campaign.
example: 2
redeemedLoyaltyPointsCount:
type: number
description: Total number of loyalty points redeemed by rules in this campaign.
example: 8
redeemedLoyaltyPointsEffectCount:
type: integer
description: >-
Total number of loyalty point redemption effects triggered by rules in
this campaign.
example: 9
callApiEffectCount:
type: integer
description: Total number of webhook triggered by rules in this campaign.
example: 0
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
NewRuleset:
type: object
required:
- rules
- bindings
properties:
rules:
type: array
description: Set of rules to apply.
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.
Ruleset:
type: object
description: ''
required:
- id
- created
- userId
- rules
- bindings
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
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
userId:
type: integer
description: The ID of the account that owns this entity.
rules:
type: array
description: Set of rules to apply.
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.
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:
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:
- id
- created
- applicationId
- set
- version
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
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
version:
type: integer
minimum: 1
description: Version of the campaign set
set:
$ref: '#/definitions/CampaignSetBranchNode'
additionalProperties: false
CampaignSetV2:
type: object
description: ''
required:
- id
- created
- applicationId
- set
- version
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
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
version:
type: integer
minimum: 1
description: Version of the campaign set
set:
description: Child elements of this set
$ref: '#/definitions/CampaignPrioritiesV2'
additionalProperties: false
CampaignSetIDs:
type: object
description: Campaign IDs for each priority.
additionalProperties: false
properties:
campaignId:
type: integer
description: ID of the campaign
CampaignPrioritiesV2:
type: object
properties:
exclusive:
type: array
items:
$ref: '#/definitions/CampaignSetIDs'
stackable:
type: array
items:
$ref: '#/definitions/CampaignSetIDs'
universal:
type: array
items:
$ref: '#/definitions/CampaignSetIDs'
CampaignSetNode:
type: object
required:
- type
properties:
type:
type: string
CampaignSetBranchNode:
type: object
additionalProperties: false
required:
- type
- name
- operator
- elements
properties:
type:
type: string
description: Indicates the node type
enum:
- SET
name:
type: string
description: Name of the set
operator:
type: string
description: How does the set operates on its elements
enum:
- ALL
- FIRST
elements:
type: array
description: Child elements of this set
items:
$ref: '#/definitions/CampaignSetNode'
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
description: Version of the campaign set
set:
$ref: '#/definitions/CampaignSetBranchNode'
additionalProperties: false
NewCampaignSetV2:
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
description: Version of the campaign set
set:
$ref: '#/definitions/CampaignPrioritiesV2'
additionalProperties: false
ReferralConstraints:
type: object
required:
- campaignId
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: >-
Expiry 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: >-
Expiry 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: >-
Expiry 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
additionalProperties: false
ImportEntity:
type: object
required:
- id
properties:
importId:
type: integer
description: The ID of the Import which created this referral.
Referral:
type: object
description: ''
required:
- id
- created
- campaignId
- advocateProfileIntegrationId
- code
- usageCounter
- usageLimit
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
created:
type: string
format: date-time
description: The exact moment 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: >-
Expiry 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
importId:
type: integer
description: The ID of the Import which created this referral.
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: >-
Expiry 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: >-
Expiry 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 item.
additionalProperties: true
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:
- E
- F
- I
- Z
- '1'
- '2'
- '3'
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: >-
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
created:
type: string
format: date-time
description: The exact moment 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: >-
Expiry 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
importId:
type: integer
description: The ID of the Import which created this referral.
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")
applicationIds:
type: array
description: >-
Application IDs of the applications to which a campaign should be
copied to
additionalProperties: true
items:
type: integer
description:
type: string
title: Campaign Description
description: A detailed description of the campaign.
startTime:
type: string
format: date-time
description: Timestamp when the campaign will become active.
endTime:
type: string
format: date-time
description: Timestamp when the campaign will become inactive.
tags:
type: array
description: A list of tags for the campaign.
maxItems: 50
items:
type: string
minLength: 1
maxLength: 50
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 amount of discounts that can be given with this coupon code.
startDate:
type: string
format: date-time
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
minimum: 0
description: >-
Expiry 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
endpoint](https://docs.talon.one/management-api/#operation/createCouponsAsync).
attributes:
type: object
description: Arbitrary properties associated with this item
additionalProperties: true
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-#####'
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 amount of discounts that can be given with this coupon code.
startDate:
type: string
format: date-time
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
minimum: 0
description: >-
Expiry 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
recipientsIntegrationIds:
title: Receiving customer profiles integration IDs
type: array
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.
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
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 amount of discounts that can be given with this coupon code.
startDate:
type: string
format: date-time
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
minimum: 0
description: >-
Expiry 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
attributes:
type: object
description: Arbitrary properties associated with this item
additionalProperties: true
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 amount of discounts that can be given with this coupon code.
startDate:
type: string
format: date-time
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
minimum: 0
description: >-
Expiry 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
batchID:
title: Batch ID
type: string
description: The id of the batch the coupon belongs to.
additionalProperties: false
Coupon:
type: object
description: ''
required:
- id
- created
- campaignId
- value
- usageCounter
- usageLimit
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
created:
type: string
format: date-time
description: The exact moment 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 amount of discounts that can be given with this coupon code.
startDate:
type: string
format: date-time
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
minimum: 0
description: >-
Expiry 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: Number of coupon usages
example: 10
description: The number of times this coupon has been successfully used.
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.
discountRemainder:
type: number
title: Coupon Discount Remainder
description: The remaining discount this coupon can give.
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.
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
endpoint](/integration-api/#operation/createCouponReservation).
- `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
endpoint](/management-api/#operation/createCoupons) or [Create coupons
for multiple recipients
endpoint](/management-api/#operation/createCouponsForMultipleRecipients).
default: true
batchId:
title: Batch ID
type: string
description: The id of the batch the coupon belongs to.
example: 32535-43255
additionalProperties: false
InventoryCoupon:
type: object
description: ''
required:
- id
- created
- campaignId
- value
- usageCounter
- usageLimit
- state
- profileRedemptionCount
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
created:
type: string
format: date-time
description: The exact moment 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 amount of discounts that can be given with this coupon code.
startDate:
type: string
format: date-time
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
minimum: 0
description: >-
Expiry 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: Number of coupon usages
example: 10
description: The number of times this coupon has been successfully used.
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.
discountRemainder:
type: number
title: Coupon Discount Remainder
description: The remaining discount this coupon can give.
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.
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
endpoint](/integration-api/#operation/createCouponReservation).
- `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
endpoint](/management-api/#operation/createCoupons) or [Create coupons
for multiple recipients
endpoint](/management-api/#operation/createCouponsForMultipleRecipients).
default: true
batchId:
title: Batch ID
type: string
description: The id of the batch the coupon belongs to.
example: 32535-43255
profileRedemptionCount:
type: integer
title: Number of coupon usages
description: The number of times the coupon was redeemed by the profile.
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
campaignRevenue:
type: number
description: Amount of revenue in this campaign (for coupon or discount sessions).
totalCampaignRevenue:
type: number
description: >-
Amount of revenue in this campaign since it began (for coupon or
discount sessions).
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.
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.
totalAddedLoyaltyPoints:
type: number
description: Number of added loyalty points in the campaign since it began.
deductedLoyaltyPoints:
type: number
description: >-
Number of deducted loyalty points in the campaign in a specific
interval.
totalDeductedLoyaltyPoints:
type: number
description: Number of deducted loyalty points in the campaign since it began.
additionalProperties: false
LoyaltyStatistics:
type: object
description: ''
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.
totalPendingPoints:
type: number
description: Total of pending points for this loyalty program.
totalSpentPoints:
type: number
description: Total of spent points for this loyalty program.
totalExpiredPoints:
type: number
description: Total of expired points for this loyalty program.
totalMembers:
type: number
description: Number of loyalty program members.
newMembers:
type: number
description: Number of members who joined on this day.
spentPoints:
description: Points spent on this day.
$ref: '#/definitions/LoyaltyDashboardPointsBreakdown'
earnedPoints:
description: Points that were earned on this day.
$ref: '#/definitions/LoyaltyDashboardPointsBreakdown'
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.
totalPendingPoints:
type: number
description: Total of pending points for this loyalty program.
totalSpentPoints:
type: number
description: Total of spent points for this loyalty program.
totalExpiredPoints:
type: number
description: Total of expired points for this loyalty program.
totalMembers:
type: number
description: Number of loyalty program members.
newMembers:
type: number
description: Number of members who joined on this day.
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
createdViaRuleEngine:
type: number
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
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
status:
type: integer
description: HTTP status code of response
method:
type: string
description: HTTP method of request
requestUri:
type: string
description: target URI of request
time:
type: string
format: date-time
description: timestamp of request
requestPayload:
type: string
description: payload of request
responsePayload:
type: string
description: payload of response
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
integrationRequestUuid:
type: string
description: >-
UUID reference of the integration request linked to this webhook
request
webhookId:
type: integer
description: ID of the webhook that triggered the request
applicationId:
type: integer
description: ID of the application that triggered the webhook
url:
type: string
description: Target url of request
request:
type: string
description: Request message
response:
type: string
description: Response message
status:
type: integer
description: HTTP status code of response
requestTime:
type: string
format: date-time
description: Timestamp of request
responseTime:
type: string
format: date-time
description: Timestamp of response
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
webhookId:
type: integer
description: ID of the webhook that triggered the request
applicationId:
type: integer
description: ID of the application that triggered the webhook
campaignId:
type: integer
description: ID of the campaign that triggered the webhook
created:
type: string
format: date-time
description: Timestamp of request
User:
type: object
description: ''
required:
- id
- created
- modified
- email
- accountId
- inviteToken
- state
- name
- policy
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
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The exact moment 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
additionalProperties: false
NewInvitation:
type: object
description: Parameters for inviting a new user
required:
- email
- acl
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 actual access control on the user level.
Use one of the following:
- normal user: `{"Role": 0}`
- admin: `{"Role": 127}`
example: '{"Role":0}'
roles:
type: array
description: An array of roleIDs to assign the new user to
items:
type: integer
example:
- 2
- 4
- 13
Change:
type: object
description: ''
required:
- id
- created
- userId
- entity
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
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
userId:
type: integer
description: The ID of the account that owns this entity.
applicationId:
type: integer
description: ID of application associated with change
entity:
type: string
description: API endpoint on which the change was initiated.
old:
type: object
description: Resource before the change occurred.
additionalProperties: true
new:
type: object
description: Resource after the change occurred.
additionalProperties: true
additionalProperties: false
LoyaltyPoints:
type: object
description: Points to add or 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: Allows to specify a name for the addition or deduction
validityDuration:
type: string
description: >-
Indicates the duration after which the added loyalty points should
expire. The format is a number followed by one letter indicating the
time unit, like '1h' or '40m' (defined by Go time package).
pendingDuration:
type: string
description: >-
Indicates the amount of time before the points are considered valid.
The format is a number followed by one letter indicating the time
unit, like '1h' or '40m' (defined by Go time package).
subLedgerID:
type: string
description: >-
This specifies if we are adding loyalty points to the main ledger or a
subledger
LoyaltyProgram:
type: object
description: ''
required:
- id
- created
- name
- title
- description
- accountID
- defaultValidity
- defaultPending
- subscribedApplications
- allowSubledger
- timezone
- cardBased
properties:
id:
type: integer
description: >-
The ID of loyalty program. 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.
created:
type: string
format: date-time
description: The exact moment 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: >-
Indicates the default duration after which new loyalty points should
expire. The format is a number, followed by one letter indicating the
unit; like '1h' or '40m'.
example: unlimited
defaultPending:
type: string
description: >-
Indicates the default duration for the pending time, after which
points will be valid. The format is a number followed by a duration
unit, like '1h' or '40m'.
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`.
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
additionalProperties: false
LoyaltyTier:
type: object
description: ''
required:
- id
- created
- programID
- name
- minPoints
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
created:
type: string
format: date-time
description: The exact moment 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: >-
Indicates the default duration after which new loyalty points should
expire. The format is a number, followed by one letter indicating the
unit; like '1h' or '40m'.
example: unlimited
defaultPending:
type: string
description: >-
Indicates the default duration for the pending time, after which
points will be valid. The format is a number followed by a duration
unit, like '1h' or '40m'.
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`.
NewLoyaltyProgram:
type: object
description: ''
required:
- name
- title
- defaultValidity
- defaultPending
- allowSubledger
- timezone
- cardBased
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: >-
Indicates the default duration after which new loyalty points should
expire. The format is a number, followed by one letter indicating the
unit; like '1h' or '40m'.
example: unlimited
defaultPending:
type: string
description: >-
Indicates the default duration for the pending time, after which
points will be valid. The format is a number followed by a duration
unit, like '1h' or '40m'.
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`.
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: >-
Indicates the default duration after which new loyalty points should
expire. The format is a number, followed by one letter indicating the
unit; like '1h' or '40m'.
example: unlimited
defaultPending:
type: string
description: >-
Indicates the default duration for the pending time, after which
points will be valid. The format is a number followed by a duration
unit, like '1h' or '40m'.
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`.
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:
transactions:
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
programID:
type: integer
customerProfileID:
type: string
cardID:
type: integer
customerSessionID:
type: string
eventID:
type: integer
type:
type: string
description: >
The type of the ledger transaction. Possible values are addition,
subtraction, expire or expiring (for expiring points ledgers)
amount:
type: number
startDate:
type: string
format: date-time
expiryDate:
type: string
format: date-time
name:
type: string
description: >-
A name referencing the condition or effect that added this entry, or
the specific name provided in an API call.
subLedgerID:
type: string
description: >-
This specifies if we are adding loyalty points to the main ledger or a
subledger
userID:
type: integer
description: >-
This is the ID of the user who created this entry, if the addition or
subtraction was done manually.
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'
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.
pendingPoints:
type: number
title: Total pending points
description: >-
Total amount of points awarded to this customer but not available
until their start date.
spentPoints:
type: number
title: Total spent points
description: Total amount of points already spent by this customer.
expiredPoints:
type: number
title: Total expired points
description: >-
Total amount of points awarded but never redeemed. They cannot be used
anymore.
LoyaltyLedger:
type: object
description: Ledger of Balance in Loyalty Program for a Customer.
required:
- ledger
- subledgers
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'
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: 46
pendingBalance:
type: number
title: Pending balance
description: Sum of pending points
example: 10
expiredBalance:
type: number
title: Expired balance
description: Sum of expired points
example: 30
spentBalance:
type: number
title: Spent balance
description: Sum of spent points
example: 84
tentativeCurrentBalance:
type: number
title: Tentative current balance
description: >-
Sum of currently active points, including points added and deducted in
open sessions
example: 56
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
projection:
$ref: '#/definitions/LoyaltyProjection'
description: Keep track of loyalty points that are expected in the future.
example: 10
additionalProperties: false
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
LoyaltyCard:
type: object
description: ''
required:
- id
- created
- programID
- status
- identifier
- usersPerCardLimit
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
created:
type: string
format: date-time
description: The exact moment 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', 'disabled']
identifier:
type: string
description: The alphanumeric identifier of the loyalty card.
usersPerCardLimit:
type: integer
minimum: 0
example: 111
description: >
The max amount of user profiles a card can be shared with. 0 means
unlimited.
profiles:
type: array
description: Integration IDs of the customers associated with 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'
additionalProperties: false
CardLedgerTransactionLogEntry:
type: object
description: Loyalty ledger transaction log entry.
required:
- created
- programId
- cardIdentifier
- sessionId
- type
- name
- startDate
- expiryDate
- subledgerId
- amount
- id
properties:
created:
type: string
format: date-time
description: The exact moment the loyalty ledger transaction happened.
example: '2022-01-02T15:04:05Z07:00'
programId:
type: integer
description: ID of the loyalty program.
example: 324
cardIdentifier:
type: string
description: Identifier of the loyalty card.
maxLength: 255
example: summer-loyalty-card-0543
sessionId:
type: string
description: ID of the customer session.
maxLength: 255
example: 05c2da0d-48fa-4aa1-b629-898f58f1584d
type:
type: string
enum:
- addition
- subtraction
description: |
Type of transaction. Possible values are:
- `addition`: Points were added.
- `subtraction`: Points were subtracted.
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: |
Start date of the loyalty ledger entry. Possible values are:
- `immediate`: Points ere active immediately.
- `timestamp value`: Points are become active from certain date.
maxLength: 64
example: '2022-01-02T15:04:05Z07:00'
expiryDate:
type: string
description: |
Expiry date of the loyalty ledger entry. Possible values are:
- `unlimited`: Points have no expiration date.
- `timestamp value`: Points have certain expiration date.
example: '2022-01-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 of the loyalty ledger transaction.
example: 10.25
id:
type: integer
description: ID of the loyalty ledger transaction.
example: 123
UpdateLoyaltyCard:
type: object
required:
- status
properties:
status:
type: string
description: |
Status of the loyalty card. Can be one of: ['active', 'disabled']
LoyaltyCardProfileRegistration:
type: object
required:
- integrationId
- timestamp
properties:
integrationId:
type: string
maxLength: 1000
description: Integration ID of the customer associated with the card.
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: my_customer_profile
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: 46
pendingBalance:
type: number
title: Pending balance
description: Sum of pending points
example: 10
expiredBalance:
type: number
title: Expired balance
description: Sum of expired points
example: 30
spentBalance:
type: number
title: Spent balance
description: Sum of spent points
example: 84
tentativeCurrentBalance:
type: number
title: Tentative current balance
description: >-
Sum of currently active points, including points added and deducted in
open sessions
example: 56
LoyaltyProjection:
description: Group of all loyalty points expected in the future.
type: object
required:
- balances
- totalExpiringPoints
- totalActivatingPoints
properties:
projections:
type: array
maxItems: 31
items:
$ref: '#/definitions/LoyaltyProjectionData'
totalExpiringPoints:
type: number
description: >-
Sum of points to be expired by the projection date set in the query
parameter.
example: 10
totalActivatingPoints:
type: number
description: >-
Sum of points to be active by the projection date set in the query
parameter.
example: 40
LoyaltyProjectionData:
type: object
required:
- date
- expiringPoints
- activatingPoints
- projectedBalance
properties:
date:
type: string
format: date-time
example: 2021-01-24T17:32:28.000Z
description: Specific date of projection.
expiringPoints:
type: number
description: Points that will be expired by the specified date.
example: 14
activatingPoints:
type: number
description: Points that will be active by the specified date.
example: 25
projectedBalance:
type: number
description: 'Current balance plus projected active points, minus expiring points.'
example: 57
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
CustomerProfile:
type: object
description: ''
required:
- id
- created
- integrationId
- accountId
- closedSessions
- totalSales
- lastActivity
- attributes
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
created:
type: string
description: >-
The exact moment this entity was created. The exact moment 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: Sum of all purchases made by this customer
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: A list of audiences the customer belongs to
items:
$ref: '#/definitions/AudienceMembership'
title: Audience memberships
lastActivity:
type: string
format: date-time
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'
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
referral:
type: string
maxLength: 100
description: Any referral code entered.
title: Referral code entered in session
state:
type: string
enum:
- open
- closed
- partially_returned
- cancelled
default: 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](/docs/dev/concepts/entities#customer-session).
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
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: ''
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
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))
4. `partially_returned` → `cancelled`
For more information, see [Customer session
states](/docs/dev/concepts/entities#customer-session).
title: Customer's session state
cartItems:
type: array
description: >
The items to add to this sessions.
- If cart item flattening is disabled: **Do not exceed 1000 items**
(regardless of their `quantity`) per request.
- If cart item flattening is enabled: **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
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**: If you [create a unique identifier
budget](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets/#budget-types)
for your campaign, ensure the session contains an identifier by the
time you close it.
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: ''
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: ''
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 exact moment 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 exact moment 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
referral:
type: string
maxLength: 100
description: Any referral code entered.
title: Referral code entered in session
state:
type: string
enum:
- open
- closed
- partially_returned
- cancelled
default: 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](/docs/dev/concepts/entities#customer-session).
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
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: >-
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
created:
type: string
description: >-
The exact moment this entity was created. The exact moment 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
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))
4. `partially_returned` → `cancelled`
For more information, see [Customer session
states](/docs/dev/concepts/entities#customer-session).
title: Customer's session state
cartItems:
type: array
description: >
The items to add to this sessions.
- If cart item flattening is disabled: **Do not exceed 1000 items**
(regardless of their `quantity`) per request.
- If cart item flattening is enabled: **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
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**: If you [create a unique identifier
budget](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets/#budget-types)
for your campaign, ensure the session contains an identifier by the
time you close it.
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 sum of cart-items, as well as additional costs, before any
discounts applied
example: 119.99
cartItemTotal:
type: number
title: Cart Items Total
description: The total sum of cart-items before any discounts applied
example: 99.99
additionalCostTotal:
type: number
title: Additional Costs Total
description: The total sum of additional costs before any discounts 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:
- name
- sku
- quantity
- price
x-attributable: true
properties:
name:
title: Name of item
type: string
description: Name of item
minLength: 1
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: >
Quantity of item. **Important:** If you enabled [cart item
flattening](https://docs.talon.one/docs/product/campaigns/campaign-evaluation/#flattened-cart-items),
the quantity is always one and the same cart item might receive
multiple per-item discounts. Ensure you can process multiple discounts
on one cart item correctly.
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 item
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
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
type:
type: string
title: Event Type
description: A string representing the event. Must not be a reserved event name.
minLength: 1
example: pageViews
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
type:
type: string
title: Event Type
description: A string representing the event. Must not be a reserved event name.
minLength: 1
example: pageViews
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: >-
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
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
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
type:
type: string
title: Event Type
description: A string representing the event. Must not be a reserved event name.
minLength: 1
example: pageViews
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](/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. This is
the response type returned by the V2 PUT customer_session endpoint
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/Coupon'
triggeredCampaigns:
type: array
items:
$ref: '#/definitions/Campaign'
effects:
type: array
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'
IntegrationCustomerSessionResponse:
type: object
properties:
customerSession:
$ref: '#/definitions/CustomerSessionV2'
ApplicationCustomer:
type: object
description: ''
required:
- id
- created
- integrationId
- accountId
- closedSessions
- totalSales
- lastActivity
- attributes
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.
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.
created:
type: string
description: >-
The exact moment this entity was created. The exact moment this entity
was created. The exact moment this entity was created. The exact
moment 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: Sum of all purchases made by this customer
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: A list of audiences the customer belongs to
items:
$ref: '#/definitions/AudienceMembership'
title: Audience memberships
lastActivity:
type: string
format: date-time
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'
advocateIntegrationId:
type: string
maxLength: 1000
description: >-
The Integration ID of the Customer Profile that referred this Customer
in the Application.
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
- applicationId
- integrationId
- coupon
- referral
- state
- cartItems
- discounts
- total
- totalDiscounts
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
created:
type: string
description: >-
The exact moment this entity was created. The exact moment this entity
was created.
format: date-time
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
integrationId:
type: string
format: string
example: URNGV8294NV
maxLength: 1000
description: The integration ID set by your integration layer.
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](/docs/dev/concepts/entities#customer-session).
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: >-
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
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
profileId:
type: integer
description: >-
The globally unique Talon.One ID of the customer that created this
entity.
example: 138
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:
type: object
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
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
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: >-
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
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The exact moment 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: Your name.
policy:
type: string
description: a blob of acl json
state:
type: string
enum:
- deactivated
- active
description: >-
New state ("deactivated" or "active") for the user. Only usable by
admins for the user.
roles:
type: array
items:
type: integer
description: Update
applicationNotificationSubscriptions:
type: object
additionalProperties: true
ChangeProfilePassword:
type: object
required:
- password
- newPassword
properties:
password:
type: string
description: Your old password.
newPassword:
type: string
description: Your new password.
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.
resetToken:
type: string
minLength: 1
Environment:
type: object
description: ''
required:
- id
- created
- applicationId
- slots
- functions
- templates
- variables
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
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
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
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
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
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
type:
type: string
enum:
- string
- number
- boolean
- percent
- (list string)
- time
description: Defines the type of parameter value.
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.
attributeId:
type: integer
description: ID of the corresponding attribute.
example: 42
NewCampaignTemplate:
type: object
required:
- name
- state
- description
- instructions
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
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: >-
Template parameters are 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'
UpdateCampaignTemplate:
type: object
required:
- name
- state
- description
- instructions
- applicationsIds
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.
activeRulesetId:
type: integer
description: The ID of the Ruleset this Campaign Template will use.
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
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: >-
Template parameters are fields which can be used to replace values in
a rule.
items:
$ref: '#/definitions/CampaignTemplateParams'
applicationsIds:
type: array
description: >-
A list of the IDs of the applications that are subscribed to this
campaign template
items:
type: integer
campaignCollections:
type: array
description: The campaign collections from the blueprint campaign for the template.
items:
$ref: '#/definitions/CampaignTemplateCollection'
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
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
created:
type: string
format: date-time
description: The exact moment 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 account that owns this entity.
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.
activeRulesetId:
type: integer
description: The ID of the Ruleset this Campaign Template will use.
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
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: >-
Template parameters are fields which can be used to replace values in
a rule.
items:
$ref: '#/definitions/CampaignTemplateParams'
applicationsIds:
type: array
description: >-
A list of the IDs of the applications that are subscribed to this
campaign template A list of the 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'
updated:
type: string
format: date-time
description: >-
Timestamp of the most recent update to the campaign template or any of
its elements.
updatedBy:
type: string
description: Name of the user who last updated this campaign template if available.
validApplicationIds:
type: array
description: The IDs of the applications that are related to this entity.
items:
type: integer
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'
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
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: >-
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
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
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
eventType:
type: string
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.
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.
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.
description:
type: string
description: A description of this attribute.
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
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
editable:
type: boolean
description: Whether or not this attribute can be edited.
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications where this attribute is
available.
items:
type: integer
subscribedCatalogsIds:
type: array
description: A list of the IDs of the catalogs where this attribute is available.
items:
type: integer
allowedSubscriptions:
type: array
description: >
A list of allowed subscription types for this attribute.
**Note:** This only applies to attributes associated with the
`CartItem` entity.
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: >-
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
created:
type: string
format: date-time
description: The exact moment 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
eventType:
type: string
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.
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.
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.
description:
type: string
description: A description of this attribute.
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
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
editable:
type: boolean
description: Whether or not this attribute can be edited.
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications where this attribute is
available.
items:
type: integer
subscribedCatalogsIds:
type: array
description: A list of the IDs of the catalogs where this attribute is available.
items:
type: integer
allowedSubscriptions:
type: array
description: >
A list of allowed subscription types for this attribute.
**Note:** This only applies to attributes associated with the
`CartItem` entity.
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|\s)*$'
description: >-
The additional cost name that will be used in API requests and Talang.
E.g. if `name == "shipping"` then you would set the shipping
additional cost by including an `additionalCosts.shipping` property in
your request payload.
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.
description:
type: string
description: A description of this additional cost.
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications that are subscribed to this
additional cost
items:
type: integer
type:
type: string
enum:
- session
- item
- both
description: |
The type of additional cost. The following options can be chosen:
- `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: >-
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
created:
type: string
format: date-time
description: The exact moment 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|\s)*$'
description: >-
The additional cost name that will be used in API requests and Talang.
E.g. if `name == "shipping"` then you would set the shipping
additional cost by including an `additionalCosts.shipping` property in
your request payload.
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.
description:
type: string
description: A description of this additional cost.
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications that are subscribed to this
additional cost
items:
type: integer
type:
type: string
enum:
- session
- item
- both
description: |
The type of additional cost. The following options can be chosen:
- `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 display name for this event type. Use a short,
past-tense, description of the event.
name:
type: string
minLength: 1
description: >-
The machine-friendly canonical name for this event type. This will be
used in URLs, and cannot be changed after an event type has been
created.
description:
type: string
description: >
An explanation of when the event type is triggered. Write this with a
campaign manager in mind. For example:
> The "Payment Accepted" event is triggered after successful
processing of a payment by our payment gateway.
additionalProperties: false
EventType:
type: object
description: ''
required:
- id
- created
- title
- name
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
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
title:
type: string
minLength: 1
description: >-
The human-friendly display name for this event type. Use a short,
past-tense, description of the event.
name:
type: string
minLength: 1
description: >-
The machine-friendly canonical name for this event type. This will be
used in URLs, and cannot be changed after an event type has been
created.
description:
type: string
description: >
An explanation of when the event type is triggered. Write this with a
campaign manager in mind. For example:
> The "Payment Accepted" event is triggered after successful
processing of a payment by our payment gateway.
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: Friendly title for this webhook
verb:
type: string
enum:
- POST
- PUT
- GET
- DELETE
- PATCH
description: API method for this webhook
url:
type: string
description: API url (supports templating using parameters) for this webhook
headers:
type: array
description: List of API HTTP headers for this webhook
items:
type: string
pattern: '^([^:,]*):([^]*|[^,]*)$'
payload:
type: string
description: API payload (supports templating using parameters) for this webhook
params:
type: array
description: Array of template argument definitions
items:
$ref: '#/definitions/TemplateArgDef'
enabled:
type: boolean
description: Enables or disables webhook from showing in rule builder
additionalProperties: false
Webhook:
type: object
description: ''
required:
- id
- created
- modified
- applicationIds
- title
- verb
- url
- headers
- params
- enabled
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
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The exact moment 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: Friendly title for this webhook
verb:
type: string
enum:
- POST
- PUT
- GET
- DELETE
- PATCH
description: API method for this webhook
url:
type: string
description: API url (supports templating using parameters) for this webhook
headers:
type: array
description: List of API HTTP headers for this webhook
items:
type: string
pattern: '^([^:,]*):([^]*|[^,]*)$'
payload:
type: string
description: API payload (supports templating using parameters) for this webhook
params:
type: array
description: Array of template argument definitions
items:
$ref: '#/definitions/TemplateArgDef'
enabled:
type: boolean
description: Enables or disables webhook from showing in rule builder
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: mPTravel
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
- upserted
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
created:
type: string
format: date-time
description: The exact moment 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: mPTravel
integrationId:
type: string
minLength: 1
maxLength: 1000
description: The ID of this audience in the third-party integration.
example: 382370BKDB946
upserted:
type: boolean
description: >-
Indicates whether the audience is new or updated in the database after
this request.
additionalProperties: false
NewAudience:
type: object
required:
- name
properties:
name:
type: string
minLength: 1
description: The human-friendly display name for this audience.
example: Travel audience
integration:
type: string
description: >
The Talon.One-supported 3rd-party platform 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
UpdateAudience:
type: object
required:
- name
properties:
name:
type: string
minLength: 1
description: The human-friendly display name for this audience.
example: mPTravel
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: >-
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
created:
type: string
format: date-time
description: The exact moment 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
integration:
type: string
description: >
The Talon.One-supported 3rd-party platform 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
additionalProperties: false
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: >-
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
created:
type: string
format: date-time
description: The exact moment 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 account that owns this entity.
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: >-
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
created:
type: string
format: date-time
description: The exact moment 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 account that owns this entity.
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
Role:
type: object
description: ''
required:
- id
- created
- modified
- accountId
- name
- acl
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
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The exact moment 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/managing-campaign-groups/)
this role was created for.
name:
type: string
description: Name of the role
description:
type: string
description: Description of the role
members:
type: array
items:
type: integer
description: A list of user identifiers assigned to this role
acl:
type: object
format: aclRole
description: Role ACL Policy
additionalProperties: false
NewRole:
type: object
description: ''
required:
- name
- acl
- members
properties:
name:
type: string
description: Name of the role
description:
type: string
description: Description of the role
acl:
type: string
description: Role Policy this should be a stringified blob of json
members:
type: array
items:
type: integer
description: An array of user identifiers
additionalProperties: false
UpdateRole:
type: object
properties:
name:
type: string
description: Name of the role
description:
type: string
description: Description of the role
acl:
type: string
description: Role Policy this should be a stringified blob of json
members:
type: array
items:
type: integer
description: An array of user identifiers
RoleAssign:
type: object
description: ''
required:
- users
- roles
properties:
users:
type: array
items:
type: integer
description: An array of userIDs
roles:
type: array
items:
type: integer
description: An array of roleIDs
additionalProperties: false
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:
- ty238-32fke9
- 3gy32-008ye9
items:
type: string
LedgerEntry:
type: object
description: ''
required:
- id
- created
- eventId
- accountId
- profileId
- loyaltyProgramId
- amount
- reason
- expiryDate
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
created:
type: string
format: date-time
description: The exact moment 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
amount:
type: integer
description: Amount of loyalty points
example: 100
reason:
type: string
description: reason for awarding/deducting points
expiryDate:
type: string
format: date-time
description: Expiry date of the points
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
- CouponLimitReached
- CampaignLimitReached
- ProfileLimitReached
- CouponRecipientDoesNotMatch
- CouponExpired
- CouponStartDateInFuture
- CouponRejectedByCondition
- EffectCouldNotBeApplied
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
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
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
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
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
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.
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: >-
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
created:
type: string
format: date-time
description: The exact moment 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.
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.
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
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
example: rejectCoupon
triggeredByCoupon:
type: integer
example: 4928
description: >-
The ID of the coupon that was being evaluated when this effect 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
example: rejectCoupon
triggeredByCoupon:
type: integer
example: 4928
description: >-
The ID of the coupon that was being evaluated when this effect was
triggered
EffectProps:
type: object
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: >-
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: >
Only used when [cart item
flattening](https://docs.talon.one/docs/product/campaigns/campaign-evaluation/#flattened-cart-items)
is enabled.
Indicates which item the discount applies to for cart items with
`quantity` > 1.
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 binding
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: >
Only used when [cart item
flattening](https://docs.talon.one/docs/product/campaigns/campaign-evaluation/#flattened-cart-items)
is enabled.
Indicates which item the discount applies to for cart items with
`quantity` > 1.
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.
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.
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: >
The sub position is triggered when application flattening is enabled.
It indicates to which item the loyalty points addition applies, for
cart items with `quantity` > 1.
cardIdentifier:
type: string
description: The card on which these points were added.
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:
type: string
description: The card on which these points were added.
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. Value can be any of the following
types (time, string, number, location, boolean) or a 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: >
The index of the item unit in its line item. It is only used for cart
items with `quantity` > 1 and is
only returned when cart item flattening is enabled.
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:
- name
- 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
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: >
The sub-position is returned when [cart item
flattening](https://docs.talon.one/docs/product/campaigns/campaign-evaluation/#flattened-cart-items)
is enabled.
It indicates to which item the loyalty points were rolled back, for
cart items with `quantity` > 1.
cardIdentifier:
type: string
description: The card on which these points were originally added.
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:
- name
- 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
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:
type: string
description: The card on which these points were added.
ShowBundleMetadataEffectProps:
type: object
description: >-
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.
poolName:
type: string
description: The name of the giveaways pool the code was taken from.
recipientIntegrationId:
type: string
maxLength: 1000
description: The integration ID of the profile that was awarded the giveaway.
giveawayId:
type: integer
description: The internal ID for the giveaway that was awarded.
code:
type: string
description: The giveaway code that was awarded.
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.
poolName:
type: string
description: The name of the giveaways pool the code will be taken from.
recipientIntegrationId:
type: string
maxLength: 1000
description: The integration ID of the profile that will be awarded the giveaway.
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
name:
type: string
description: The type of the custom effect.
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: >
Optional list of extra data that you want to get in the response. Use
this property to get as much data
as you need in one request instead of sending extra requests to other
endpoints.
**Note:** `ruleFailureReasons` is always part of the response when the
[Application
type](https://docs.talon.one/docs/product/applications/overview#application-types)
is `sandbox`.
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: >
Optional list of extra data that you want to get in the response. Use
this property to get as much data
as you need in one request instead of sending extra requests to other
endpoints.
**Note:** `ruleFailureReasons` is always part of the response when the
[Application
type](https://docs.talon.one/docs/product/applications/overview#application-types)
is `sandbox`..
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
audiencesChanges:
type: object
description: Audiences memberships changes for this profile
$ref: '#/definitions/ProfileAudiencesChanges'
responseContent:
type: array
description: >
Optional list of extra data that you want to get in the response. Use
this property to get as much data
as you need in one request instead of sending extra requests to other
endpoints.
**Note:** `ruleFailureReasons` is always part of the response when the
[Application
type](https://docs.talon.one/docs/product/applications/overview#application-types)
is `sandbox`.
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.
deletes:
title: Audiences to leave
type: array
items:
type: integer
description: The IDs of the audiences for the customer to leave.
AudienceMembership:
type: object
required:
- id
- name
properties:
id:
type: integer
title: Audience ID
description: The ID of the audience belonging to this entity.
name:
type: string
title: Audience Name
description: The Name of the audience belonging to this entity.
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](/integration-api/#operation/updateCustomerSessionV2).
type: string
example: R195412
maxLength: 1000
additionalProperties: false
MultipleCustomerProfileIntegrationResponseV2:
type: object
properties:
integrationStates:
type: array
items:
$ref: '#/definitions/IntegrationStateV2'
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
FeedNotification:
type: object
description: A feed notification for CAMA users
required:
- title
- created
- updated
- articleUrl
- body
- type
properties:
title:
type: string
description: Title of the feed notification
created:
type: string
format: date-time
description: Timestamp of the moment this feed notification was created
updated:
type: string
format: date-time
description: Timestamp of the moment this feed notification was last updated
articleUrl:
type: string
description: URL to the feed notification in the help center
type:
type: string
enum:
- feed
- feature
- announcement
- alert
- test
description: The type of the feed notification
body:
type: string
description: Body of the feed notification
UserFeedNotifications:
type: object
description: notifications to notify CAMA user about
required:
- lastUpdate
- notifications
properties:
lastUpdate:
type: string
format: date-time
description: Timestamp of the last request for this list
notifications:
type: array
description: List of all notifications to notify the user about
items:
$ref: '#/definitions/FeedNotification'
UpdateUserLatestFeedTimestamp:
type: object
description: Updates current user's latest seen notifications timestamp
required:
- newLatestFeedTimestamp
properties:
newLatestFeedTimestamp:
type: string
format: date-time
description: New timestamp to update for the current user
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: >-
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
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
code:
type: string
description: The code value of this giveaway.
poolId:
type: integer
description: The ID of the pool to return giveaway codes from.
startDate:
format: date-time
description: Timestamp at which point the giveaway becomes valid.
type: string
endDate:
format: date-time
description: Timestamp at which point the giveaway becomes invalid.
type: string
attributes:
type: object
description: Arbitrary properties associated with this giveaway.
additionalProperties: true
used:
type: boolean
description: Indicates whether this giveaway code was given before.
importId:
type: integer
description: The ID of the Import which created this giveaway.
additionalProperties: false
NewGiveawaysPool:
type: object
required:
- name
properties:
name:
type: string
description: The name of this giveaways pool.
description:
type: string
description: The description of this giveaways pool.
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications that this giveaways pool is
enabled for
items:
type: integer
GiveawaysPool:
type: object
description: ''
required:
- id
- created
- accountId
- name
- createdBy
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
created:
type: string
format: date-time
description: The exact moment 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.
description:
type: string
description: The description of this giveaways pool.
subscribedApplicationsIds:
type: array
description: >-
A list of the IDs of the applications that this giveaways pool is
enabled for
items:
type: integer
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
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
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
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: >-
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
created:
type: string
format: date-time
description: The exact moment 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 exact moment 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
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.
createdBy:
type: integer
description: ID of the user who created this effect.
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: >-
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
created:
type: string
format: date-time
description: The exact moment 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 exact moment 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: >-
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
created:
type: string
format: date-time
description: The exact moment 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 exact moment 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: >-
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
created:
type: string
format: date-time
description: The exact moment 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 exact moment 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: >-
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
created:
type: string
format: date-time
description: The exact moment 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 exact moment 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 amount of discounts that can be given with this coupon code.
startDate:
type: string
format: date-time
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
minimum: 0
description: >-
Expiry 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. Must be
between 20,001 and 5,000,000.
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: >-
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
created:
type: string
format: date-time
description: The exact moment 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 amount of discounts that can be given with this coupon code.
startDate:
type: string
format: date-time
minimum: 0
description: Timestamp at which point the coupon becomes valid.
expiryDate:
type: string
format: date-time
minimum: 0
description: >-
Expiry 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. Must be
between 20,001 and 5,000,000.
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. The value should be either
'pending', 'completed', 'failed' or '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.
profileIntegrationId:
type: string
maxLength: 1000
description: The profile integration ID for which this limit counter is used.
couponId:
type: integer
description: The coupon ID for which this limit counter is used.
couponValue:
type: string
description: The coupon value for which this limit counter is used.
referralId:
type: integer
description: The referral ID for which this limit counter is used.
referralValue:
type: string
description: The referral value for which this limit counter is used.
identifier:
type: integer
description: The arbitrary identifier for which this limit counter is used.
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
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
BulkApplicationNotification:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
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_priorities_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/Campaign'
oldState:
type: string
description: >
The campaign's old state. Can be one of the following: ['running',
'disabled', 'scheduled', 'expired', 'draft', 'archived']
newState:
type: string
description: >
The campaign's new state. Can be one of the following: ['running',
'disabled', 'scheduled', 'expired', 'draft', 'archived']
CampaignRulesetChangedNotification:
type: object
required:
- campaign
- ruleset
description: A notification regarding a campaign whose ruleset was changed.
properties:
campaign:
type: object
description: The current version of the campaign.
$ref: '#/definitions/Campaign'
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 current version of the campaign.
$ref: '#/definitions/Campaign'
oldCampaign:
type: object
description: The campaign before it was edited.
$ref: '#/definitions/Campaign'
CampaignCreatedNotification:
type: object
description: A notification regarding a campaign that was created.
required:
- campaign
properties:
campaign:
type: object
description: The newly created campaign.
$ref: '#/definitions/Campaign'
CampaignDeletedNotification:
type: object
description: A notification regarding a campaign that was deleted.
required:
- campaign
properties:
campaign:
type: object
description: The deleted campaign.
$ref: '#/definitions/Campaign'
CampaignPrioritiesChangedNotification:
type: object
description: Notification about an Application whose campaigns' priorities changed.
required:
- application
- priorities
properties:
application:
type: object
description: Application containing the campaigns whose priorities changed.
$ref: '#/definitions/Application'
oldPriorities:
type: object
description: Previous campaign priorities
$ref: '#/definitions/CampaignPriorities'
priorities:
type: object
description: New campaign priorities
$ref: '#/definitions/CampaignPriorities'
CampaignPriorities:
type: object
description: >
Campaign IDs for each priority. The priority can be one of: ['universal',
'stackable', 'exclusive']
additionalProperties:
type: array
items:
type: integer
NewNotificationWebhook:
type: object
required:
- url
- headers
properties:
url:
type: string
description: API url for this notification webhook
headers:
type: array
description: List of API HTTP headers for this notification webhook
items:
type: string
pattern: '^[^:,]+:[^,]*$'
NotificationWebhook:
type: object
description: ''
required:
- id
- created
- modified
- applicationId
- url
- headers
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
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
modified:
type: string
format: date-time
description: The exact moment this entity was last modified.
example: '2021-09-12T10:12:42Z'
applicationId:
type: integer
description: The ID of the application that owns this entity.
example: 322
url:
type: string
description: API url for this notification webhook
headers:
type: array
description: List of API HTTP headers for this notification webhook
items:
type: string
pattern: '^[^:,]+:[^,]*$'
additionalProperties: false
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: >-
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
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
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. It is only available when [cart item
flattening](https://docs.talon.one/docs/product/campaigns/campaign-evaluation/#flattened-cart-items)
is enabled. If cart item flattening is disabled, the cart item can
only be returned in its entirety.
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
type:
type: string
title: Event Type
description: A string representing the event. Must not be a reserved event name.
minLength: 1
example: email_opened
attributes:
type: object
description: Arbitrary additional JSON data associated with the event.
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
type:
type: string
title: Event Type
description: A string representing the event. Must not be a reserved event name.
minLength: 1
example: email_opened
attributes:
type: object
description: Arbitrary additional JSON data associated with the event.
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: >-
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
created:
type: string
format: date-time
description: The exact moment 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 exact moment 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
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
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
- attributes
properties:
sku:
type: string
description: The unique SKU of the item to patch.
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.
required:
- attributes
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 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: >-
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
created:
type: string
format: date-time
description: The exact moment this entity was created.
example: '2020-06-10T09:05:27.993483Z'
sku:
type: string
description: The stock keeping unit of the item.
example: SKU1241028
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.
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