Talon.One Campaign templates API

openapi: 3.2.0
info:
  title: Management Campaign templates 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: Campaign templates
  description: 'Represents templates used to generate campaigns from.

    '
paths:
  /v1/campaign_templates:
    get:
      operationId: getCampaignTemplates
      summary: List campaign templates
      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 a list of campaign templates.'
      tags:
      - Campaign templates
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/sort'
      - name: state
        in: query
        description: Filter results by the state of the campaign template.
        example: draft
        required: false
        schema:
          type: string
          enum:
          - draft
          - enabled
          - disabled
      - name: name
        in: query
        description: Filter results performing case-insensitive matching against the name of the campaign template.
        example: template1
        required: false
        schema:
          type: string
      - name: tags
        in: query
        description: 'Filter results performing case-insensitive matching against the tags of the campaign template. When used in conjunction with the "name" query parameter, a logical OR will be performed to search both tags and name for the provided values.

          '
        example: tag1
        required: false
        schema:
          type: string
      - in: query
        description: Filter results by user ID.
        example: 34
        required: false
        name: userId
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - hasMore
                - data
                properties:
                  hasMore:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CampaignTemplate'
  /v1/applications/{applicationId}/create_campaign_from_template:
    post:
      operationId: createCampaignFromTemplate
      summary: Create campaign from campaign template
      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.


        Use the campaign template referenced in the request body to create

        a new campaign in one of the connected Applications.


        If the template was created from a campaign with rules referencing [campaign collections](https://docs.talon.one/docs/product/campaigns/managing-collections),

        the corresponding collections for the new campaign are created automatically.

        '
      tags:
      - Campaign templates
      parameters:
      - $ref: '#/components/parameters/applicationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateCampaign'
        description: body
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTemplateCampaignResponse'
components:
  schemas:
    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
    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
    Binding:
      type: object
      required:
      - name
      - expression
      properties:
        name:
          type: string
          description: A descriptive name for the value to be bound.
          example: Discount percentage
        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 is evaluated, and its result is bound to the name of

            the binding. The first element must be one of the functions or operators supported

            by Talang, followed by its arguments. The arguments can be strings, numbers, or

            nested expressions. For example:

            - `["list", "10014", "10015"]` calls the `list` function to build a list of strings.

            - `["+", 2, 0]` uses the `+` operator to add two numbers.

            '
          example:
          - identity
          - 10
          items: {}
        valueType:
          type: string
          description: 'The data type of the value. One of the following:

            - `string`

            - `number`

            - `boolean`

            '
          example: number
        minValue:
          type: number
          description: The minimum value allowed for this placeholder.
          example: 0
        maxValue:
          type: number
          description: The maximum value allowed for this placeholder.
          example: 19.9
        attributeId:
          type: integer
          title: Attribute ID
          description: Identifier of the attribute attached to the placeholder.
          example: 100
        description:
          type: string
          description: Description of the placeholder field and its value in the template. This text can be shown when creating campaigns from this template.
          example: The percentage discount applied to the cart total.
    NewRuleset:
      type: object
      required:
      - rules
      - bindings
      properties:
        rules:
          type: array
          description: Set of rules to apply.
          items:
            $ref: '#/components/schemas/Rule'
        strikethroughRules:
          type: array
          description: Set of rules to apply for strikethrough.
          items:
            $ref: '#/components/schemas/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: '#/components/schemas/Binding'
          example: []
        rbVersion:
          type: string
          description: The version of the rulebuilder used to create this ruleset.
          example: v2
        activate:
          type: boolean
          description: Indicates whether this created ruleset should be activated for the campaign that owns it.
          example: true
    MutableEntity:
      type: object
      required:
      - modified
      properties:
        modified:
          type: string
          format: date-time
          description: The time this entity was last modified.
          example: '2021-09-12T10:12:42Z'
    BaseCampaign:
      type: object
      properties:
        name:
          type: string
          title: Campaign Name
          description: A user-facing name for this campaign.
          minLength: 1
          example: Summer promotions
        description:
          type: string
          title: Campaign Description
          description: A detailed description of the campaign.
          example: Campaign for all summer 2021 promotions
        startTime:
          type: string
          format: date-time
          description: Timestamp when the campaign will become active.
          example: '2021-07-20T22:00:00Z'
        endTime:
          type: string
          format: date-time
          description: Timestamp when the campaign will become inactive.
          example: '2021-09-22T22:00:00Z'
        attributes:
          type: object
          description: Arbitrary properties associated with this campaign.
        state:
          type: string
          enum:
          - enabled
          - disabled
          - archived
          default: enabled
          example: enabled
          description: 'A disabled or archived campaign is not evaluated for rules or coupons.

            '
        activeRulesetId:
          type: integer
          description: '[ID of Ruleset](https://docs.talon.one/management-api#tag/Campaigns/operation/getRulesets) this

            campaign applies on customer session evaluation.

            '
          example: 6
        tags:
          type: array
          description: A list of tags for the campaign.
          example:
          - summer
          maxItems: 50
          items:
            type: string
            minLength: 1
            maxLength: 50
        reevaluateOnReturn:
          type: boolean
          title: Reevaluate on return
          description: Indicates whether this campaign should be reevaluated when a customer returns an item.
          example: true
        features:
          type: array
          description: The features enabled in this campaign.
          example:
          - coupons
          - referrals
          items:
            type: string
            enum:
            - coupons
            - referrals
            - loyalty
            - giveaways
            - strikethrough
            - achievements
            - advancedEvents
        couponSettings:
          $ref: '#/components/schemas/CodeGeneratorSettings'
        referralSettings:
          $ref: '#/components/schemas/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: '#/components/schemas/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
        type:
          type: string
          title: Type
          enum:
          - cartItem
          - advanced
          default: advanced
          example: advanced
          description: "The campaign type. Possible type values:\n  - `cartItem`: Type of campaign that can apply effects only to cart items.\n  - `advanced`: Type of campaign that can apply effects to customer sessions and cart items.\n"
        linkedStoreIds:
          type: array
          description: 'A list of store IDs that you want to link to the campaign.


            **Note:** Campaigns with linked store IDs will only be evaluated when there is a

            [customer session update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)

            that references a linked store.

            '
          items:
            type: integer
          example:
          - 1
          - 2
          - 3
        couponAttributes:
          type: object
          description: Arbitrary properties associated with coupons in this campaign.
      required:
      - name
      - state
      - tags
      - limits
      - features
    ApplicationEntity:
      type: object
      required:
      - applicationId
      properties:
        applicationId:
          type: integer
          description: The ID of the Application that owns this entity.
          example: 322
    CampaignTemplateCouponReservationSettings:
      type: object
      properties:
        reservationLimit:
          type: integer
          minimum: 0
          maximum: 999999
          example: 45
          description: 'The number of reservations that can be made with this coupon code.

            '
        isReservationMandatory:
          title: Is reservation mandatory
          type: boolean
          example: false
          description: An indication of whether the code can be redeemed only if it has been reserved first.
          default: false
    TemplateLimitConfig:
      allOf:
      - $ref: '#/components/schemas/LimitConfig'
    Rule:
      type: object
      required:
      - title
      - condition
      - effects
      properties:
        id:
          type: string
          format: uuid
          description: A unique identifier for the rule.
          example: 7fa800a8-ac8d-4792-85dc-c4650dcc8f23
        parentId:
          type: string
          format: uuid
          description: The ID of the rule that was copied to create this rule.
          example: 7fa800a8-ac8d-4792-85dc-c4650dcc8f23
        title:
          type: string
          description: A short description of the rule.
          example: Give discount via coupon
        description:
          type: string
          description: A longer, more detailed description of the rule.
          example: Creates a discount when a coupon is valid
        bindings:
          type: array
          description: An array that provides objects with variable names (name) and talang expressions to whose result they are bound (expression) during rule evaluation. The order of the evaluation is decided by the position in the array.
          items:
            $ref: '#/components/schemas/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: {}
        effects:
          type: array
          description: An array of effectful Talang expressions in arrays that will be evaluated when a rule matches.
          items:
            type: array
            items: {}
          example:
          - catch
          - - noop
          - - setDiscount
            - 10% off
            - - '*'
              - - .
                - Session
                - Total
              - - /
                - 10
                - 100
    NewCollection:
      allOf:
      - $ref: '#/components/schemas/UpdateCollection'
      - type: object
        required:
        - name
        properties:
          name:
            type: string
            minLength: 1
            pattern: ^[^[:cntrl:]\s][^[:cntrl:]]*$
            description: The name of this collection.
            example: My collection
    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
    CodeGeneratorSettings:
      type: object
      properties:
        validCharacters:
          type: array
          description: 'List of characters used to generate the random parts of a code.

            '
          example:
          - A
          - B
          - C
          - D
          - E
          - F
          - G
          - H
          - I
          - J
          - K
          - L
          - M
          - N
          - O
          - P
          - Q
          - R
          - S
          - T
          - U
          - V
          - W
          - X
          - Y
          - Z
          - '0'
          - '1'
          - '2'
          - '3'
          - '4'
          - '5'
          - '6'
          - '7'
          - '8'
          - '9'
          items:
            type: string
        couponPattern:
          type: string
          description: 'The pattern used to generate codes, such as coupon codes, referral codes, and loyalty cards. The character `#` is a placeholder and is replaced by a random character from the `validCharacters` set.

            '
          maxLength: 100
          minLength: 3
          pattern: ^[A-Za-z0-9._%+@#-]+$
          example: SUMMER-####-####
      additionalProperties: false
      required:
      - couponPattern
      - validCharacters
    AdditionalCampaignProperties:
      type: object
      properties:
        budgets:
          type: array
          items:
            $ref: '#/components/schemas/CampaignBudget'
          description: 'A list of all the budgets that are defined by this campaign and their usage.


            **Note:** Budgets that are not defined do not appear in this list and their usage is

            not counted until they are defined.

            '
        couponRedemptionCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Number of coupons redeemed in the campaign.

            '
          example: 163
        referralRedemptionCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Number of referral codes redeemed in the campaign.

            '
          example: 3
        discountCount:
          type: number
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total amount of discounts redeemed in the campaign.

            '
          example: 288
        discountEffectCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of times discounts were redeemed in this campaign.

            '
          example: 343
        couponCreationCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of coupons created by rules in this campaign.

            '
          example: 16
        customEffectCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of custom effects triggered by rules in this campaign.

            '
          example: 0
        referralCreationCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of referrals created by rules in this campaign.

            '
          example: 8
        addFreeItemEffectCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of times the [add free item effect](https://docs.talon.one/docs/dev/integration-api/api-effects#addfreeitem) can be triggered in this campaign.

            '
          example: 0
        awardedGiveawaysCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of giveaways awarded by rules in this campaign.

            '
          example: 9
        createdLoyaltyPointsCount:
          type: number
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of loyalty points created by rules in this campaign.

            '
          example: 9
        createdLoyaltyPointsEffectCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of loyalty point creation effects triggered by rules in this campaign.

            '
          example: 2
        redeemedLoyaltyPointsCount:
          type: number
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of loyalty points redeemed by rules in this campaign.

            '
          example: 8
        redeemedLoyaltyPointsEffectCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of loyalty point redemption effects triggered by rules in this campaign.

            '
          example: 9
        callApiEffectCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of webhooks triggered by rules in this campaign.

            '
          example: 0
        reservecouponEffectCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of reserve coupon effects triggered by rules in this campaign.

            '
          example: 9
        lastActivity:
          type: string
          format: date-time
          example: '2022-11-10T23:00:00Z'
          description: Timestamp of the most recent event received by this campaign.
        updated:
          type: string
          format: date-time
          example: '2022-10-27T15:00:00Z'
          description: 'Timestamp of the most recent update to the campaign''s property. Updates to external entities used in this campaign

            are **not** registered by this property, such as collection or coupon updates.

            '
        createdBy:
          type: string
          description: Name of the user who created this campaign if available.
          example: John Doe
        updatedBy:
          type: string
          description: Name of the user who last updated this campaign if available.
          example: Jane Doe
        templateId:
          type: integer
          description: The ID of the Campaign Template this Campaign was created from.
          example: 3
        frontendState:
          type: string
          description: The campaign state displayed in the Campaign Manager.
          enum:
          - expired
          - scheduled
          - running
          - disabled
          - archived
          - staged
          example: running
        storesImported:
          type: boolean
          description: Indicates whether the linked stores were imported via a CSV file.
          example: true
        valueMapsIds:
          type: array
          description: A list of value map IDs for the campaign.
          items:
            type: integer
          example:
          - 100
          - 215
        experimentId:
          type: integer
          description: The ID of the Experiment this Campaign is part of.
          example: 1
      required:
      - state
      - description
      - type
      - frontendState
      - storesImported
    Ruleset:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - $ref: '#/components/schemas/UserEntity'
      - $ref: '#/components/schemas/NewRuleset'
      - type: object
        properties:
          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.
    CreateTemplateCampaignResponse:
      type: object
      required:
      - campaign
      - ruleset
      properties:
        campaign:
          $ref: '#/components/schemas/Campaign'
        ruleset:
          $ref: '#/components/schemas/Ruleset'
        collections:
          type: array
          items:
            $ref: '#/components/schemas/Collection'
    CollectionWithoutPayload:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - $ref: '#/components/schemas/AccountEntity'
      - $ref: '#/components/schemas/MutableEntity'
      - $ref: '#/components/schemas/NewCollection'
      - type: object
        required:
        - createdBy
        properties:
          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
    CampaignTemplateParams:
      type: object
      required:
      - name
      - type
      - description
      properties:
        name:
          type: string
          description: Name of the campaign template parameter.
          minLength: 1
          example: discount_value
        type:
          type: string
          enum:
          - string
          - number
          - boolean
          - percent
          - (list string)
          - (list number)
          - time
          description: Defines the type of parameter value.
          example: number
        description:
          type: string
          description: Explains the meaning of this template parameter and the placeholder value that will define it. It is used on campaign creation from this template.
          example: This is a template parameter of type `number`.
        attributeId:
          type: integer
          description: ID of the corresponding attribute.
          example: 42
    CampaignBudget:
      type: object
      required:
      - action
      - limit
      - counter
      properties:
        action:
          type: string
          description: 'The limitable action to which this limit applies. For example:

            - `setDiscount`

            - `setDiscountEffect`

            - `redeemCoupon`

            - `createCoupon`

            '
          example: createCoupon
        limit:
          type: number
          minimum: 0
          example: 1000
          description: 

# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/talon-one/refs/heads/main/openapi/talon-one-campaign-templates-api-openapi.yml