Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Management Analytics API
version: ''
description: 'The Management API allows you to programmatically do what the Campaign Manager
does.'
servers:
- url: https://yourbaseurl.talon.one
security:
- manager_auth: []
- management_key: []
tags:
- name: Analytics
description: Represents analytics used to retrieve statistical data about the performance of campaigns within an Application.
paths:
/v1/applications/{applicationId}/export_effects:
get:
operationId: exportEffects
summary: Export triggered effects
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.
Download a CSV file containing the triggered effects that match the given
attributes.
> [!tip] If the exported CSV file is too large to view, you can
> split it into multiple files.
The generated file can contain the following columns:
- `applicationid`: The ID of the Application.
- `campaignid`: The ID of the campaign.
- `couponid`: The ID of the coupon, when applicable to the effect.
- `created`: The timestamp of the effect.
- `event_type`: The name of the event. See the docs.
- `eventid`: The internal ID of the effect.
- `name`: The effect name. See the docs.
- `profileintegrationid`: The ID of the customer profile, when applicable.
- `props`: The properties of the effect.
- `ruleindex`: The index of the rule.
- `rulesetid`: The ID of the rule set.
- `sessionid`: The internal ID of the session that triggered the effect.
- `profileid`: The internal ID of the customer profile.
- `sessionintegrationid`: The integration ID of the session.
- `total_revenue`: The total revenue.
- `store_integration_id`: The integration ID of the store. You choose this ID when you create a store.'
tags:
- Analytics
parameters:
- $ref: '#/components/parameters/applicationId'
- name: campaignId
in: query
description: Filter results by campaign ID.
example: 49
schema:
type: number
- name: createdBefore
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string. 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. 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: dateFormat
in: query
description: Determines the format of dates in the export document.
example: excel
required: false
schema:
type: string
enum:
- excel
- ISO8601
responses:
'200':
description: OK
content:
application/csv:
schema:
type: string
format: csv
examples:
response:
value: 'created,name,applicationid,campaignid,rulesetid,ruleindex,sessionintegrationid,profileintegrationid,sessionid,profileid,eventid,event_type,total_revenue,props,couponid,store_id,store_integration_id
2021-06-02T21:14:16Z,rejectCoupon,270,0,0,0,newsession1,,9168,0,95797,talon_session_created,265.00,"{""value"": ""XMAS20"", ""rejectionReason"": ""CouponNotFound""}",,115,STORE-001
2021-09-01T13:04:04Z,setDiscountPerItem,270,3882,13599,0,test_flattening_2,integid_4,9707,4800,98806,talon_session_updated,405.00,"{""name"": ""10% off per item#1"", ""value"": 11.0, ""position"": 1}",,116,STORE-002
'
/v1/applications/{applicationId}/export_customer_sessions:
get:
operationId: exportCustomerSessions
summary: Export customer sessions
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.
Download a CSV file containing the customer sessions that match the request.
> [!important] Archived sessions cannot be exported. See the retention
> policy.
> [!tip] If the exported CSV file is too large to view, you can
> split it into multiple files.
- `id`: The internal ID of the session.
- `firstsession`: Whether this is a first session.
- `integrationid`: The integration ID of the session.
- `applicationid`: The ID of the Application.
- `profileid`: The internal ID of the customer profile.
- `profileintegrationid`: The integration ID of the customer profile.
- `created`: The timestamp when the session was created.
- `state`: The state
of the session.
- `cartitems`: The cart items in the session.
- `discounts`: The discounts in the session.
- `total`: The total value of cart items and additional costs in the session, before any discounts are applied.
- `attributes`: The attributes set in the session.
- `closedat`: Timestamp when the session was closed.
- `cancelledat`: Timestamp when the session was cancelled.
- `referral`: The referral code in the session.
- `identifiers`: The identifiers in the session.
- `additional_costs`: The additional costs
in the session.
- `updated`: Timestamp of the last session update.
- `store_integration_id`: The integration ID of the store.
- `coupons`: Coupon codes in the session.'
tags:
- Analytics
parameters:
- $ref: '#/components/parameters/applicationId'
- name: createdBefore
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string.
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.
required: false
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: updatedBefore
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string.
required: false
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: updatedAfter
in: query
description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string.
required: false
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
- name: profileIntegrationId
in: query
description: Only return sessions for the customer that matches this customer integration ID.
example: customer1
required: false
schema:
type: string
- name: dateFormat
in: query
description: Determines the format of dates in the export document.
example: excel
required: false
schema:
type: string
enum:
- excel
- ISO8601
- name: customerSessionState
in: query
description: Filter results by state.
example: open
required: false
schema:
type: string
enum:
- open
- closed
- partially_returned
- cancelled
responses:
'200':
description: OK
content:
application/csv:
schema:
type: string
format: csv
examples:
response:
value: 'id,firstsession,integrationid,applicationid,profileid,profileintegrationid,created,state,cartitems,discounts,total,attributes,closedat,cancelledat,referral,identifiers,additional_costs,updated,store_integration_id,coupons
12328,true,62791173fbf323ee5cfd96f3,270,6111,dxclwds,2022-05-09T13:05:31Z,open,"[{""sku"": ""B00004TKVY"", ""name"": ""Gravel bike - \""Aisle of Man\"""", ""price"": 1800, ""weight"": 6, ""category"": ""gravelbikes"", ""position"": 0, ""quantity"": 1, ""attributes"": {""color"": [""black,white""], ""material"": ""titanium""}, ""returnedQuantity"": 0, ""remainingQuantity"": 1}]","{}",1850.00,"{""ShippingCost"": 50, ""PaymentMethod"": ""creditcard"", ""ShippingMethod"": ""Standard""}",0001-01-01T00:00:00Z,0001-01-01T00:00:00Z,,"null","{""ShippingCost"": {""price"": 50}}",2022-05-09T13:13:28Z,"STORE-001","[""SORRY5QMUJRWA""]"
'
components:
parameters:
applicationId:
name: applicationId
in: path
required: true
description: The ID of the Application. It is displayed in your Talon.One deployment URL.
example: 42
schema:
type: integer
securitySchemes:
manager_auth:
type: apiKey
name: Authorization
in: header
description: 'This authentication scheme relies on a bearer token that you can use to
access all the endpoints of the Management API.
To create the token:
1. Get a bearer token by calling the
[createSession](#tag/Sessions/operation/createSession) endpoint.
1. Use the `token` property of the response in the HTTP header of your
next queries: `Authorization: Bearer $TOKEN`.
A token is valid for 3 months. In accordance with best pratices, use
your generated token for all your API requests. Do **not** regenerate a token for each
request.
> [!note]
> We recommend that you use a [Management API key](https://docs.talon.one/management-api#section/Authentication/management_key)
> instead of a bearer token.
'
management_key:
type: apiKey
name: Authorization
in: header
description: "The API key authentication gives you access to the endpoints selected by\nthe admin who created the key.\n\nUsing an API key is the recommended authentication method.\n\nThe key must be generated by an admin and given to the developer that\nrequires it:\n\n1. Sign in to the Campaign Manager and click **Account** > **Tools** >\n**Management API Keys**.\n1. Click **Create Key** and give it a name.\n1. Set an expiration date.\n **Tip**: Avoid choosing expiration dates that fall at the end of the year or during other high-traffic periods.\n1. Choose the endpoints the key should give access to.\n1. Click **Create Key**.\n1. Share it with your developer.\n\nThe developer can now use the API key in the HTTP header, prefixing it\nwith `ManagementKey-v1`:\n\n```\nAuthorization: ManagementKey-v1 bd9479c59e16f9dbc644d33aa74d58270fe13bf3\n```\n"