openapi: 3.2.0 info: title: Management Stores API version: '' description: "The Management API allows you to programmatically do what the Campaign Manager\ndoes. Use this API for back-office operations such as campaign\nand coupon management, maintenance jobs, and bulk operations.\n\nFor more background information about this API, see\n[Management API overview](https://docs.talon.one/docs/dev/management-api/overview).\n\n> [!note] **Are you looking for a different API?**\n> - To integrate with Talon.One directly and send real-time data, see the [Integration API](https://docs.talon.one/integration-api).\n> - To integrate with Talon.One from a CEP or CDP platform, see the [Third-party API](https://docs.talon.one/third-party-api).\n\n## Authentication\n\nManagement API keys are scoped to a user account and become invalid if the user is\ndeactivated or removed from the organization. Use a dedicated service account to\ncreate keys for production integrations.\n\nFor details on generating and managing API keys, see\n[Manage Management API keys](https://docs.talon.one/docs/product/account/dev-tools/manage-mapi-keys).\n\n## Security\n\nConsider the following recommendations:\n- Store API keys securely via environment variables or by using a secret management system.\n- Only call this API from backend services.\n- Implement HTTPS for all communication with the API to ensure data privacy and security.\n- Create [user roles](https://docs.talon.one/docs/product/account/account-settings/manage-roles)\n reflecting your own company hierarchies.\n\n## Response codes and error handling\n\nTalon.One uses conventional HTTP response codes to indicate the success or failure of an API request.\nCodes in the `2xx` range indicate success. Codes in the `4xx` range indicate the request failed based\non the information provided. Codes in the `5xx` range indicate an error with Talon.One servers.\n\nError responses include a `message` that summarizes what went wrong. Use it for logging and debugging.\n\nWhen a request has one or more specific problems, the `errors` array lists each one separately:\n- `title` gives a short description of the problem\n- `source` shows where the error originated, for example, using a `pointer` property indicating the\n problematic property in the request body.\n\n| Code | Description | Action |\n|------|-------------|--------|\n| `2xx` | Success | None. |\n| `400` | Bad request | Fix the request (for example, a missing or invalid parameter). Not retryable. |\n| `401` | Unauthorized | Provide a valid API key. Not retryable. |\n| `404` | Not found | Check the resource path or ID. Not retryable. |\n| `409` | Conflict | If you are creating a resource, use a unique resource name/ID. Generally not retryable. |\n| `429` | Rate limit exceeded | Retry with exponential backoff. |\n| `5xx` | Server error | Retry with exponential backoff. |\n\n## URL encoding\n\nEncode all path and query parameter values that contain special characters. This applies to\ncustomer profile IDs, session IDs, coupon codes, and any other user-supplied string passed as\na URL segment or query parameter.\n\nFor example, encode a `10$OFF_NOW` coupon code as `10%24OFF_NOW` before\nincluding it in a request URL.\n\nRequests with unencoded special characters may be misrouted or return unexpected errors.\n\nFor more information, see [HTML URL Encoding Reference](https://www.w3schools.com/tags/ref_urlencode.asp).\n\n## MCP server (closed beta)\n\nTalon.One provides an MCP server that gives AI agents\nread-only access to your campaigns, customers, coupons, and loyalty programs,\nso they can answer questions about your campaigns and customers in plain language.\n\nAgents can explain campaign rule logic, check campaign status and budgets, analyze customer point\nbalances and tier status, and investigate failed API requests.\n\nTo connect, append `/v1/mcp/entrypoint` to your Talon.One deployment URL and authenticate with an MCP\nconnection API key generated in **Campaign Manager > Account > Tools > MCP Connections**.\n\nThe server is compatible with Claude Desktop, Claude Code, Cursor, Gemini CLI, ChatGPT CLI,\nCodex CLI, and other stdio-compatible MCP clients.\n\nFor more information, see [Talon.One MCP server](https://docs.talon.one/docs/dev/mcp).\n\n## Rate limiting\n\nThis API is **not** meant to be used in real-time integrations that directly serve your end users.\nIt supports a maximum of **3 requests per second** for each of these endpoints.\nFor real-time integrations use the [Integration API](https://docs.talon.one/integration-api).\n" servers: - url: https://yourbaseurl.talon.one security: - manager_auth: [] - management_key: [] tags: - name: Stores description: 'Represents physical or digital stores, branches, and franchises. ' paths: /v1/applications/{applicationId}/stores: get: operationId: listStores summary: List stores 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 stores for a specific Application.' tags: - Stores parameters: - $ref: '#/components/parameters/applicationId' - $ref: '#/components/parameters/pageSize' - $ref: '#/components/parameters/skip' - $ref: '#/components/parameters/sort' - name: withTotalResultSize in: query description: 'When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets. - When `true`: `totalResultSize` contains the total number of results for this query. - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page. ' example: false schema: type: boolean - name: campaignId in: query description: Filter results by campaign ID. example: 49 schema: type: number - name: name description: The name of the store. example: store1 required: false in: query schema: type: string - name: integrationId description: The integration ID of the store. example: storeId1 required: false in: query schema: type: string - name: query description: Filter results by `name` or `integrationId`. example: name required: false in: query schema: type: string responses: '200': description: OK content: application/json: schema: type: object required: - data properties: hasMore: type: boolean totalResultSize: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/Store' post: operationId: createStore summary: Create store 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. Create a new store in a specific Application.' tags: - Stores parameters: - $ref: '#/components/parameters/applicationId' requestBody: $ref: '#/components/requestBodies/NewStore' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Store' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict. A store with this integration ID already exists for this application. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/applications/{applicationId}/stores/{storeId}: get: operationId: getStore summary: Get store 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 store details for a specific store ID.' tags: - Stores parameters: - $ref: '#/components/parameters/applicationId' - name: storeId required: true in: path description: 'The ID of the store. You can get this ID with the [List stores](#tag/Stores/operation/listStores) endpoint. ' example: '17' schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Store' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' put: operationId: updateStore summary: Update store 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 store details for a specific store ID.' tags: - Stores parameters: - $ref: '#/components/parameters/applicationId' - name: storeId required: true in: path description: 'The ID of the store. You can get this ID with the [List stores](#tag/Stores/operation/listStores) endpoint. ' example: '17' schema: type: string requestBody: $ref: '#/components/requestBodies/NewStore' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Store' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' delete: operationId: deleteStore summary: Delete store 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 specified store.' tags: - Stores parameters: - $ref: '#/components/parameters/applicationId' - name: storeId required: true in: path description: 'The ID of the store. You can get this ID with the [List stores](#tag/Stores/operation/listStores) endpoint. ' example: '17' schema: type: string responses: '204': description: No Content '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/applications/{applicationId}/campaigns/{campaignId}/stores/export: get: operationId: exportCampaignStores summary: Export stores 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 stores linked to a specific campaign. > [!tip] If the exported CSV file is too large to view, you can > [split it into multiple files](https://www.google.com/search?q=split+CSV+into+multiple+files). The CSV file contains the following column: - `store_integration_id`: The identifier of the store. ' tags: - Stores parameters: - $ref: '#/components/parameters/applicationId' - $ref: '#/components/parameters/campaignId' responses: '200': description: OK content: application/csv: schema: type: string format: csv examples: response: value: 'store_integration_id STORE-001 STORE-002 STORE-003 ' '400': description: Bad request content: application/csv: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Invalid API key content: application/csv: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/csv: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/applications/{applicationId}/campaigns/{campaignId}/stores: delete: operationId: disconnectCampaignStores summary: Disconnect stores 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. Disconnect the stores linked to a specific campaign.' tags: - Stores parameters: - $ref: '#/components/parameters/applicationId' - $ref: '#/components/parameters/campaignId' responses: '204': description: No Content '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/applications/{applicationId}/campaigns/{campaignId}/stores/import: post: operationId: importCampaignStores summary: Import stores 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. Upload a CSV file containing the stores you want to link to a specific campaign. Send the file as multipart data. The CSV file **must** only contain the following column: - `store_integration_id`: The identifier of the store. The import **replaces** the previous list of stores linked to the campaign. ' tags: - Stores parameters: - $ref: '#/components/parameters/applicationId' - $ref: '#/components/parameters/campaignId' requestBody: required: true content: multipart/form-data: schema: type: object properties: upFile: description: The CSV file containing the data that is being imported. type: string format: binary responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Import' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' components: schemas: NewStore: allOf: - $ref: '#/components/schemas/UpdateStore' - type: object required: - integrationId properties: integrationId: type: string format: string example: STORE-001 maxLength: 1000 minLength: 1 description: 'The integration ID of the store. You choose this ID when you create a store. **Note**: You cannot edit the `integrationId` after the store has been created. ' Store: allOf: - $ref: '#/components/schemas/Entity' - $ref: '#/components/schemas/NewStore' - type: object required: - updated - applicationId - integrationId - created properties: created: type: string format: date-time description: The time this entity was created. example: '2020-02-07T08:15:22Z' applicationId: type: integer description: The ID of the Application that owns this entity. example: 322 updated: type: string format: date-time description: Timestamp of the most recent update on this entity. example: '2021-09-23T10:12:42Z' linkedCampaignIds: type: array description: A list of IDs of the campaigns that are linked with current store. items: type: integer example: - 4 - 6 - 8 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' 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: '#/components/schemas/APIError' AccountEntity: type: object required: - accountId properties: accountId: type: integer description: The ID of the account that owns this entity. example: 3886 Entity: type: object required: - id - created properties: id: type: integer description: The internal ID of this entity. example: 6 created: type: string format: date-time description: The time this entity was created. example: '2020-06-10T09:05:27.993483Z' UserEntity: type: object required: - userId properties: userId: type: integer description: The ID of the user associated with this entity. example: 388 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. UpdateStore: type: object required: - name - description properties: name: type: string description: The name of the store. example: South US store minLength: 1 maxLength: 200 description: type: string description: The description of the store. example: This is the description of the store in south US. attributes: type: object description: The attributes of the store. example: country: USA code: 1234 Import: allOf: - $ref: '#/components/schemas/Entity' - $ref: '#/components/schemas/AccountEntity' - $ref: '#/components/schemas/UserEntity' - type: object required: - amount - entity properties: 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. 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 sort: name: sort in: query required: false description: 'The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with `-`. **Note:** You may not be able to use all fields for sorting. This is due to performance limitations. ' example: name schema: type: string pageSize: name: pageSize in: query required: false description: The number of items in the response. example: 1000 schema: type: integer minimum: 1 maximum: 1000 default: 1000 campaignId: name: campaignId in: path description: The ID of the campaign. It is displayed in your Talon.One deployment URL. example: 18 required: true schema: type: integer skip: name: skip in: query required: false description: The number of items to skip when paging through large result sets. example: 100 schema: type: integer requestBodies: NewStore: content: application/json: schema: $ref: '#/components/schemas/NewStore' description: body required: true 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"