openapi: 3.0.1
servers:
  - url: https://integration.talon.one
info:
  version: 1.0.0
  title: Third-party API reference docs
  description: |
    Use the Third-party API from [Talon.One's technology partners](https://docs.talon.one/docs/dev/technology-partners/overview).

    For example, use the Braze-specific endpoints from your Braze campaigns to interact with Talon.One.

    If the CDP or CEP you are using isn't listed here, use the generic
    [Customer Data Platforms](#tag/Customer-data-platforms) and [Customer Engagement Platform](#tag/Customer-engagement-platforms) endpoints.

    <div class="redoc-section">
      <p class="title">Are you looking for a different API?</p>

      If you need the API to:

      - Integrate with Talon.One directly and send real-time data, see [the Integration API reference docs](https://docs.talon.one/integration-api).
      - Interact with the Campaign Manager for backoffice operations, see [the Management API reference docs](https://docs.talon.one/management-api).
    </div>


    # Authentication

    <SecurityDefinitions />

tags:
  - name: Braze
    description: |
      [Braze](https://www.braze.com/) is a customer engagement platform to manage customer-centric interactions between consumers and brands in real-time.

      Use these endpoints to automate the creation of coupon and referral codes
      and deliver them to specific customer segments. To send requests to these endpoints, use the
      [connected content feature](https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/connected_content/connected_content_retries) in Braze.

      For more information, see our integration examples in [the developer docs](https://docs.talon.one/docs/dev/technology-partners/braze).
  - name: Customer data platforms
    description: |
      You can integrate with any customer data platform, or CDP, using the following endpoints designed for third-party tools, rather than your own integration layer.

      Use these endpoints to automate the creation of coupon and referral codes and deliver them to specific customer segments.
  - name: Customer engagement platforms
    description: |
      You can integrate with any customer engagement platform, or CEP, using the following endpoints designed for third-party tools, rather than your own integration layer.

      Use these endpoints to automate the creation of coupon and referral codes and deliver them to specific customer segments.

      For more information, see our integration examples in [the developer docs](https://docs.talon.one/docs/dev/technology-partners/cep/integrating-cep).
  - name: Iterable
    description: |
      [Iterable](https://iterable.com/) is a cross-channel marketing platform that powers unified customer experiences
      and empowers you to create, optimize and measure every interaction across the entire customer journey.

      Use these endpoints to automate the creation of coupon and referral codes
      and deliver them to specific customer segments. To send requests to these endpoints, use the
      [data feed feature](https://support.iterable.com/hc/en-us/articles/360044425931#enable-template-generation-using-data-feeds) in Iterable.

      For more information, see our integration examples in [the developer docs](https://docs.talon.one/docs/dev/technology-partners/iterable).
  - name: Segment
    description: |
      [Segment](https://segment.com/) is a customer data platform that collects events from your web & mobile apps.

      Use these endpoints to integrate with Talon.One.
  - name: Selligent
    description: |
      [Selligent](https://www.selligent.com/) Marketing Cloud is an AI-powered marketing automation platform that helps you make marketing personal, by activating your data to deliver unique, highly relevant experiences to your customers at every moment of interaction, across all channels and devices.
      
      For more information, see [the developer docs](https://docs.talon.one/docs/dev/technology-partners/selligent).

  - name: mParticle
    description: |
      [mParticle](https://www.mparticle.com/) is the customer data platform that helps unify data and simplify partner integrations with enterprise-class security and reliability.

      For more information, see our integration examples in [the developer docs](https://docs.talon.one/docs/dev/technology-partners/mparticle).

  - name: Emarsys
    description: |
      Emarsys is a customer engagement platform that enables marketers to build, launch, and scale personalized cross-channel promotional campaigns that have measurable impact.

      Use these endpoints to integrate with Talon.One.

  - name: API Health
    description: Check API health
    x-internal: true

paths:
  /health:
    get:
      summary: Check API health
      operationId: health
      x-internal: true
      description: Check the health of the API.
      tags:
      - API Health
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              examples:
                default:
                  $ref: '#/components/examples/HealthResponse'
  ################################
  # Braze Integration API Routes #
  ################################
  /braze/referral:
    post:
      tags:
        - Braze
      summary: Create referral
      operationId: braze/createReferral
      description: |
        Create a referral code in Talon.One. To use it in your Braze deployment, see [the tutorial](https://docs.talon.one/docs/dev/technology-partners/braze/creating-referrals-braze).
      parameters:
        - $ref: '#/components/parameters/dryRun'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReferralRequest'
            examples:
              default:
                $ref: '#/components/examples/ReferralRequest'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralResponse'
              examples:
                default:
                  $ref: '#/components/examples/ReferralResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
  /braze/coupon:
    post:
      tags:
        - Braze
      summary: Create coupon
      operationId: braze/createCoupon
      description: |
        Create a coupon code in Talon.One. To use it in your Braze deployment, see [the tutorial](https://docs.talon.one/docs/dev/technology-partners/braze/creating-coupons-braze).

        You can also use this endpoint to get an existing coupon's details by setting the `identifier` property to a value you previously used.

        **Tip:** You can edit the default coupon code format in the [campaign's settings](https://docs.talon.one/docs/product/campaigns/coupons/coupon-page-overview#editing-coupon-format).
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CouponRequest'
            examples:
              default:
                $ref: '#/components/examples/CouponRequest'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponResponse'
              examples:
                default:
                  $ref: '#/components/examples/CouponResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
  /braze/event:
    post:
      tags:
        - Braze
      summary: Track event
      operationId: braze/trackEvent
      description: |
        Triggers a custom event inside Talon.One. You can then trigger rules when this event is received.

        An event is a type of custom attribute. You must create it first in the Campaign Manager. See [creating custom events](https://docs.talon.one/docs/dev/concepts/entities/events#custom-events).
        To see the events received by your Application in Talon.One, open the Application and click **Events**.

        For more information, see [the tutorial](https://docs.talon.one/docs/dev/technology-partners/braze/adding-loyalty-points-braze).

        **Note:** If the customer profile ID you provided does not exist in Talon.One, a customer profile is created with the ID you provided.
      parameters:
        - $ref: '#/components/parameters/destinationHostname'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrazeTrackEventRequest'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationStateV2'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'

  ###################################
  # Iterable Integration API Routes #
  ###################################
  /iterable/coupon:
    get:
      tags:
        - Iterable
      summary: Create coupon
      operationId: iterable/createCoupon
      description: |
        Create a coupon code in Talon.One. To use it in your Iterable deployment and generate
        the request, see [the tutorial](https://docs.talon.one/docs/dev/technology-partners/iterable/creating-coupons-iterable).

        **Tip:** You can edit the default coupon code format in the [campaign's settings](https://docs.talon.one/docs/product/campaigns/coupons/coupon-page-overview#editing-coupon-format).
      parameters:
        - $ref: '#/components/parameters/deployment'
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/expiryDate'
        - $ref: '#/components/parameters/discountLimit'
        - $ref: '#/components/parameters/iterableCampaignId'
        - $ref: '#/components/parameters/recipientIntegrationId'
        - $ref: '#/components/parameters/usageLimitCoupons'
        - $ref: '#/components/parameters/attributes'
      responses:
        200:
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponResponse'
              examples:
                default:
                  $ref: '#/components/examples/CouponResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
  /iterable/referral:
    get:
      tags:
        - Iterable
      summary: Create referral
      operationId: iterable/createReferral
      description: |
        Create a referral code in Talon.One. To use it in your Iterable deployment and generate
        the request, see [the tutorial](https://docs.talon.one/docs/dev/technology-partners/iterable/creating-referral-iterable).
      parameters:
        - $ref: '#/components/parameters/deployment'
        - $ref: '#/components/parameters/campaignId'
        - $ref: '#/components/parameters/advocateProfileIntegrationId'
        - $ref: '#/components/parameters/friendProfileIntegrationId'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/expiryDate'
        - $ref: '#/components/parameters/usageLimit'
        - $ref: '#/components/parameters/attributes'
      responses:
        200:
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralResponse'
              examples:
                default:
                  $ref: '#/components/examples/ReferralResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
  /iterable/loyalty:
    get:
      tags:
        - Iterable
      summary: Get loyalty ledger
      operationId: iterable/loyalty
      description: |
        Get the loyalty ledger information of the given customer profile from Talon.One. To use it in your Iterable deployment and generate
        the request, see [the tutorial](https://docs.talon.one/docs/dev/technology-partners/iterable/getting-loyalty-iterable).
      parameters:
        - $ref: '#/components/parameters/deployment'
        - $ref: '#/components/parameters/profileIntegrationId'
        - $ref: '#/components/parameters/loyaltyProgramId'
      responses:
        200:
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoyaltyResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  ####################################
  # Selligent Integration API Routes #
  ####################################
  /selligent:
    get:
      tags:
        - Selligent
      summary: Create coupon
      operationId: selligent/createCoupon
      description: |
        Create a coupon code in Talon.One. To use it in your Selligent deployment, see [the tutorial](https://docs.talon.one/docs/dev/technology-partners/selligent).

        **Tip:** You can edit the default coupon code format in the [campaign's settings](https://docs.talon.one/docs/product/campaigns/coupons/coupon-page-overview#editing-coupon-format).
      parameters:
        - $ref: '#/components/parameters/deployment'
        - $ref: '#/components/parameters/campaignId'
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/selligentCampaignId'
        - $ref: '#/components/parameters/recipientIntegrationId'
        - $ref: '#/components/parameters/discountLimit'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/expiryDate'
        - $ref: '#/components/parameters/usageLimitCoupons'
      responses:
        200:
          description: Response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CouponResponse'
                  - $ref: '#/components/schemas/errorResponseWithStatus'
              examples:
                success response:
                  $ref: '#/components/examples/CouponResponse'
                error response:
                  value:
                    StatusCode: 200
                    Error: |
                      malformed url query: campaignID parameter is invalid or is missing
                    RequestUUID: fd2f7c55-d064-46e1-ab87-a39cb877cd82
        401:
          $ref: '#/components/responses/Unauthorized'
        429:
          $ref: '#/components/responses/TooManyRequests'

  ##################################
  # Segment Integration API Routes #
  ##################################
  /segment/customer_profile/{customerProfileId}:
    put:
      tags:
        - Segment
      parameters:
        - $ref: '#/components/parameters/destinationHostname'
        - name: customerProfileId
          in: path
          description: The integration ID of the customer profile.
          required: true
          schema:
            type: string
      summary: Upsert customer profile
      operationId: segment/updateCustomerProfile
      deprecated: true
      description: |
        **Important:** This endpoint is deprecated. We recommend you use the current [Update customer profile](#tag/Segment/operation/segment/v2/updateCustomerProfile) endpoint.

        <blockquote>Create or update the given customer profile, and creates or set the specified attributes. You can also
        use this endpoint to specify which audiences this customer has joined or left.

        **Note:**
        The audiences must be created first with [Create audience](#tag/Segment/operation/segment/createAudience).
        </blockquote>
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentCustomerProfileRequest'
            examples:
              default:
                $ref: '#/components/examples/SegmentCustomerProfileRequest'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerProfileResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/SegmentTooManyRequestsOrParallel'


  /segment/customer_profile_v2/{customerProfileId}:
    put:
      tags:
        - Segment
      parameters:
        - $ref: '#/components/parameters/destinationHostname'
        - name: customerProfileId
          in: path
          description: The integration ID of the customer profile.
          required: true
          schema:
            type: string
      summary: Upsert customer profile V2
      operationId: segment/updateCustomerProfileV2
      deprecated: true
      description: |
        **Important:** This endpoint is deprecated. We recommend you use the current [Update customer profile](#tag/Segment/operation/segment/v2/updateCustomerProfile) endpoint.

        <blockquote>Create or update the given customer profile, and also creates or set the specified attributes and audiences.

        You **do not** have to create attributes or audiences before using this endpoint.</blockquote>

      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentCustomerProfileRequestV2'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerProfileResponseV2'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/SegmentTooManyRequestsOrParallel'
  /segment/v2/customer_profiles/{customerProfileId}:
    put:
      tags:
        - Segment
      parameters:
        - $ref: '#/components/parameters/destinationHostname'
        - $ref: '#/components/parameters/skipNonExistingAttributes'
        - name: customerProfileId
          in: path
          description: The integration ID of the customer profile.
          required: true
          schema:
            type: string
      summary: Update customer profile
      operationId: segment/v2/updateCustomerProfile
      description: |
        Create or update the given customer profile.

        **Note:**

        - Create all the required attributes and audiences before using this endpoint.
        - This endpoint replaces the [Upsert customer profile](#tag/Segment/operation/segment/updateCustomerProfile) and [Upsert customer profile V2](#tag/Segment/operation/segment/updateCustomerProfileV2) endpoints.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentCustomerProfileV2Request'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerProfileIntegrationResponseV2'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/SegmentTooManyRequestsOrParallel'
  /segment/customer_profiles/audiences:
    parameters:
      - $ref: '#/components/parameters/destinationHostname'
    put:
      tags:
        - Segment
      summary: Update audiences in multiple customer profiles
      operationId: segment/updateCustomerProfilesAudiences
      description: |
        Update the specified audiences for the specified profiles.

        If a provided customer profile doesn't exist, it is created automatically.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerProfilesAudiencesRequest'
      responses:
        204:
          description: No Content
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/SegmentTooManyRequests'
  /segment/event:
    parameters:
      - $ref: '#/components/parameters/destinationHostname'
    put:
      tags:
        - Segment
      summary: Track event
      operationId: segment/trackEvent
      deprecated: true
      description: |
        **Important:** This endpoint is deprecated. We recommend you use the current [Track Event](#tag/Segment/operation/segment/trackEventV2) endpoint.

        <blockquote>Triggers a custom event inside Talon.One. You can then trigger rules when this event is received.

        An event is a type of custom attribute, you must create it first in the Campaign Manager. See [creating custom events](https://docs.talon.one/docs/dev/concepts/entities/events#custom-events).
        To see the events received by your Application in Talon.One, open the Application and click **Events**.

        If the specified session already exists, it must belong to the same `profileId` or an error will be returned.</blockquote>
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentTrackEventRequest'
            examples:
              default:
                $ref: '#/components/examples/SegmentTrackEventRequest'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationStateV2'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/SegmentTooManyRequestsOrParallel'

  /segment/v2/events:
    parameters:
      - $ref: '#/components/parameters/destinationHostname'
      - $ref: '#/components/parameters/skipNonExistingAttributes'
    put:
      tags:
        - Segment
      summary: Track event
      operationId: segment/trackEventV2
      description: |
        Trigger a custom event inside Talon.One. You can then trigger rules when this event is received.

        An event is a type of custom attribute, you must create it first in the Campaign Manager. See [creating custom events](https://docs.talon.one/docs/dev/concepts/entities/events#custom-events).
        To see the events received by your Application in Talon.One, open the Application and click **Events**.

        If the specified session already exists, it must belong to the same `profileId`, or else an error is returned.

        **Note:**

        - Create the event and all the required attributes before using this endpoint.
        - This `v2` version replaces the previous `v1` version of this endpoint.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentTrackEventV2Request'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationStateV2'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/SegmentTooManyRequestsOrParallel'

  /segment/audiences:
    parameters:
      - $ref: '#/components/parameters/destinationHostname'
    post:
      tags:
        - Segment
      summary: Create audience
      operationId: segment/createAudience
      description: |
        Create an audience. The audience can be created directly from scratch or can come from Segment.

        Once you create your first audience, audience-specific rule conditions are enabled in the Rule Builder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAndUpdateAudienceRequest'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAndUpdateResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        409:
          $ref: '#/components/responses/AudienceAlreadyExist'
        429:
          $ref: '#/components/responses/SegmentTooManyRequests'
  /segment/audiences/{audienceId}:
    parameters:
      - $ref: '#/components/parameters/audienceId'
      - $ref: '#/components/parameters/destinationHostname'
    put:
      tags:
        - Segment
      summary: Update audience
      operationId: segment/updateAudience
      description: |
        Update an audience.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAndUpdateAudienceRequest'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAndUpdateResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/SegmentTooManyRequests'
    delete:
      tags:
        - Segment
      summary: Delete audience
      operationId: segment/deleteAudience
      description: |
        Delete the audience.

        **Warning:** This endpoint also removes any associations recorded between a customer profile and this audience.
      responses:
        204:
          description: No Content
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/SegmentTooManyRequests'

  /segment/customer_sessions/{customerSessionId}:
    put:
      tags:
        - Segment
      summary: Update customer session
      operationId: segment/updateCustomerSession
      deprecated: true
      description: |
        **Important:** This endpoint is deprecated. We recommend you use the current [Update customer session](#tag/Segment/operation/segment/v2/updateCustomerSession) endpoint.

        <blockquote>Update the given customer session, or creates it if it doesn't exist.

        Customer sessions are a key concept in Talon.One, see the [documentation](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).

        This endpoint also allows you to define a callback where the response will be sent. See the **Header parameters** section below.</blockquote>
      parameters:
        - $ref: '#/components/parameters/destinationHostname'
        - $ref: '#/components/parameters/callbackDestinationURI'
        - $ref: '#/components/parameters/callbackAPIKey'
        - $ref: '#/components/parameters/contentFields'
        - $ref: '#/components/parameters/correlationID'
        - name: customerSessionId
          in: path
          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).
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerSessionRequest'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationStateV2'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        429:
          $ref: '#/components/responses/SegmentTooManyRequestsOrParallel'

  /segment/v2/customer_sessions/{customerSessionId}:
    put:
      tags:
        - Segment
      summary: Update customer session
      operationId: segment/v2/updateCustomerSession
      description: |
        Update the given customer session, or create a customer session if it doesn't exist.

        Customer sessions are a key concept in Talon.One, see the [documentation](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).

        This endpoint also allows you to define a callback where the response will be sent. See the **Header parameters** section below.

        **Note:**

        - Create all the required attributes before using this endpoint.
        - This `v2` version replaces the previous `v1` version of this endpoint.
      parameters:
        - $ref: '#/components/parameters/destinationHostname'
        - $ref: '#/components/parameters/callbackDestinationURI'
        - $ref: '#/components/parameters/callbackAPIKey'
        - $ref: '#/components/parameters/contentFields'
        - $ref: '#/components/parameters/correlationID'
        - $ref: '#/components/parameters/skipNonExistingAttributes'
        - name: customerSessionId
          in: path
          description: |
            The `integration ID` of the customer session. You set this ID when you create a customer session.

            You can see the existing customer session integration IDs in the Campaign Manager's **Sessions** menu, or via the
            [List Application session](https://docs.talon.one/management-api#operation/getApplicationSessions) endpoint.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/newCustomerSessionV2'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationStateV2'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        429:
          $ref: '#/components/responses/SegmentTooManyRequestsOrParallel'

  ##############################
  # CDP Integration API Routes #
  ##############################
  /cdp/customer_profile/{customerProfileId}:
    parameters:
      - $ref: '#/components/parameters/customerDataPlatformName'
      - $ref: '#/components/parameters/destinationHostname'
      - $ref: '#/components/parameters/skipNonExistingAttributes'
    put:
      tags:
        - Customer data platforms
      parameters:
        - name: customerProfileId
          in: path
          description: The integration ID of the customer profile.
          required: true
          example: URN-GV8294NV
          schema:
            type: string
      summary: Update customer profile
      operationId: cdp/updateCustomerProfile
      description: |
        Update the given customer profile to add or remove audiences.

        **Note:** Create all the required attributes and audiences before using this endpoint.

      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CDPCustomerProfileRequest'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationStateV2'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
  /cdp/customer_profiles/audiences:
    parameters:
      - $ref: '#/components/parameters/customerDataPlatformName'
      - $ref: '#/components/parameters/destinationHostname'
    put:
      tags:
        - Customer data platforms
      summary: Update audiences in multiple customer profiles
      operationId: cdp/updateCustomerProfilesAudiences
      description: |
        Update the specified audiences for the specified profiles.

        If a provided customer profile doesn't exist, it is created automatically.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerProfilesAudiencesRequest'
      responses:
        204:
          description: No Content
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
  /cdp/audiences:
    parameters:
      - $ref: '#/components/parameters/customerDataPlatformName'
      - $ref: '#/components/parameters/destinationHostname'
    post:
      tags:
        - Customer data platforms
      summary: Create audience
      operationId: cdp/createAudience
      description: |
        Create an audience. The audience can be created directly from scratch or can come from third party platforms.

        Once you create your first audience, audience-specific rule conditions are enabled in the Rule Builder.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAndUpdateAudienceRequest'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAndUpdateResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
        409:
          $ref: '#/components/responses/AudienceAlreadyExist'
  /cdp/audiences/{audienceId}:
    parameters:
      - $ref: '#/components/parameters/audienceId'
      - $ref: '#/components/parameters/customerDataPlatformName'
      - $ref: '#/components/parameters/destinationHostname'
    put:
      tags:
        - Customer data platforms
      summary: Update audience
      operationId: cdp/updateAudience
      description: |
        Update an audience created by a third-party integration.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAndUpdateAudienceRequest'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAndUpdateResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
    delete:
      tags:
        - Customer data platforms
      summary: Delete audience
      operationId: cdp/deleteAudience
      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.
      responses:
        204:
          description: No Content
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'

  ###################################
  # CEP Integration API Routes      #
  ###################################
  /customer_engagement/coupon:
    get:
      tags:
        - Customer engagement platforms
      summary: Create coupon
      operationId: cep/createCoupon
      description: |
        Create a coupon code in Talon.One. See [the tutorial](https://docs.talon.one/docs/dev/technology-partners/cep/integrating-cep).

        **Tip:** You can edit the default coupon code format in the [campaign's settings](https://docs.talon.one/docs/product/campaigns/coupons/coupon-page-overview#editing-coupon-format).
      parameters:
        - $ref: '#/components/parameters/customerEngagementPlatformName'
        - $ref: '#/components/parameters/destinationHostname'
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - $ref: '#/components/parameters/externalCampaignId'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/expiryDate'
        - $ref: '#/components/parameters/dryRun'
        - $ref: '#/components/parameters/discountLimit'
        - $ref: '#/components/parameters/recipientIntegrationId'
        - $ref: '#/components/parameters/usageLimitCoupons'
        - $ref: '#/components/parameters/attributes'
        - $ref: '#/components/parameters/identifier'
      responses:
        200:
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponResponse'
              examples:
                default:
                  $ref: '#/components/examples/CouponResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
  /customer_engagement/referral:
    get:
      tags:
        - Customer engagement platforms
      summary: Create referral
      operationId: cep/createReferral
      description: |
        Create a referral code in Talon.One. See [the tutorial](https://docs.talon.one/docs/dev/technology-partners/cep/integrating-cep).
      parameters:
        - $ref: '#/components/parameters/customerEngagementPlatformName'
        - $ref: '#/components/parameters/destinationHostname'
        - $ref: '#/components/parameters/dryRun'
        - $ref: '#/components/parameters/campaignId'
        - $ref: '#/components/parameters/advocateProfileIntegrationId'
        - $ref: '#/components/parameters/friendProfileIntegrationId'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/expiryDate'
        - $ref: '#/components/parameters/usageLimit'
        - $ref: '#/components/parameters/attributes'
      responses:
        200:
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralResponse'
              examples:
                default:
                  $ref: '#/components/examples/ReferralResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
  /customer_engagement/loyalty:
    get:
      tags:
        - Customer engagement platforms
      summary: Get loyalty ledger
      operationId: cep/loyalty
      description: |
        Get the loyalty ledger information of the given customer profile from Talon.One. See [the tutorial](https://docs.talon.one/docs/dev/technology-partners/cep/integrating-cep).
      parameters:
        - $ref: '#/components/parameters/customerEngagementPlatformName'
        - $ref: '#/components/parameters/destinationHostname'
        - $ref: '#/components/parameters/profileIntegrationId'
        - $ref: '#/components/parameters/loyaltyProgramId'
      responses:
        200:
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoyaltyResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'
  ####################################
  # mParticle Integration API Routes #
  ####################################
  /mparticle:
    post:
      tags:
        - mParticle
      summary: Send event
      operationId: mparticle/sendevent
      description: |
        Send an mParticle event to Talon.One.

        This endpoint supports the following mParticle events:
        - `module_registration_request`: A new client signs up for Talon.One in mParticle.
        - `audience_subscription_request`: A client adds/deletes/edits an audience in mParticle.
        - `event_processing_request`: Talon.One should process events that have been triggered in mParticle.
        - `audience_membership_change_request`: Customers are added to/removed from an audience in mParticle.
      security: []
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/ModuleRegistrationRequest'
                - $ref: '#/components/schemas/AudienceMembershipChangeRequest'
                - $ref: '#/components/schemas/AudienceSubscriptionRequest'
                - $ref: '#/components/schemas/EventProcessingRequest'
            examples:
              moduleRegistrationRequest:
                $ref: '#/components/examples/ModuleRegistrationRequest'
              audienceMembershipChangeRequest:
                $ref: '#/components/examples/AudienceMembershipChangeRequest'
              audienceSubscriptionRequest:
                $ref: '#/components/examples/AudienceSubscriptionRequest'
              eventProcessingRequest:
                $ref: '#/components/examples/EventProcessingRequest'
      responses:
        200:
          description: Response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ModuleRegistrationResponse'
                  - $ref: '#/components/schemas/AudienceSubscriptionResponse'
                  - $ref: '#/components/schemas/AudienceMembershipChangeResponse'
                  - $ref: '#/components/schemas/EventProcessingResponse'
              examples:
                moduleRegistrationResponse:
                  $ref: '#/components/examples/ModuleRegistrationResponse'
                audienceSubscriptionResponse:
                  $ref: '#/components/examples/AudienceSubscriptionResponse'
                audienceMembershipChangeResponse:
                  $ref: '#/components/examples/AudienceMembershipChangeResponse'
                eventProcessingResponse:
                  $ref: '#/components/examples/EventProcessingResponse'
        401:
          $ref: '#/components/responses/Unauthorized'
        400:
          $ref: '#/components/responses/BadRequest'
        409:
          $ref: '#/components/responses/AudienceAlreadyExist'
        429:
          $ref: '#/components/responses/TooManyRequests'

  ###################################
  # Emarsys Integration API Routes  #
  ###################################
  /emarsys/customer_profiles/coupons:
    post:
      security:
        - ApiKeyBasicAuth: []
      tags:
        - Emarsys
      summary: Get coupon
      operationId: emarsys/getCoupon
      description: |
        Retrieve a coupon code from Talon.One.
      parameters:
        - $ref: '#/components/parameters/deployment'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmarsysCouponRequest'
      responses:
        200:
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmarsysCouponResponse'
              examples:
                default:
                  $ref: '#/components/examples/EmarsysCouponResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          $ref: '#/components/responses/TooManyRequests'

components:
  parameters:
    audienceId:
      name: audienceId
      in: path
      description: The ID of the audience.
      required: true
      schema:
        type: integer
        format: int64
      example: 4729630
    customerDataPlatformName:
      name: customer-data-platform-name
      in: header
      description: The name of the CDP platform.
      required: true
      schema:
        type: string
        format: string
      example: My CDP platform
    deployment:
      name: deployment
      in: query
      description: The base URL of your Talon.One deployment.
      schema:
        type: string
      required: true
      example: company.talon.one
    campaignId:
      name: campaignId
      in: query
      description: The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.
      schema:
        type: integer
        format: int64
      required: true
      example: 5843
    applicationId:
      name: applicationId
      in: query
      description: The ID of the Application in Talon.One. It is displayed in your Talon.One deployment URL.
      schema:
        type: integer
        format: int64
      required: true
      example: 316
    startDate:
      description: The date when the code becomes usable.
      name: startDate
      in: query
      schema:
        type: string
        format: date-time
      example: 2022-09-30T15:35:02Z
    expiryDate:
      description: The date when the code becomes unusable.
      name: expiryDate
      in: query
      schema:
        type: string
        format: date-time
      example: 2022-10-30T15:35:02Z
    advocateProfileIntegrationId:
      name: advocateProfileIntegrationId
      in: query
      description: The integration ID of the advocate.
      schema:
        type: string
      required: true
      example: testAdvocateProfile
    friendProfileIntegrationId:
      name: friendProfileIntegrationId
      in: query
      description: The profile ID of the referred customer.
      schema:
        type: string
      example: testFriendProfile
    usageLimit:
      name: usageLimit
      in: query
      description: 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.
      schema:
        type: integer
        format: int64
      example: 1
    usageLimitCoupons:
      name: usageLimit
      in: query
      description: The number of times the coupon code can be redeemed. 0 means unlimited redemptions but any campaign usage limits will still apply. The default value is 1.
      schema:
        type: integer
        format: int64
        default: 1
      example: 1
    discountLimit:
      name: discountLimit
      in: query
      description: The discount amount the coupon is worth. Can be blank if, for example, the coupon provides a 10% discount, or something other than a fixed value of discounts.
      schema:
        type: integer
        format: int64
      example: 155
    iterableCampaignId:
      name: iterableCampaignId
      in: query
      description: The ID of the campaign in Iterable.
      schema:
        type: string
      required: true
      example: iterableCampaign
    recipientIntegrationId:
      name: recipientIntegrationId
      in: query
      description: The integration ID of the only customer that can use the generated coupon code. Leave blank to allow any user to use the coupon.
      schema:
        type: string
      example: URN-GV8294NV
    profileIntegrationId:
      name: profileIntegrationId
      in: query
      description: The integration ID of the customer profile in Talon.One.
      schema:
        type: string
      required: true
      example: URN-GV8294NV
    loyaltyProgramId:
      name: loyaltyProgramId
      in: query
      description: The ID of the loyalty program in Talon.One.
      schema:
        type: integer
        format: int64
      required: true
      example: 25
    selligentCampaignId:
      name: selligentCampaignId
      in: query
      description: Selligent campaign id
      required: true
      schema:
        type: string
      example: someCampaignId
    customerEngagementPlatformName:
      name: customer-engagement-platform-name
      in: header
      description: The name of the third-party platform.
      schema:
        type: string
      required: true
      example: My CEP platform
    destinationHostname:
      name: destination-hostname
      in: header
      description: The base URL of your Talon.One deployment.
      required: true
      schema:
        type: string
        format: hostname
      example: mycompany.europe-west1.talon.one
    dryRun:
      name: X-DRY-RUN
      in: header
      description: Indicates whether to persist the changes. Changes are ignored when `X-DRY-RUN=true`.
      schema:
        type: boolean
      example: true
    externalCampaignId:
      name: externalCampaignId
      in: query
      description: The ID of the campaign in the third-party platform.
      schema:
        type: string
      example: testCampaignId
      required: true
    attributes:
      name: attributes
      in: query
      description: |
        Optional parameter to set the value of custom attributes. They are defined in the Campaign Manager,
        see [Managing attributes](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes).

        Prefix each attribute name with `.`.

        Certain attributes can also be set to _mandatory_ in your Application [settings](https://docs.talon.one/docs/product/applications/using-attributes#making-attributes-mandatory).
        If your Application uses mandatory attributes, you must use this parameter to set their value.

        Full URI example: `https://<url>?applicationId=5&.myAttribute1=1234&.myAttribute2=abc`.
      schema:
        type: object
        additionalProperties: true
      style: form
      explode: true
      example:
        .firstName: john
        .country: DE
    callbackDestinationURI:
      name: X-Callback-Destination-URI
      in: header
      description: |
        The **full** URI where Talon.One sends the response content. The callback is a `POST` request.
      schema:
        type: string
        format: hostname
      example: http://mydomain.com/api/callbacks
    callbackAPIKey:
      name: X-Callback-API-Key
      in: header
      description: |
        The header and the API key, separated by a space. The first space marks the header.

        For example:
        - To set `Authorization: 3aa74d582bd94`, use `Authorization 3aa74d582bd94`.
        - To set `Authorization: ApiKey-v1 3aa74d582bd94`, use `Authorization ApiKey-v1 3aa74d582bd94`.

        The minimal length of the API key is 32 characters.
      example: Authorization 3aa74d582bd9479c59e16f970fe13bf3
      schema:
        type: string
    contentFields:
      name: X-Content-Fields
      in: header
      description: |
        A comma-separated list of field names from the Update customer enpdoint's response that you want to receive.

        If omitted, all the fields will be sent to the callback destination URI.
      example: effects, customerProfile, customerSession
      schema:
        type: string
        enum: [customerSession, customerProfile, coupons, triggeredCampaigns, referral, loyalty, event, awardedGiveaways, ruleFailureReasons, previousReturns, createdAttributes, createdCoupons, createdReferrals, effects]
    correlationID:
      name: X-Correlation-ID
      in: header
      description: |
        An arbitrary ID assigned to the callback request. You can use it to track the callbacks you receive from Talon.One.
        If omitted, the callback request does not include `X-Correlation-ID`.
      schema:
        type: string
      example: abc123
    identifier:
      name: identifier
      in: query
      description: |
        The identifier of the request. Providing a new value creates a new coupon. Providing an existing value retrieves the existing coupon of that ID and does not create a new coupon.
      schema:
        type: string
      example: 3495-4323
    skipNonExistingAttributes:
      name: skipNonExistingAttributes
      in: query
      schema:
        type: boolean
      example: true
      description: |
        Indicates whether to skip non-existing attributes.

        If `true`, the non-existing attributes are skipped and a 400 error is not returned.

        If `false`, a 400 error is returned in case of non-existing attributes.

  schemas:
    HealthResponse:
      x-internal: true
      type: object
      required:
        - Status
        - Commit
        - Version
        - Date
      properties:
        Status:
          type: string
          description: The HTTP status.
          enum: ['OK']
          example: OK
        Commit:
          type: string
          description: The Git commit hash that this version was built on.
          example: df532a0dce4902db7f81bc190216309bc9da61cc
        Version:
          type: string
          description: The version of `talon-integration`.
          example: 0.0.141
        Date:
          type: string
          format: date-time
          description: The date when `talon-integration` was built.
          example: 2023-11-08T09:24:10Z

    #####################################
    # Braze Request and Response Models #
    #####################################
    ReferralRequest:
      type: object
      required:
        - deploymentUrl
        - campaignId
        - advocateProfileIntegrationId
      properties:
        deploymentUrl:
          type: string
          description: The base url of your deployment.
          example: mycompany.europe-west1.talon.one
        campaignId:
          type: integer
          format: int64
          minimum: 1
          example: 3
          description: The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.
        advocateProfileIntegrationId:
          type: string
          minLength: 1
          example: URN-GV8294NV
          description: The customer integration ID of the advocate.
        friendProfileIntegrationId:
          type: string
          minLength: 1
          example: PKBR-G06449OELK
          description: The customer integration ID of the person being referred.
        startDate:
          type: string
          format: date-time
          example: 2021-09-30T15:35:02.371569+02:00
          description: The date when the code becomes usable.
        expiryDate:
          type: string
          format: date-time
          example: 2021-10-03T15:35:02.371569+02:00
          description: The date when the code becomes unsable.
        usageLimit:
          type: integer
          format: int64
          minimum: 0
          default: 0
          example: 1
          description: Set the usage limit of the referral to unlimited.
        attributes:
          type: object
          description: |
            An object containing the value of each attributes to set.

            New attributes are created automatically. For more information, see [Attributes](https://docs.talon.one/docs/dev/concepts/attributes).
    ReferralResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 32
        created:
          type: string
          format: date-time
          example: 2020-02-08T14:15:20Z
        startDate:
          type: string
          format: date-time
          example: 2020-02-12T11:00:00Z
        expiryDate:
          type: string
          format: date-time
          example: 2021-02-12T11:00:00Z
        usageLimit:
          type: integer
          format: int64
          example: 1
        campaignId:
          type: integer
          format: int64
          example: 23
        advocateProfileIntegrationId:
          type: string
          minLength: 1
          example: URN-GV8294NV
        friendProfileIntegrationId:
          type: string
          minLength: 1
          example: PKBR-G06449OELK
        attributes:
          type: object
          example:
            phone: 555-555-555
            language: english
        code:
          type: string
          example: XMAS-2020
        usageCounter:
          type: integer
          format: int64
          example: 0
        dryRun:
          type: boolean
          example: true
    CouponRequest:
      type: object
      required:
        - deploymentUrl
        - applicationId
        - campaignId
        - identifier
      properties:
        deploymentUrl:
          type: string
          description: The base URL of your Talon.One deployment.
          example: mycompany.europe-west1.talon.one
        applicationId:
          type: integer
          format: int64
          minimum: 1
          description: The ID of the Application in Talon.One. It is displayed in your Talon.One deployment URL.
          example: 2
        campaignId:
          type: integer
          format: int64
          minimum: 1
          description: The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.
          example: 34
        identifier:
          type: string
          minLength: 1
          description: |
            The identifier of the request. Providing a new value creates a new coupon. Providing an existing value retrieves the existing coupon of that ID and does not create a new coupon.

            In general, you should set it to a variable controlled by Braze. Usual values include:
            - `message_api_id`
            - `variant_api_id`
            - `dispatch_id`

            See [Supported personalization tags](https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/liquid/supported_personalization_tags/)
            and [dispatch ID](https://www.braze.com/docs/help/help_articles/data/dispatch_id/) behavior.
          example: 3495-4323
        usageLimit:
          type: integer
          format: int64
          default: 1
          description: The usage limit of the coupon.
          example: 1
        discountLimit:
          type: number
          minimum: 0
          maximum: 999999
          example: 30
          description: |
            The discount amount the coupon is worth. Can be blank if, for example, the coupon provides a 10% discount, or something other than a fixed value of discounts.
        reservationLimit:
          type: integer
          format: int64
          minimum: 0
          maximum: 999999
          example: 45
          description: |
            The number of reservations that can be made with this coupon code.
        isReservationMandatory:
          type: boolean
          example: true
          description: |
            Indicates whether the code can be redeemed only if it has been reserved first. Codes can be reserved with the Create coupon code reservation effect.
        integrationId:
          type: string
          description: The integration ID of the customer profile. When specified, only that customer will be able to use the coupon.
          example: URNGV8294NV
        startDate:
          type: string
          format: date-time
          description: The start date of the coupon.
          example: 2021-09-30T15:35:02.371569+02:00
        expiryDate:
          type: string
          format: date-time
          description: The expiry date of the coupon.
          example: 2022-02-30T11:00:00.569+02:00
        validCharacters:
          type: array
          items:
            type: string
          description: The list of allowed characters to be used when generating the code.
          example: ["S","U","M","E","R"]
        couponPattern:
          type: string
          description: The coupon pattern to use. Use `#` to represent a random character picked from `validCharacters`.
          example: SUMMER-####-2022
        attributes:
          type: object
          description: Arbitrary properties associated with item.
          example:
            langugae: english
    CouponResponse:
      type: object
      properties:
        ID:
          type: integer
          format: int64
          example: 20190408
        ApplicationID:
          type: integer
          format: int64
          example: 2
        CampaignID:
          type: integer
          format: int64
          example: 30
        Value:
          type: string
          example: SUMMER-####-2022
        DiscountLimit:
          type: integer
          format: int64
          description: The discount amount the coupon is worth. Can be blank if, for example, the coupon provides a 10% discount, or something other than a fixed value of discounts.
          example: 100
        ReservationLimit:
          type: integer
          format: int64
          minimum: 0
          maximum: 999999
          example: 45
          description: The number of reservations that can be made with this coupon code.
        IsReservationMandatory:
          type: boolean
          example: true
          description: |
            Indicates whether the code can be redeemed only if it has been reserved first. Codes can be reserved with the Create coupon code reservation effect.
        StartDate:
          type: string
          format: date-time
          example: 2021-09-30T15:35:02.371569+02:00
        ExpiryDate:
          type: string
          format: date-time
          example: 2022-02-30T11:00:00.569+02:00
        RecipientIntegrationID:
          type: string
          example: URN-GV8294NV
        UsageLimit:
          type: integer
          format: int64
          example: 1
        Attributes:
          type: object
          example:
            language: english

    #######################################
    # Segment Request and Response Models #
    #######################################
    CustomerProfileRequest:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/attributeValuePairs'
        runRuleEngine:
          type: boolean
          default: false
          description: |
            Indicates whether to run the Rule Engine.

            If `true`, the rules are run and their effects are applied, and audience changes are applied.

            If `false`:
            - The rules are not executed.
            - The response time improves.
            - Audience changes are not applied.
          example: false
        audiencesChanges:
          $ref: '#/components/schemas/audienceChange'
    CDPCustomerProfileRequest:
      type: object
      properties:
        attributes:
          type: object
          description: |
            Property to set the attributes of your choice to the values of your choice.
          additionalProperties: true
          example:
            Language: english
            ShippingCountry: DE
            ProductClicked: true
        runRuleEngine:
          type: boolean
          default: false
          description: |
            Indicates whether to run the Rule Engine.

            If `true`, the rules are run and their effects are applied.

            If `false`:
            - The rules are not executed.
            - The response time improves.

            **Note:** If the `audiencesChanges` request parameter is not empty, this value is automatically set to `true`.
          example: false
        audiencesChanges:
          $ref: '#/components/schemas/audienceChange'
    CustomerProfileRequestV2:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/attributeValuePairs'
        runRuleEngine:
          type: boolean
          default: false
          description: |
            Indicates whether to run the Rule Engine.

            If `true`, the rules are run and their effects are applied, and audience changes are applied.

            If `false`:
            - The rules are not executed.
            - The response time improves.
            - Audience changes are not applied.
          example: false
        audiencesChanges:
          $ref: '#/components/schemas/audienceChangeV2'
    CustomerProfilesAudiencesRequest:
      type: object
      properties:
        data:
          type: array
          description: |
            Indicates audience changes for a selected profile.

            **Note:** The total number of `adds` and `deletes` items should be equal to or less than `1000`.
          items:
            $ref: '#/components/schemas/multipleAudienceChanges'
    CustomerProfileResponse:
      type: object
      description: |
        Contains all entities that might interest Talon.One integrations.
      properties:
        customerProfile:
          $ref: '#/components/schemas/customerProfile'
        createdAttributes:
          $ref: '#/components/schemas/multipleAttributes'
    CustomerProfileResponseV2:
      allOf:
        - $ref: '#/components/schemas/CustomerProfileResponse'
        - type: object
          properties:
            audiences:
              type: array
              description: The flat list of audiences in Talon.One used in the request after they were processed.
              items:
                { $ref: '#/components/schemas/MultipleAudiencesItem' }
    MultipleAudiencesItem:
      allOf:
        - $ref: '#/components/schemas/entity'
        - $ref: '#/components/schemas/newAudience'
        - type: object
          required: [ name, integrationId, status ]
          description: |
            Audience item that contains the status of the action applied and its related properties.
          properties:
            status:
              type: string
              description: |
                Indicates whether the audience is new, updated or unmodified by the request.
              enum: ['unmodified' ,'updated', 'new']
              example: new

    CreateAndUpdateAudienceRequest:
      type: object
      required:
        - audienceId
        - audienceName
      properties:
        audienceId:
          $ref: '#/components/schemas/audienceId'
        audienceName:
          $ref: '#/components/schemas/audienceName'
    CreateAndUpdateResponse:
      allOf:
        - $ref: '#/components/schemas/entity'
        - $ref: '#/components/schemas/accountEntity'
        - $ref: '#/components/schemas/newAudience'
    TrackEventRequest:
      type: object
      required:
        - eventType
        - type
        - customerProfileId
      properties:
        eventType:
          type: string
          format: string
          description: The event type, as defined in Talon.One when you created the custom attribute representing this event.
          example: myBrazeEvent
        type:
          type: string
          format: string
          enum: [string, time, number, boolean, location, (list string), (list number), (list time), (list location)]
          description: The data type of the event, as defined in Talon.One when you created the custom attribute representing this event.
          example: string
        eventAttributes:
          $ref: '#/components/schemas/attributeValuePairs'
        customerProfileId:
          $ref: '#/components/schemas/customerProfileID'
    BrazeTrackEventRequest:
      allOf:
        - $ref: '#/components/schemas/TrackEventRequest'
        - type: object
          required:
            - identifier
          properties:
            identifier:
              $ref: '#/components/schemas/identifier'
    SegmentTrackEventV2Request:
      type: object
      required:
        - eventType
      properties:
        eventType:
          type: string
          format: string
          description: The event type, as defined in Talon.One when you created the custom attribute representing this event.
          example: mySegmentEvent
        eventAttributes:
          $ref: '#/components/schemas/attributeValuePairs'
        customerProfileId:
          $ref: '#/components/schemas/customerProfileID'
    SegmentTrackEventRequest:
      allOf:
        - $ref: '#/components/schemas/TrackEventRequest'
        - type: object
          properties:
            attributesInfo:
              $ref: '#/components/schemas/attributesInfo'
    SegmentCustomerProfileRequest:
      allOf:
        - $ref: '#/components/schemas/CustomerProfileRequest'
        - type: object
          properties:
            attributesInfo:
              $ref: '#/components/schemas/attributesInfo'
    SegmentCustomerProfileRequestV2:
      allOf:
        - $ref: '#/components/schemas/CustomerProfileRequestV2'
        - type: object
          properties:
            attributesInfo:
              $ref: '#/components/schemas/attributesInfo'
    SegmentCustomerProfileV2Request:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/attributeValuePairs'
        runRuleEngine:
          type: boolean
          default: false
          description: |
            Indicates whether to run the Rule Engine.

            If `true`, the rules are run and their effects are applied, and audience changes are applied.

            If `false`:
            - The rules are not executed.
            - The response time improves.
            - Audience changes are not applied.
          example: false
        audiencesChanges:
          $ref: '#/components/schemas/audienceChange'
    CustomerProfileIntegrationResponseV2:
      type: object
      description: |
        This is the response type returned by the updateCustomerProfileV2 endpoint.
      required: [ effects, createdCoupons, createdReferrals ]
      properties:
        customerProfile: { $ref: '#/components/schemas/customerProfile' }
        event: { $ref: '#/components/schemas/event' }
        loyalty: { $ref: '#/components/schemas/loyalty' }
        triggeredCampaigns:
          type: array
          items: { $ref: '#/components/schemas/campaign' }
        ruleFailureReasons:
          type: array
          items: { $ref: '#/components/schemas/ruleFailureReason' }
        awardedGiveaways:
          type: array
          items: { $ref: '#/components/schemas/giveaway' }
        effects:
          type: array
          description: The effects generated by the rules in your running campaigns. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          items: { $ref: '#/components/schemas/effect' }
        createdCoupons:
          type: array
          items: { $ref: '#/components/schemas/coupon' }
        createdReferrals:
          type: array
          items: { $ref: '#/components/schemas/referral' }

    LoyaltyResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 302
        title:
          type: string
          example: My loyalty program
        name:
          type: string
          example: myloyaltyprogram
        ledger:
          allOf:
            - $ref: '#/components/schemas/ledgerInfo'
        subLedgers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ledgerInfo'
    UpdateCustomerSessionRequest:
      type: object
      properties:
        customerSession:
          $ref: '#/components/schemas/newCustomerSessionV2'
        sessionAttributesInfo:
          $ref: '#/components/schemas/attributesInfo'
        cartItemAttributesInfo:
          $ref: '#/components/schemas/attributesInfo'
    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: '#/components/schemas/customerSessionV2' }
        customerProfile: { $ref: '#/components/schemas/customerProfile' }
        event:   { $ref: '#/components/schemas/event' }
        loyalty: { $ref: '#/components/schemas/loyalty' }
        referral: { $ref: '#/components/schemas/inventoryReferral' }
        coupons:
          type: array
          items: { $ref: '#/components/schemas/coupon' }
        triggeredCampaigns:
          type: array
          items: { $ref: '#/components/schemas/campaign' }
        effects:
          type: array
          items: { $ref: '#/components/schemas/effect' }
        ruleFailureReasons:
          type: array
          items: { $ref: '#/components/schemas/ruleFailureReason' }
        createdCoupons:
          type: array
          items: { $ref: '#/components/schemas/coupon' }
        createdReferrals:
          type: array
          items: { $ref: '#/components/schemas/referral' }
        awardedGiveaways:
          type: array
          items: { $ref: '#/components/schemas/giveaway' }
        return: { $ref: '#/components/schemas/return' }
        previousReturns:
          type: array
          items: { $ref: '#/components/schemas/return' }

    #########################################
    # mParticle Request and Response Models #
    #########################################
    ModuleRegistrationRequest:
      allOf:
        - $ref: '#/components/schemas/mparticleBaseFields'
        - $ref: '#/components/schemas/mparticleAccount'
    ModuleRegistrationResponse:
      allOf:
        - $ref: '#/components/schemas/mparticleBaseFields'
        - type: object
          properties:
            name:
              type: string
              description: Name of our integration.
              example: Talon.One
            description:
              type: string
              description: Description of our integration.
              example: <a href='https://talon.one'>Talon.One</a> is the world's most flexible Promotion Engine. Create, manage and track coupon codes, discount campaigns, loyalty programs and referrals in one system.
            version:
              type: string
              description: Version of our integration.
              example: 0.0.1
            permissions:
              $ref: '#/components/schemas/mparticlePermissions'
            audience_processing_registration:
              $ref: '#/components/schemas/mparticleAudienceProcessingRegistration'
            event_processing_registration:
              $ref: '#/components/schemas/mparticleEventProcessingRegistration'
    AudienceMembershipChangeRequest:
      allOf:
        - $ref: '#/components/schemas/mparticleBaseFields'
        - $ref: '#/components/schemas/mparticleAccount'
        - type: object
          properties:
            user_profiles:
              type: array
              description: The list of user profiles.
              items:
                $ref: '#/components/schemas/mparticleUserProfiles'
    AudienceMembershipChangeResponse:
      $ref: '#/components/schemas/mparticleBaseFields'
    AudienceSubscriptionRequest:
      allOf:
        - $ref: '#/components/schemas/mparticleBaseFields'
        - $ref: '#/components/schemas/mparticleAccount'
        - type: object
          required:
            - audience_id
            - audience_name
          properties:
            audience_id:
              type: integer
              description: Audience id
              example: 29
            audience_name:
              type: string
              description: Audience name
              example: Travel audience
            action:
              description: Audience action
              example: add
              enum:
                - add
                - update
                - remove
            audience_subscription_settings:
              type: object
              additionalProperties: false
            user_attributes:
              type: array
              items:
                $ref: '#/components/schemas/mparticleUserAttribute'
    AudienceSubscriptionResponse:
      allOf:
        - $ref: '#/components/schemas/mparticleBaseFields'
        - type: object
          properties:
            audience_subscription_settings:
              type: object
              additionalProperties: true
    EventProcessingRequest:
      allOf:
        - $ref: '#/components/schemas/mparticleBaseFields'
        - $ref: '#/components/schemas/mparticleAccount'
        - $ref: '#/components/schemas/mparticleUserIdentityInt'
        - type: object
          required:
            - mpid
          properties:
            user_identities:
              type: array
              items:
                $ref: '#/components/schemas/mparticleUserIdentity'
            mpid:
              type: string
              description: mparticle id
              example: 6423PSJVY7492
            user_attributes:
              type: array
              items:
                $ref: '#/components/schemas/mparticleUserAttribute'
            events:
              type: array
              items:
                $ref: '#/components/schemas/mparticleEvent'
    EventProcessingResponse:
      $ref: '#/components/schemas/mparticleBaseFields'

    #########################################
    # Emarsys Request and Response Models #
    #########################################
    EmarsysCouponRequest:
      type: object
      required: [fields, limit, parameters]
      properties:
        parameters:
          type: array
          items:
            properties:
              campaignId:
                type: string
                description: The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.
                example: "34"
              integrationId:
                type: string
                description: The integration ID of the customer profile.
                example: URNGV8294NV
        fields:
          type: array
          description: |
            Any additional data we want in the response.

            **Note:** For the supported `fields`, see the [List customer data](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/getCustomerInventory) response (any nested arrays and objects are discarded from the response).
            In addition to this, custom attributes are supported.
          example: ["id", "created"]
          items:
            type: string
        limit:
          type: number
          minimum: 0
          example: 1000
          description: The value to set for the limit.
    EmarsysCouponResponse:
      properties:
        content:
          type: array
          description: |
            The relevant coupon-related content, including the properties passed in the `fields` array of the request.
          items:
            type: object
            required:
              - campaignId
              - integrationId
            properties:
              campaignId:
                type: string
                description: The ID of the campaign in Talon.One. It is displayed in your Talon.One deployment URL.
                example: "34"
              integrationId:
                type: string
                description: The integration ID of the customer profile.
                example: URNGV8294NV

    ###############################################
    # Reusable models for Requests and Responses  #
    ###############################################
    id:
      type: integer
      title: ID
      description: Unique ID for this entity.
      format: int64
      example: 6
      minimum: 1
    audienceId:
      type: string
      format: string
      minLength: 1
      maxLength: 1000
      description: The ID of this audience. If the audience comes from a third-party platform, set this property to the ID given by the third-party platform.
      example: 382370BKDB946
    audienceName:
      type: string
      format: string
      maxLength: 1000
      minLength: 1
      description: The human-friendly display name for this audience.
      example: Travel audience
    newAudience:
      type: object
      required:
        - name
      properties:
        name:
          $ref: '#/components/schemas/audienceName'
        integration:
          type: string
          description: The third-party platform that this audience was created in.
          example: My platform name
        integrationId:
          $ref: '#/components/schemas/audienceId'
    event:
      allOf:
        - $ref: '#/components/schemas/entity'
        - $ref: '#/components/schemas/applicationEntity'
        - $ref: '#/components/schemas/integrationEvent'
        - type: object
          required:
            - effects
            - ledgerEntries
          properties:
            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" that must be applied in response to this event.
                See the list of [effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
              items:
                type: array
                example:
                  [
                    4208,
                    20095,
                    0,
                    ['showNotification', 'Info', 'My title', 'My content'],
                  ]
            ledgerEntries:
              type: array
              description: Ledger entries for the event.
              items:
                $ref: '#/components/schemas/ledgerEntry'
            meta:
              $ref: '#/components/schemas/meta'
    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: '#/components/schemas/couponRejectionReason'
        referralRejectionReason:
          $ref: '#/components/schemas/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
          example: 20
        referralId:
          type: integer
          example: 4
        reason:
          type: string
          example: ReferralNotFound
          enum:
            [
              'ReferralNotFound',
              'ReferralRecipientIdSameAsAdvocate',
              'ReferralPartOfNotRunningCampaign',
              'ReferralLimitReached',
              'CampaignLimitReached',
              'ProfileLimitReached',
              'ReferralRecipientDoesNotMatch',
              'ReferralExpired',
              'ReferralStartDateInFuture',
              'ReferralRejectedByCondition',
              'EffectCouldNotBeApplied',
            ]
    ledgerEntry:
      allOf:
        - $ref: '#/components/schemas/entity'
        - $ref: '#/components/schemas/integrationProfileEntity'
        - type: object
          description: Entry in the point ledger
          required:
            - eventId
            - accountId
            - profileId
            - loyaltyProgramId
            - amount
            - reason
            - expiryDate
          properties:
            accountId:
              type: integer
              description: The ID of the Talon.One account that owns this profile.
              example: 23
            loyaltyProgramId:
              type: integer
              description: ID of the ledger
              example: 323414846
            eventId:
              type: integer
              description: ID of the related event
              example: 3
            amount:
              type: integer
              description: Amount of loyalty points
              example: 100
            reason:
              type: string
              description: reason for awarding/deducting points
              example: customer appeasment
            expiryDate:
              type: string
              format: date-time
              description: Expiry date of the points
              example: 2021-06-10T09:05:27.993483Z
            referenceId:
              type: integer
              description: The ID of the balancing ledgerEntry
              example: 5
    applicationEntity:
      type: object
      required:
        - applicationId
      properties:
        applicationId:
          type: integer
          description: The ID of the application that owns this entity.
          example: 322
    integrationEvent:
      allOf:
        - $ref: '#/components/schemas/integrationProfileEntity'
        - type: object
          properties:
            type:
              type: string
              title: Event Type
              description: A string representing the event. Must not be a reserved event name.
              minLength: 1
              example: pageViews
            attributes:
              $ref: '#/components/schemas/attributeValuePairs'
          required:
            - type
            - attributes
    integrationProfileEntity:
      type: object
      properties:
        profileId:
          type: string
          description: |
            ID of the customers profile as used within this Talon.One account.
          example: URN-GV8294NV
    customerProfile:
      allOf:
        - $ref: '#/components/schemas/entity'
        - $ref: '#/components/schemas/accountEntity'
        - properties:
            attributes:
              $ref: '#/components/schemas/attributeValuePairs'
            integrationId:
              type: string
              format: string
              example: URNGV8294NV
              maxLength: 1000
              description: The integration ID for this entity sent to and used in the Talon.One system.
            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
            audienceMemberships:
              type: array
              description: A list of audiences the customer belongs to
              items:
                type: object
                required:
                  - id
                  - name
                properties:
                  id:
                    $ref: '#/components/schemas/id'
                  name:
                    type: string
                    title: Audience Name
                    description: The Name of the audience belonging to this entity.
                    example: audience1
              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
    addAudienceIds:
      type: array
      description: The IDs of the audiences for the customer to join.
      example: [1, 2, 3]
      items:
        $ref: '#/components/schemas/id'
    deleteAudienceIds:
      type: array
      description: The IDs of the audiences for the customer to leave.
      example: [4, 5, 6]
      items:
        $ref: '#/components/schemas/id'
    addAudienceItems:
      type: array
      description: The audiences for the customer to join.
      items:
        $ref: '#/components/schemas/audienceItem'
    deleteAudienceItems:
      type: array
      description: The audiences for the customer to leave.
      items:
        $ref: '#/components/schemas/audienceItem'
    audienceItem:
      type: object
      required:
        - name
      properties:
        integrationId:
          type: string
          minLength: 1
          description: |
            The integration ID of the audience. You can either use an existing audience ID, or assign a new one.

            When you specify a new integration ID with this property, all A-Z, a-z and 0-9 characters are
            preserved and all other characters are replaced by `_`. For example, `My Travel audience1` becomes `My_Travel_audience1`
          example: My_Travel_audience1
        name:
          type: string
          title: Audience Name
          description: The name of the audience belonging to this entity.
          example: Travel audience 18-25
    attributeValuePairs:
      type: object
      description: |
        Property to set the attributes of your choice to the values of your choice.

        New attributes are created automatically. For more information, see [Attributes](https://docs.talon.one/docs/dev/concepts/attributes).
      additionalProperties: true
      example:
        Language: english
        ShippingCountry: DE
        ProductClicked: true
    multipleAttributes:
      type: array
      items:
        $ref: '#/components/schemas/attribute'
    attribute:
      allOf:
        - $ref: '#/components/schemas/entity'
        - $ref: '#/components/schemas/accountEntity'
        - type: object
          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',
                ]
              example: CustomerProfile
            eventType:
              type: string
              example: event
            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.
              example: country
            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.
              example: Country
            type:
              type: string
              enum: [string, time, number, boolean, location, (list string), (list number), (list time), (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.
              example: string
            description:
              type: string
              description: A description of this attribute.
              example: a description
            suggestions:
              type: array
              description: A list of suggestions for the attribute.
              maxItems: 50
              example: ['suggestion1', 'suggestion2']
              items:
                type: string
                minLength: 1
                example: suggestion
            hasAllowedList:
              type: boolean
              description: Whether or not this attribute has an allowed list of values associated with it.
              default: false
              example: 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
              example: false
            editable:
              type: boolean
              description: Whether or not this attribute can be edited.
              example: false
            subscribedApplicationsIds:
              type: array
              description: A list of the IDs of the applications that are subscribed to this attribute
              example: [10, 20, 100]
              items:
                type: integer
            eventTypeId:
              type: integer
              format: int64
              example: 22
    multipleAudienceChanges:
      allOf:
        - $ref: '#/components/schemas/audienceChange'
        - type: object
          properties:
            customerProfileId:
              $ref: '#/components/schemas/customerProfileID'
    customerProfileID:
      type: string
      format: string
      example: URN-GV8294NV
      maxLength: 1000
      description: Unique Customer Profile ID.
    audienceChange:
      type: object
      description: A list of audiences where the customer should be removed or added.
      properties:
        adds:
          $ref: '#/components/schemas/addAudienceIds'
        deletes:
          $ref: '#/components/schemas/deleteAudienceIds'
    audienceChangeV2:
      type: object
      properties:
        adds:
          $ref: '#/components/schemas/addAudienceItems'
        deletes:
          $ref: '#/components/schemas/deleteAudienceItems'
    accountEntity:
      type: object
      required:
        - accountId
      properties:
        accountId:
          $ref: '#/components/schemas/id'
    entity:
      type: object
      required:
        - id
        - created
      properties:
        id:
          $ref: '#/components/schemas/id'
        created:
          type: string
          format: date-time
          description: The moment this entity was created.
          example: 2020-06-10T09:05:27.993483Z
    ledgerInfo:
      type: object
      properties:
        currentBalance:
          type: number
          example: 10.5
        pendingBalance:
          type: number
          example: 5.1
        expiredBalance:
          type: number
          example: 2
        spentBalance:
          type: number
          example: 0
        tentativeCurrentBalance:
          type: number
          example: 0
        pointsToNextTier:
          type: number
          example: 10
        currentTier:
          type: object
          properties:
            id:
              type: integer
              format: int64
              example: 112345
            name:
              type: string
              example: silver-tier
    mparticlePermissions:
      type: object
      description: Permissions indicates which identities we require access to.
      properties:
        allow_consent_state:
          type: boolean
          example: true
        allow_access_mpid:
          type: boolean
          example: true
        allow_user_attributes:
          type: boolean
          example: true
        allow_audience_user_attributes:
          type: boolean
          example: true
        user_identities:
          type: array
          items:
            $ref: '#/components/schemas/mparticleUserIdentity'
    mparticleAudienceProcessingRegistration:
      type: object
      description: AudienceSubscriptionSettings define client configuration that we require.
      properties:
        account_settings:
          type: array
          items:
            $ref: '#/components/schemas/mparticleAccountSettings'
        audience_subscription_settings:
          type: array
          items:
            $ref: '#/components/schemas/mparticleAudienceSubscriptionSettings'
    mparticleAudienceSubscriptionSettings:
      type: object
      description: AudienceSubscriptionSetting represents a audience-specific configuration.
      properties:
        type:
          type: string
          example: integer
        id:
          type: string
          example: t1AudienceID
        name:
          type: string
          example: Talon.One Audience ID
        visible:
          type: boolean
          example: false
        required:
          type: boolean
          example: false
    mparticleAccountSettings:
      type: object
      description: AccountSetting represents configuration to be set by the client.
      properties:
        type:
          type: string
          example: text
        id:
          type: string
          example: deploymentURL
        name:
          type: string
          example: Deployment URL
        description:
          type: string
          example: URL of your Talon.One deployment
        visible:
          type: boolean
          example: true
        required:
          type: boolean
          example: true
        confidential:
          type: boolean
          example: true
        default_value:
          type: string
          example: ''
    mparticleEventProcessingRegistration:
      type: object
      description: EventProcessingRegistration defines our required configuration from the client.
      properties:
        account_settings:
          type: array
          items:
            $ref: '#/components/schemas/mparticleAccountSettings'
        supported_event_types:
          type: array
          items:
            type: string
            example: custom_event
        supported_runtime_environments:
          type: array
          items:
            type: string
            example: android
        supported_system_notification_types:
          type: array
          items:
            type: string
        max_data_age_hours:
          type: integer
          example: -1
    firehoseVersion:
      type: string
      description: mParticle's internal API version.
      example: 2.4.0
    timestampMS:
      type: integer
      description: Timestamp of the request (in milliseconds)
      example: 1586980879793
    mparticleType:
      type: string
      description: The type of request/event coming from mParticle.
      example: module_registration_request
      enum:
        - module_registration_request
        - audience_subscription_request
        - event_processing_request
        - audience_membership_change_request
    mparticleId:
      type: string
      description: The ID that is set by mParticle to identify this request.
      example: dd33f-dd-b3fb3-def0000
    mparticleUserIdentity:
      type: object
      properties:
        type:
          type: string
          enum:
            - email
            - customerId
            - mpid
            - customer
          example: customerId
        encoding:
          type: string
          example: raw
        required:
          type: boolean
          example: true
        value:
          type: string
          example: ''
    mparticleUserIdentityInt:
      type: integer
      properties:
        type:
          type: string
          example: RGV6358UYY
    mparticleAudience:
      type: object
      required:
        - action
        - audience_id
        - audience_name
      properties:
        audience_id:
          type: integer
          description: Audience id
          example: 234
        audience_name:
          type: string
          description: Audience name
          example: Travel audience
        action:
          $ref: '#/components/schemas/actionMembershipChange'
        audience_subscription_settings:
          type: object
          description: Settings contains custom configuration per audience.
          additionalProperties: true
        user_attributes:
          type: array
          items:
            $ref: '#/components/schemas/mparticleUserAttribute'
    actionMembershipChange:
      type: string
      description: Audience action
      example: add
      enum:
        - add
        - delete
        - attribute_update
    mparticleUserAttribute:
      type: object
      properties:
        key:
          type: string
          example: country
        value:
          example: DE
        action:
          type: string
          example: upsert
          enum:
            - upsert
            - delete
    mparticleAccount:
      type: object
      properties:
        account:
          type: object
          properties:
            account_id:
              type: integer
              description: mParticle account ID
              example: 1234567
            account_settings:
              type: object
              required:
                - apiKey
                - deploymentURL
                - userIdField
              properties:
                apiKey:
                  type: string
                  description: mParticle api key
                  example: someapikey
                deploymentURL:
                  type: string
                  description: The base URL of your Talon.One deployment
                  example: mycompany.europe-west1.talon.one
                userIdField:
                  type: string
                  description: how to identify customer profiles
                  example: email
                  enum:
                    - email
                    - customerId
                    - mpid
                runRuleEngine:
                  type: boolean
                  description: whether to run the Rule Engine
                  example: false
    mparticleEvent:
      type: object
      required:
        - name
        - type
        - session_id
      properties:
        name:
          type: string
          description: The name of the event
          example: isDogLover
        type:
          type: string
          description: The type of the event
          enum:
            - custom_event
          example: custom_event
        session_id:
          type: integer
          description: The session ID of the event
          example: 109
        id:
          type: string
          description: Unique id for this entity
          example: 342PV86540CR
        source_id:
          type: string
          description: The source ID of the event
          example: B5720CRPPN7
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/mparticleUserAttribute'
    mparticleBaseFields:
      type: object
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/mparticleType'
        id:
          $ref: '#/components/schemas/mparticleId'
        timestamp_ms:
          $ref: '#/components/schemas/timestampMS'
        firehose_version:
          $ref: '#/components/schemas/firehoseVersion'
    mparticleUserProfiles:
      type: object
      required:
        - mpid
      properties:
        mpid:
          type: string
          description: mParticle ID
          example: c314b207-f3ae-4d21-9ae7-5983af40876a
        audiences:
          type: array
          items:
            $ref: '#/components/schemas/mparticleAudience'
        user_identities:
          type: array
          items:
            $ref: '#/components/schemas/mparticleUserIdentity'
    identifier:
      type: string
      minLength: 1
      description: |
        The identifier of the request. Providing a new value sends a new event to Talon.One. Providing an existing value retrieves the existing event of that id.

        In general, you should set it to a `dispatch_id` variable controlled by Braze.

        See [dispatch ID](https://www.braze.com/docs/help/help_articles/data/dispatch_id/) behavior.
      example: NNjETb6XxDV7hQhLMA
    attributeInfo:
      type: object
      properties:
        name:
          type: string
          description: Attribute name
          example: ProductClicked
        type:
          type: string
          enum: [string, time, number, boolean, location]
          description: The data type of the attribute. When using `time`, send the attribute value as a string conforming to the [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) timestamp format.
          example: boolean
    attributesInfo:
      description: |
        Allows you to set the type of the attribute to create instead of relying on auto-type detection.

        For example, if you have a `hasClickedProduct` attribute set to `false` (boolean) in the `attributes` property,
        it will be created as `boolean` automatically. But to force it to be of type `string`,
        use the `attributesInfo` field to declare it at as a `string`.

        **Note:** List types cannot be converted. A `listOfSomething` attribute set to `(list string)` type,)
        must not be declared as `string` in `attributesInfo` field.
      type: array
      items:
        $ref: '#/components/schemas/attributeInfo'
    newCustomerSessionV2:
      allOf:
        - { $ref: '#/components/schemas/integrationProfileEntity' }
        - type: object
          properties:
            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](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).
              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: '#/components/schemas/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: '#/components/schemas/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"
    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: '#/components/schemas/additionalCost'
          example:
            shipping:
              price: 9
    additionalCost:
      type: object
      required: [ price ]
      properties:
        price:
          title: Price of additional cost
          type: number
          example: 4.5
    return:
      allOf:
        - { $ref: '#/components/schemas/entity' }
        - { $ref: '#/components/schemas/applicationEntity' }
        - { $ref: '#/components/schemas/accountEntity' }
        - { $ref: '#/components/schemas/newReturn' }
        - type: object
          required: [ eventId, sessionId, sessionIntegrationId ]
          properties:
            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
    newReturn:
      type: object
      required: [ returnedCartItems ]
      properties:
        returnedCartItems:
          type: array
          description: List of cart items to be returned.
          items: { $ref: '#/components/schemas/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
    giveaway:
      allOf:
        - { $ref: '#/components/schemas/entity' }
        - type: object
          required: [ id, created, code, poolId ]
          properties:
            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.
    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.
    inventoryReferral:
      allOf:
        - { $ref: '#/components/schemas/referral' }
        - type: object
          x-attributable: true
          required:
            - referredCustomers
          properties:
            referredCustomers:
              type: array
              description: An array of referred customers.
              items: { type: string }
    customerSessionV2:
      allOf:
        - { $ref: '#/components/schemas/entity' }
        - { $ref: '#/components/schemas/integrationEntity' }
        - { $ref: '#/components/schemas/applicationEntity' }
        - { $ref: '#/components/schemas/newCustomerSessionV2' }
        - type: object
          x-attributable: true
          properties:
            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"
          # these inherited properties are intentionally made required here so
          # that we can validate they are present (but possibly empty) in API responses
          required:
            - profileId
            - firstSession
            - coupon
            - referral
            - state
            - cartItems
            - integrationId
            - applicationId
            - attributes
            - total
            - cartItemTotal
            - additionalCostTotal
            - updated
    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"
    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: '#/components/schemas/loyaltyCard' }
        programs:
          type: object
          title: Customer's current loyalty program balance.
          description: Displays information about point balances in profile-based programs.
          additionalProperties:
            $ref: '#/components/schemas/loyaltyProgramLedgers'
    loyaltyCard:
      allOf:
        - { $ref: '#/components/schemas/entity' }
        - { $ref: '#/components/schemas/loyaltyProgramEntity' }
        - { $ref: '#/components/schemas/updateLoyaltyCard' }
        - type: object
          required: [ identifier, usersPerCardLimit ]
          properties:
            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: '#/components/schemas/loyaltyCardProfileRegistration'
            ledger:
              $ref: '#/components/schemas/ledgerInfo'
            subledgers:
              type: object
              description: Displays point balances of the card in the subledgers of the loyalty program.
              additionalProperties:
                $ref: '#/components/schemas/ledgerInfo'
            modified:
              type: string
              format: date-time
              description: Timestamp of the most recent update of the loyalty card.
              example: "2021-09-12T10:12:42Z"
    loyaltyProgramEntity:
      type: object
      required: [ programID ]
      properties:
        programID:
          type: integer
          description: The ID of the loyalty program that owns this entity.
          example: 125
    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"
    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:
          $ref: '#/components/schemas/ledgerInfo'
        subLedgers:
          type: object
          description: A map containing information about each loyalty subledger.
          additionalProperties:
            $ref: '#/components/schemas/ledgerInfo'
    campaign:
      allOf:
        - { $ref: '#/components/schemas/entityWithTalangVisibleID' }
        - { $ref: '#/components/schemas/applicationEntity' }
        - { $ref: '#/components/schemas/userEntity' }
        - { $ref: '#/components/schemas/newCampaign' }
        - type: object
          properties:
            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
          required: [ state, description ]
    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: '#/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
      required:
        - name
        - state
        - tags
        - limits
        - features
    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
    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.
    userEntity:
      type: object
      required: [ userId ]
      properties:
        userId:
          type: integer
          description: The ID of the account that owns this entity.
    referral:
      allOf:
        - { $ref: '#/components/schemas/entity' }
        - { $ref: '#/components/schemas/newReferral' }
        - { $ref: '#/components/schemas/importEntity' }
        - type: object
          x-attributable: true
          required:
            - code
            - usageCounter
            - usageLimit
          properties:
            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
    newReferral:
      allOf:
        - { $ref: '#/components/schemas/referralConstraints' }
        - type: object
          required:
            - campaignId
            - advocateProfileIntegrationId
          properties:
            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
    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
    importEntity:
      type: object
      required: [ id ]
      properties:
        importId:
          type: integer
          description:  The ID of the Import which created this referral.
    coupon:
      allOf:
        - { $ref: '#/components/schemas/entity' }
        - { $ref: '#/components/schemas/campaignEntity' }
        - { $ref: '#/components/schemas/couponValue' }
        - { $ref: '#/components/schemas/couponConstraints' }
        - { $ref: '#/components/schemas/couponLimitConfigs' }
        - type: object
          x-attributable: true
          required:
            - value
            - usageCounter
            - usageLimit
          properties:
            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
    campaignEntity:
      type: object
      required: [ campaignId ]
      properties:
        campaignId:
          type: integer
          title: Campaign ID
          description: The ID of the campaign that owns this entity.
          example: 211
    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.
    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: '#/components/schemas/limitConfig' }
    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
            # The campaign entity is intentionally left out of this enum, as for the moment
            # it is always implicitly added on the Backend for all limit configurations.
            enum: [Coupon, Referral, Profile, Identifier]
    effect:
      allOf:
        - {  $ref: '#/components/schemas/effectEntity' }
        - type: object
          description: A generic effect that is fired by a triggered campaign. The props property will contain information specific to the specific effect type.
          required: [ props ]
          properties:
            props: { $ref: '#/components/schemas/effectProps' }
    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
      oneOf:
        - { $ref: '#/components/schemas/acceptCouponEffectProps' }
        - { $ref: '#/components/schemas/acceptReferralEffectProps' }
        - { $ref: '#/components/schemas/redeemReferralEffectProps' }
        - { $ref: '#/components/schemas/rejectCouponEffectProps' }
        - { $ref: '#/components/schemas/rejectReferralEffectProps' }
        - { $ref: '#/components/schemas/couponCreatedEffectProps' }
        - { $ref: '#/components/schemas/referralCreatedEffectProps' }
        - { $ref: '#/components/schemas/setDiscountEffectProps' }
        - { $ref: '#/components/schemas/setDiscountPerItemEffectProps' }
        - { $ref: '#/components/schemas/setDiscountPerAdditionalCostEffectProps' }
        - { $ref: '#/components/schemas/triggerWebhookEffectProps' }
        - { $ref: '#/components/schemas/addLoyaltyPointsEffectProps' }
        - { $ref: '#/components/schemas/deductLoyaltyPointsEffectProps' }
        - { $ref: '#/components/schemas/addFreeItemEffectProps' }
        - { $ref: '#/components/schemas/showNotificationEffectProps' }
        - { $ref: '#/components/schemas/updateAttributeEffectProps' }
        - { $ref: '#/components/schemas/rollbackCouponEffectProps' }
        - { $ref: '#/components/schemas/rollbackReferralEffectProps' }
        - { $ref: '#/components/schemas/rollbackDiscountEffectProps' }
        - { $ref: '#/components/schemas/rollbackAddedLoyaltyPointsEffectProps' }
        - { $ref: '#/components/schemas/rollbackDeductedLoyaltyPointsEffectProps' }
        - { $ref: '#/components/schemas/showBundleMetadataEffectProps' }
        - { $ref: '#/components/schemas/awardGiveawayEffectProps' }
        - { $ref: '#/components/schemas/willAwardGiveawayEffectProps' }
        - { $ref: '#/components/schemas/errorEffectProps' }
        - { $ref: '#/components/schemas/customEffectProps' }
        - { $ref: '#/components/schemas/setDiscountPerAdditionalCostPerItemEffectProps' }

    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.
    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 (string, time, number, boolean, location, (list string), (list number), (list time), (list location)) 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
    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.

    ########################
    # Error Response Model #
    ########################
    errorResponseWithStatus:
      type: object
      properties:
        StatusCode:
          type: integer
          description: The error code
          example: 404
        Error:
          type: string
          example: Not found
        RequestUUID:
          type: string
          example: 51fad142-3563-4fe2-b4aa-41ab20be31d911

  examples:
    HealthResponse:
      x-internal: true
      value:
        Status: OK
        Commit: df532a0dce4902db7f81bc190216309bc9da61cc
        Version: 0.0.141
        Date: 2023-11-08T09:24:10Z
    CouponRequest:
      value:
        deploymentUrl: mycompany.europe-west1.talon.one
        applicationId: 398
        campaignId: 5671
        identifier: test-coupon
        usageLimit: 4
        discountLimit: 30
        reservationLimit: 45
        integrationId: URN-GV8294NV
        startDate: 2021-09-30T15:35:02.371569+02:00
        expiryDate: 2024-10-03T15:35:02.371569+02:00
        validCharacters: ['A', 'B', 'C', '1', '2']
        couponPattern: ew-####
        attributes:
          venueId: BER4271
          venueName: Admiralspalast
    CouponResponse:
      value:
        ID: 20190408
        ApplicationID: 398
        CampaignID: 5671
        Value: EW-1BC2
        StartDate: 2021-09-30T15:35:02.371569+02:00
        ExpiryDate: 2024-10-03T15:35:02.371569+02:00
        RecipientIntegrationID: URN-GV8294NV
        UsageLimit: 1
        Attributes:
          email: user@mailbox.com
          country: DE
    EmarsysCouponResponse:
      value:
        content:
          - integrationId: test-user-4zoj1c
            campaignId: '8431'
            id: 26443683
            created: 2024-01-03T11:28:25.648154Z
            value: QQ4R-C3BQ
            usageLimit: 1
            usageCounter: 0
            recipientIntegrationId: test-user-4zoj1c
            reservation: false
            batchId: qndflqqd
            profileRedemptionCount: 0
            state: active
    ReferralRequest:
      value:
        deploymentUrl: mycompany.europe-west1.talon.one
        campaignId: 5672
        advocateProfileIntegrationId: '2'
        friendProfileIntegrationId: '3'
        startDate: 2021-09-30T15:35:02.371569+02:00
        expiryDate: 2021-10-03T15:35:02.371569+02:00
        usageLimit: 3
        attributes:
          welcome_message: Welcome!
    ReferralResponse:
      value:
        id: 1374
        created: 2022-04-01T16:46:36.625152002Z
        startDate: 2021-09-30T15:35:02.371569+02:00
        expiryDate: 2021-10-03T15:35:02.371569+02:00
        usageLimit: 0
        campaignId: 5672
        advocateProfileIntegrationId: URN-GV8294NV
        friendProfileIntegrationId: PKBR-G06449OELK
        attributes:
          welcome_message: Welcome!
        code: P8BN-4T5V
        usageCounter: 0
    AudienceSubscriptionRequest:
      value:
        type: audience_subscription_request
        id: deadb33f-dead-b33f-b33f-deadbeef0000
        timestamp_ms: 1586980879793
        firehose_version: 2.4.0
        account:
          account_id: 1234567
          account_settings:
            apiKey: someapikey
            deploymentURL: mycompany.europe-west1.talon.one
            userIdField: email
        audience_id: 234
        audience_name: Travel audience
        action: add
        audience_subscription_settings:
          custuomField: 1
        user_attributes:
          - key: email
            value: test@email.com
    AudienceMembershipChangeRequest:
      value:
        type: audience_membership_change_request
        id: deadb33f-dead-b33f-b33f-deadbeef0000
        timestamp_ms: 1586980879793
        firehose_version: 2.4.0
        account:
          account_id: 1234567
          account_settings:
            apiKey: someapikey
            deploymentURL: mycompany.europe-west1.talon.one
            userIdField: customerId
            runRuleEngine: true
        user_profiles:
          - mpid: c314b207-f3ae-4d21-9ae7-5983af40876a
            audiences:
              - audience_id: 234
                audience_name: Travel audience
                action: add
                user_attributes:
                  - key: customerId
                    value: customer3
                    action: upsert
            user_identities:
              - type: customerId
                encoding: raw
                required: true
                value: ''
    EventProcessingRequest:
      value:
        type: event_processing_request
        id: deadb33f-dead-b33f-b33f-deadbeef0000
        timestamp_ms: 1586980879793
        firehose_version: 2.4.0
        account:
          account_id: 1234567
          account_settings:
            apiKey: someapikey
            deploymentURL: mycompany.europe-west1.talon.one
            userIdField: customerId
        user_identities:
          - type: customerId
            encoding: raw
            required: true
            value: ''
        mpid: c314b207-f3ae-4d21-9ae7-5983af40876a
        events:
          - name: isDogLover
            type: custom_event
            session_id: 109
    ModuleRegistrationRequest:
      value:
        type: module_registration_request
        id: deadb33f-dead-b33f-b33f-deadbeef0000
        timestamp_ms: 1586980879793
        firehose_version: 2.4.0
        account:
          account_id: 1234567
          account_settings:
            apiKey: someapikey
            deploymentURL: mycompany.europe-west1.talon.one
            userIdField: email
    EventProcessingResponse:
      value:
        type: event_processing_response
        id: deadb33f-dead-b33f-b33f-deadbeef0000
        timestamp_ms: 1586980879793
        firehose_version: 2.4.0
    AudienceSubscriptionResponse:
      value:
        type: audience_subscription_response
        id: deadb33f-dead-b33f-b33f-deadbeef0000
        timestamp_ms: 1586980879793
        firehose_version: 2.4.0
    AudienceMembershipChangeResponse:
      value:
        type: audience_membership_change_response
        id: deadb33f-dead-b33f-b33f-deadbeef0000
        timestamp_ms: 1586980879793
        firehose_version: 2.4.0
    ModuleRegistrationResponse:
      value:
        type: module_registration_response
        id: deadb33f-dead-b33f-b33f-deadbeef0000
        timestamp_ms: 1586980879793
        firehose_version: 2.4.0
        name: Talon.One
        description: <a href='https://talon.one'>Talon.One</a> is the world's most flexible Promotion Engine. Create, manage and track coupon codes, discount campaigns, loyalty programs and referrals in one system.
        version: 0.0.1
        permissions:
          allow_consent_state: true
          allow_access_mpid: true
          allow_user_attributes: true
          allow_audience_user_attributes: true
          user_identities:
            - type: email
              encoding: raw
              required: false
              value: ''
            - type: customer
              encoding: raw
              required: false
              value: ''
        audience_processing_registration:
          account_settings:
            - type: text
              id: deploymentURL
              name: Deployment URL
              description: URL of your Talon.One deployment
              visible: true
              required: true
              confidential: true
              default_value: ''
            - type: text
              id: apiKey
              name: API Key
              description: API Key to be used for requests to your Talon.One deployment
              visible: true
              required: true
              confidential: true
              default_value: ''
            - type: text
              id: userIdField
              name: User ID
              description: Select which user identity to forward to Talon.One as your customer's user ID.
              visible: true
              required: true
              confidential: true
              default_value: customerId
            - type: boolean
              id: runRuleEngine
              name: Run Rule Engine
              description: Dictates whether the Rule Engine should be run after each membership change.
              visible: true
              required: true
              confidential: false
              default_value: false
          audience_subscription_settings:
            - type: integer
              id: t1AudienceID
              name: Talon.One Audience ID
              visible: false
              required: false
        event_processing_registration:
          account_settings:
            - type: text
              id: deploymentURL
              name: Deployment URL
              description: URL of your Talon.One deployment
              visible: true
              required: true
              confidential: true
              default_value: ''
            - type: text
              id: apiKey
              name: API Key
              description: API Key to be used for requests to your Talon.One deployment
              visible: true
              required: true
              confidential: true
              default_value: ''
            - type: text
              id: userIdField
              name: User ID
              description: Select which user identity to forward to Talon.One as your customer's user ID.
              visible: true
              required: true
              confidential: true
              default_value: customerId
            - type: boolean
              id: runRuleEngine
              name: Run Rule Engine
              description: Dictates whether the Rule Engine should be run after each membership change.
              visible: true
              required: true
              confidential: false
              default_value: false
          supported_event_types:
            - custom_event
          supported_runtime_environments:
            - unknown
            - android
            - ios
            - tvos
            - mobileweb
            - roku
            - xbox
            - firetv
            - alexa
            - smarttv
          supported_system_notification_types: []
          max_data_age_hours: -1
    SegmentTrackEventRequest:
      value:
        customerProfileId: "URN-GV8294NV"
        eventType: mySegmentEvent
        type: string
        eventAttributes:
          Language: english
          ShippingCountry: DE
          ProductClicked: true
        attributesInfo:
          - name: ProductClicked
            type: boolean
    SegmentCustomerProfileRequest:
      value:
        runRuleEngine: false
        audiencesChanges:
          adds: [1,2,3]
          deletes: [4,5,6]
        attributes:
          Language: english
          ShippingCountry: DE
          ProductClicked: true
        attributesInfo:
          - name: ProductClicked
            type: boolean

  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponseWithStatus'
          examples:
            default:
              value:
                StatusCode: 400
                Error: No Deployment URL specified
                RequestUUID: fd2f7c55-d064-46e1-ab87-a39cb877cd82
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponseWithStatus'
          examples:
            default:
              value:
                StatusCode: 401
                Error: Missing Session Token
                RequestUUID: fd2f7c55-d064-46e1-ab87-a39cb877cd82
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponseWithStatus'
          examples:
            default:
              value:
                StatusCode: 404
                Error: Not Found
                RequestUUID: fd2f7c55-d064-46e1-ab87-a39cb877cd82
    AudienceAlreadyExist:
      description: The audience with the ID already exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponseWithStatus'
          examples:
            default:
              value:
                StatusCode: 409
                Error: The audience with the ID '382370BKDB946' already exists
                RequestUUID: 80322e41-d7d2-48eb-b6c5-c458e13b4b65
    TooManyRequests:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponseWithStatus'
          examples:
            default:
              value:
                StatusCode: 429
                Error: Too many requests
                RequestUUID: fd2f7c55-d064-46e1-ab87-a39cb877cd82
    SegmentTooManyRequestsOrParallel:
      description: Rate limit of 60 requests per second exceeded or too many [parallel requests](https://docs.talon.one/docs/dev/tutorials/integrating-talon-one#managing-parallel-requests).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponseWithStatus'
    SegmentTooManyRequests:
      description: Rate limit of 60 requests per second exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponseWithStatus'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        To authenticate in order to use these endpoints, generate an API key in the Campaign Manager:

        1. Log on to the Campaign Manager and open the Application of your choice, or create one.
        2. Click **Settings** > **Developer settings**.
        3. Click **Create API Key**.
        4. Give it a title.
        5. For **Do you want to use this API Key with a 3rd party service?**, select **Yes** and choose the platform to integrate with.
        6. Set an expiration date. then click **Create API Key**.

        You can now use the API key in the `Authorization` HTTP header of your requests, prefixing it with `ApiKey-v1`:

        ```
        Authorization: ApiKey-v1 dbc644d33aa74d582bd9479c59e16f970fe13bf3
        ```
    ApiKeyBasicAuth:
      type: http
      scheme: basic
      description: |
        To authenticate in order to use these endpoints, generate an API key in the Campaign Manager:

        1. Log on to the Campaign Manager and open the Application of your choice, or create one.
        2. Click **Settings** > **Developer settings**.
        3. Click **Create API Key**.
        4. Give it a title.
        5. For **Do you want to use this API Key with a 3rd party service?**, select **Yes** and choose the platform to integrate with.
        6. Set an expiration date. then click **Create API Key**.

        7. Encode your generated API Key with the prefix `ApiKey-v1 ` to base64, for example base64 encode this `ApiKey-v1 your-api-key-here:`.
           Don't forget to add the `:` at the end of your api key.

        Lastly prefix the previous string with `Authorization: `
        ```
        Authorization: Basic YmFzZTY0ZW5vZGV0aGlzcGxlYXNlYXNhcDQzMjE0MTI=
        ```
security:
  - ApiKeyAuth: []