Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Talon One Campaigns API
version: ''
description: 'Operations tagged Campaigns across 2 of this provider''s published API definitions: talon-one-integration-api-openapi.yml, talon-one-management-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://yourbaseurl.talon.one
tags:
- name: Campaigns
description: 'Represents the primary resource used to control the behavior of the Talon.One Rule Engine.
They combine rulesets, coupons, and limits into a single unit.
See the [docs](https://docs.talon.one/docs/product/campaigns/overview).
'
paths:
/v1/integration/campaigns:
get:
operationId: integrationGetAllCampaigns
summary: List all running campaigns
description: "Retrieve all running campaigns for the specified Application. You\ncan filter the results by providing specific campaign IDs or a range of \nstart and end dates.\n"
security:
- api_key_v1: []
tags:
- Campaigns
parameters:
- name: pageSize
in: query
required: false
description: The number of items in the response.
example: 50
schema:
type: integer
minimum: 1
maximum: 1000
default: 50
- $ref: '#/components/parameters/skip'
- name: campaignIds
in: query
required: false
description: 'Filter by one or more campaign IDs, separated by a comma.
**Note:** If no campaigns are specified, data for all the campaigns in
the Application is returned.
'
example:
- '11'
- '20'
style: form
explode: false
schema:
type: array
items:
type: string
- name: startAfter
in: query
description: "Filter results to only include campaigns that start on or after \nthe specified timestamp.\n\n**Note:**\n\n- It must be an RFC3339 timestamp string.\n\n- You can include a time component in your string, for example,\n`T23:59:59` to specify the end of the day. The time zone setting\nconsidered is `UTC`. If you do not include a time component, a default\ntime value of `T00:00:00` (midnight) in `UTC` is considered.\n"
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: startBefore
in: query
description: "Filter results to only include campaigns that start on or before \nthe specified timestamp.\n\n**Note:**\n\n- It must be an RFC3339 timestamp string.\n\n- You can include a time component in your string, for example,\n`T23:59:59` to specify the end of the day. The time zone setting\nconsidered is `UTC`. If you do not include a time component, a default\ntime value of `T00:00:00` (midnight) in `UTC` is considered.\n"
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: endAfter
in: query
description: "Filter results to only include campaigns that end on or after \nthe specified timestamp.\n\n**Note:**\n\n- It must be an RFC3339 timestamp string.\n\n- You can include a time component in your string, for example,\n`T23:59:59` to specify the end of the day. The time zone setting\nconsidered is `UTC`. If you do not include a time component, a default\ntime value of `T00:00:00` (midnight) in `UTC` is considered.\n"
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: endBefore
in: query
description: "Filter results to only include campaigns that end on or before \nthe specified timestamp.\n\n**Note:**\n\n- It must be an RFC3339 timestamp string.\n\n- You can include a time component in your string, for example,\n`T23:59:59` to specify the end of the day. The time zone setting\nconsidered is `UTC`. If you do not include a time component, a default\ntime value of `T00:00:00` (midnight) in `UTC` is considered.\n"
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: storeId
in: query
required: false
description: Filter results to campaigns linked to the specified store ID.
example: 23
schema:
type: integer
- name: audienceId
in: query
required: false
description: Filter results to campaigns linked to the specified audience ID.
example: 7
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- hasMore
- data
properties:
hasMore:
type: boolean
data:
type: array
items:
$ref: '#/components/schemas/IntegrationCampaign'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
servers:
- url: https://yourbaseurl.talon.one
/v1/applications/{applicationId}/campaigns:
get:
operationId: getCampaigns
summary: List campaigns
description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
List the campaigns of the specified application that match your filter criteria.
'
tags:
- Campaigns
parameters:
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/sort'
- $ref: '#/components/parameters/applicationId'
- name: campaignState
in: query
description: 'Filter results by the state of the campaign.
- `enabled`: Campaigns that are scheduled, running (activated), or expired.
- `running`: Campaigns that are running (activated).
- `disabled`: Campaigns that are disabled.
- `expired`: Campaigns that are expired.
- `archived`: Campaigns that are archived.
'
example: enabled
required: false
schema:
type: string
enum:
- enabled
- disabled
- archived
- scheduled
- running
- expired
- staged
- name: name
in: query
description: Filter results performing case-insensitive matching against the name of the campaign.
example: campaign1
required: false
schema:
type: string
- name: tags
in: query
description: 'Filter results performing case-insensitive matching against the tags of the campaign.
'
example:
- tag1
- tag2
required: false
schema:
type: array
items:
type: string
- name: createdBefore
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
required: false
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: createdAfter
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
required: false
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: startBefore
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign start time timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
required: false
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: startAfter
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign start time timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
required: false
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: endBefore
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign end time timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
required: false
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: endAfter
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign end time timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
required: false
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: campaignGroupId
in: query
description: Filter results to campaigns owned by the specified campaign access group ID.
example: 12
required: false
schema:
type: integer
- name: templateId
in: query
description: The ID of the campaign template this campaign was created from.
example: 18
schema:
type: integer
- name: storeId
in: query
description: Filter results to campaigns linked to the specified store ID.
example: 23
required: false
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/components/schemas/Campaign'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
security:
- manager_auth: []
- management_key: []
servers:
- url: https://yourbaseurl.talon.one
/v1/applications/{applicationId}/campaigns/{campaignId}:
get:
operationId: getCampaign
summary: Get campaign
description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Retrieve the given campaign.'
tags:
- Campaigns
parameters:
- $ref: '#/components/parameters/applicationId'
- $ref: '#/components/parameters/campaignId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
security:
- manager_auth: []
- management_key: []
put:
operationId: updateCampaign
summary: Update campaign
description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Update the given campaign.
> [!important] You cannot use this endpoint to update campaigns if [campaign staging and
> revisions](https://docs.talon.one/docs/product/applications/managing-general-settings#campaign-staging-and-revisions)
> is enabled for your Application.
'
tags:
- Campaigns
parameters:
- $ref: '#/components/parameters/applicationId'
- $ref: '#/components/parameters/campaignId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCampaign'
description: body
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
security:
- manager_auth: []
- management_key: []
delete:
operationId: deleteCampaign
summary: Delete campaign
description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Delete the given campaign.'
tags:
- Campaigns
parameters:
- $ref: '#/components/parameters/applicationId'
- $ref: '#/components/parameters/campaignId'
responses:
'204':
description: No Content
security:
- manager_auth: []
- management_key: []
servers:
- url: https://yourbaseurl.talon.one
/v1/applications/{applicationId}/campaigns/{campaignId}/copy:
post:
operationId: copyCampaignToApplications
summary: Copy the campaign into the specified Application
description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Copy the campaign into all specified Applications.'
tags:
- Campaigns
parameters:
- $ref: '#/components/parameters/applicationId'
- $ref: '#/components/parameters/campaignId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignCopy'
description: body
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/components/schemas/Campaign'
security:
- manager_auth: []
- management_key: []
servers:
- url: https://yourbaseurl.talon.one
/v1/applications/{applicationId}/campaigns_search:
post:
operationId: getCampaignByAttributes
summary: List campaigns that match the given attributes
description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Get a list of all the campaigns that match a set of attributes.
'
tags:
- Campaigns
parameters:
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/sort'
- $ref: '#/components/parameters/applicationId'
- name: campaignState
in: query
description: 'Filter results by the state of the campaign.
- `enabled`: Campaigns that are scheduled, running (activated), or expired.
- `running`: Campaigns that are running (activated).
- `disabled`: Campaigns that are disabled.
- `expired`: Campaigns that are expired.
- `archived`: Campaigns that are archived.
'
example: enabled
required: false
schema:
type: string
enum:
- enabled
- disabled
- archived
- scheduled
- running
- expired
- staged
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignSearch'
description: body
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/components/schemas/Campaign'
security:
- manager_auth: []
- management_key: []
servers:
- url: https://yourbaseurl.talon.one
/v1/applications/{applicationId}/campaigns/{campaignId}/rulesets:
get:
operationId: getRulesets
summary: List campaign rulesets
description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
List all rulesets of this campaign. A ruleset is a revision of the rules of a campaign.
**Important:** The response also includes deleted rules.
You should only consider the latest revision of the returned rulesets.
'
tags:
- Campaigns
parameters:
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/sort'
- $ref: '#/components/parameters/applicationId'
- $ref: '#/components/parameters/campaignId'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/components/schemas/Ruleset'
security:
- manager_auth: []
- management_key: []
servers:
- url: https://yourbaseurl.talon.one
/v1/applications/{applicationId}/campaigns/{campaignId}/rulesets/{rulesetId}:
get:
operationId: getRuleset
summary: Get ruleset
description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Retrieve the specified ruleset.'
tags:
- Campaigns
parameters:
- $ref: '#/components/parameters/applicationId'
- $ref: '#/components/parameters/campaignId'
- name: rulesetId
in: path
description: The ID of the ruleset.
example: 29
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Ruleset'
security:
- manager_auth: []
- management_key: []
servers:
- url: https://yourbaseurl.talon.one
/v2/applications/{applicationId}/campaigns/{campaignId}/rulesets/{rulesetId}:
get:
operationId: getRulesetV2
summary: Get ruleset (V2)
description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Retrieve the specified ruleset as a JSON object.'
tags:
- Campaigns
x-scalar-stability: experimental
parameters:
- $ref: '#/components/parameters/applicationId'
- $ref: '#/components/parameters/campaignId'
- name: rulesetId
in: path
description: The ID of the ruleset.
example: 29
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RulesetV2'
security:
- manager_auth: []
- management_key: []
servers:
- url: https://yourbaseurl.talon.one
/v1/applications/{applicationId}/campaigns/{campaignId}/analytics:
get:
operationId: getCampaignAnalytics
summary: Get analytics of campaigns
description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Retrieve statistical data about the performance of the given campaign.'
tags:
- Campaigns
parameters:
- $ref: '#/components/parameters/applicationId'
- $ref: '#/components/parameters/campaignId'
- name: rangeStart
in: query
required: true
description: 'Only return results from after this timestamp.
> [!note] **Note**
> - This must be an RFC3339 timestamp string.
> - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting
> considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered.
'
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: rangeEnd
in: query
required: true
description: 'Only return results from before this timestamp.
> [!note] **Note**
> - This must be an RFC3339 timestamp string.
> - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting
> considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered.
'
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: granularity
in: query
description: The time interval between the results in the returned time-series.
example: 1 hour
schema:
type: string
enum:
- 1 hour
- 1 day
- 1 week
- 1 month
- 1 year
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- totalResultSize
- data
properties:
totalResultSize:
type: integer
example: 1
data:
type: array
items:
$ref: '#/components/schemas/CampaignAnalytics'
security:
- manager_auth: []
- management_key: []
servers:
- url: https://yourbaseurl.talon.one
/v1/applications/{applicationId}/campaign_analytics/export:
get:
operationId: exportApplicationCampaignAnalytics
summary: Export Application analytics aggregated by campaign
description: "> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.\n\nDownload a CSV file containing analytics data aggregated by campaign for the\ncampaigns of an Application.\n\n> [!tip] If the exported CSV file is too large to view, you can\n> [split it into multiple files](https://www.google.com/search?q=split+CSV+into+multiple+files).\n\nThe CSV file contains the following columns:\n\n- `campaign_id`: The ID of the campaign. This column also contains labels\n for the [total and influenced values](https://docs.talon.one/docs/product/campaigns/analytics/application-dashboard#display-the-analytics-data).\n- `start_date`: The start of the aggregation time frame in UTC.\n- `end_date`: The end of the aggregation time frame in UTC.\n- `revenue`: The total, pre-discount value of all items purchased in a customer session.\n- `sessions`: The number of all closed sessions.\n- `average_session_value`: The average customer session value, calculated by dividing the revenue value by the number of sessions.\n- `average_items_per_session`: The number of items from sessions divided by the number of sessions.\n- `coupons`: The number of times a coupon was successfully redeemed in sessions.\n- `discounts`: The total value of discounts given for cart items in sessions.\n"
tags:
- Campaigns
parameters:
- $ref: '#/components/parameters/applicationId'
- name: campaignIds
in: query
required: false
description: 'Filter by one or more Campaign IDs, separated by a comma.
**Note:** If no campaigns are specified, data for all the campaigns in the Application is returned.
'
example:
- '11'
- '20'
style: form
explode: false
schema:
type: array
items:
type: string
- name: rangeStart
in: query
required: true
description: 'Only return results from after this timestamp.
> [!note] **Note**
> - This must be an RFC3339 timestamp string.
> - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting
> considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered.
'
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: rangeEnd
in: query
required: true
description: 'Only return results from before this timestamp.
> [!note] **Note**
> - This must be an RFC3339 timestamp string.
> - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting
> considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered.
'
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
responses:
'200':
description: OK
content:
application/csv:
schema:
type: string
format: csv
examples:
response:
value: 'campaign_id,start_date,end_date,revenue,sessions,average_session_value,average_items_per_session,coupons,discounts
Total,2025-02-01T00:00:00+00:00,2025-02-07T00:00:00+00:00,751916.88,5919,127.03,3.96,N/A,N/A
Influenced,2025-02-01T00:00:00+00:00,2025-02-07T00:00:00+00:00,525816.00,5246,100.23,4.46,374,47675.73
41,2025-02-01T00:00:00+00:00,2025-02-07T00:00:00+00:00,284089.80,3105,91.49,4.62,247,8435.65
75,2025-02-01T00:00:00+00:00,2025-02-07T00:00:00+00:00,416001.81,4771,87.19,4.52,0,16768.71
178,2025-02-01T00:00:00+00:00,2025-02-07T00:00:00+00:00,313390.53,1098,285.42,4.81,65,16097.05
195,2025-02-01T00:00:00+00:00,2025-02-07T00:00:00+00:00,34345.86,595,57.72,4.58,62,6374.32
'
security:
- manager_auth: []
- management_key: []
servers:
- url: https://yourbaseurl.talon.one
components:
schemas:
ErrorResponseWithStatus:
type: object
properties:
message:
type: string
errors:
type: array
description: An array of individual problems encountered during the request.
items:
$ref: '#/components/schemas/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: '#/components/schemas/ErrorSource'
RuleMetadata:
type: object
required:
- title
properties:
title:
type: string
description: A short description of the rule.
example: Give discount via coupon
displayName:
type: string
description: A customer-facing name for the rule.
example: 20% off all shoes!
displayDescription:
type: string
description: "A customer-facing description that explains the details of the rule. \n\nFor example, this property can contain details about eligibility requirements, reward timelines, or terms and conditions.\n"
example: Get a 20% discount on all shoes during Thanksgiving! Offer valid till Dec 5 only.
relatedData:
type: string
description: 'Any additional data associated with the rule, such as an image URL, vendor name, or a content management system (CMS) ID.
'
example: https://example.com/discounts/20-off-shoes.png
IntegrationCampaignBase:
allOf:
- $ref: '#/components/schemas/ApplicationEntity'
- type: object
required:
- id
- name
- state
- tags
- features
properties:
id:
type: integer
description: Unique ID of Campaign.
example: 4
name:
type: string
title: Campaign Name
description: The name of the campaign.
minLength: 1
example: Summer promotions
description:
type: string
title: Campaign Description
description: A detailed description of the campaign.
example: Campaign for all summer 2021 promotions
startTime:
type: string
format: date-time
description: Timestamp when the campaign will become active.
example: '2021-07-20T22:00:00Z'
endTime:
type: string
format: date-time
description: Timestamp when the campaign will become inactive.
example: '2021-09-22T22:00:00Z'
attributes:
type: object
description: Arbitrary properties associated with this campaign.
state:
type: string
enum:
- enabled
default: enabled
example: enabled
description: 'The state of the campaign.
'
tags:
type: array
description: A list of tags for the campaign.
example:
- summer
maxItems: 50
items:
type: string
minLength: 1
maxLength: 50
features:
type: array
description: The features enabled in this campaign.
example:
- coupons
- referrals
items:
type: string
enum:
- coupons
- referrals
- loyalty
- giveaways
- strikethrough
- achievements
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 pay
# --- truncated at 32 KB (143 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/talon-one/refs/heads/main/openapi/talon-one-campaigns-api-openapi.yml