openapi: 3.2.0 info: version: '' title: Third-party Braze API description: "Use the Third-party API to exchange data between Talon.One and one of the supported [technology partners](https://docs.talon.one/docs/dev/technology-partners/overview).\n\nFor example, use the Braze-specific endpoints from your Braze campaigns to interact with Talon.One.\n\nIf the CDP or CEP you are using isn't listed here, use the generic\n[Customer Data Platforms](#tag/Customer-data-platforms) and [Customer Engagement Platform](#tag/Customer-engagement-platforms) endpoints.\n\n> [!note] \n> All endpoints of this API start with `https://integration.talon.one`.\n> You must specify the base URL of your deployment in the headers or parameters.\n\n> [!note] **Are you looking for a different API?**\n> - To implement use cases that aren't covered by the Third-party API, see the [Integration API](https://docs.talon.one/management-api).\n> - To interact with the Campaign Manager for back-office operations, see the [Management API](https://docs.talon.one/management-api).\n" servers: - url: https://integration.talon.one security: - ApiKeyAuth: [] 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). ' paths: /braze/referral: post: tags: - Braze summary: Create referral (Braze) 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 (Braze) 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/BrazeCouponRequest' examples: default: $ref: '#/components/examples/BrazeCouponRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/BrazeCouponResponse' examples: default: $ref: '#/components/examples/BrazeCouponResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' /braze/coupon_reservation: post: tags: - Braze summary: Create coupon reservation (Braze) operationId: braze/createCouponReservation description: 'Create a coupon reservation for a specified customer profile on the specified coupon. ' requestBody: content: application/json: schema: $ref: '#/components/schemas/CouponReservationRequest' examples: default: $ref: '#/components/examples/CouponReservationRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CouponReservationResponse' examples: default: $ref: '#/components/examples/CouponReservationResponse' '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 (Braze) 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). ' 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' components: schemas: limitConfig: type: object required: - action - limit - entities properties: action: type: string description: "The limitable action to which this limit applies. For example:\n - `setDiscount`\n - `setDiscountEffect`\n - `redeemCoupon`\n - `createCoupon`\n" 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 enum: - Coupon - Referral - Profile - Identifier 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 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' 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 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' BrazeCouponRequest: 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. ' 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: type: object required: - action - limit - entities properties: action: type: string description: 'The limitable action to which this limit applies. Must be set to `redeemCoupon`. ' example: redeemCoupon limit: type: number minimum: 0 example: 1000 description: The number of times a coupon can be redeemed per customer. entities: type: array description: The entities that this limit applies to. Must be set to `["Coupon", "Profile"]`. example: - Coupon - Profile items: type: string enum: - Coupon - Profile 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-28T11: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: language: english 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 additionalCost: type: object properties: price: description: Price of the additional cost. type: number example: 4.5 id: type: integer title: ID description: Unique ID for this entity. format: int64 example: 6 minimum: 1 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' 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. loyaltyProgramEntity: type: object required: - programID properties: programID: type: integer description: The ID of the loyalty program that owns this entity. example: 125 customerProfileID: type: string format: string example: URN-GV8294NV maxLength: 1000 description: The integration ID of the customer profile. If the customer profile does not exist, it will be created. 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. 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. CouponReservationRequest: type: object required: - deploymentUrl - couponValue - integrationId properties: deploymentUrl: type: string description: The base url of your deployment. example: mycompany.europe-west1.talon.one couponValue: type: string description: The coupon code. integrationId: type: string description: The integration ID of the customer profile. importEntity: type: object required: - id properties: importId: type: integer description: The ID of the Import which created this referral. 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 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' required: - profileId - firstSession - coupon - referral - state - cartItems - integrationId - applicationId - attributes - total - cartItemTotal - additionalCostTotal - updated 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 updateLoyaltyCard: type: object required: - status properties: status: type: string description: 'Status of the loyalty card. Can be one of: [''active'', ''disabled'']. ' 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 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. BrazeTrackEventRequest: allOf: - $ref: '#/components/schemas/TrackEventRequest' - type: object required: - identifier properties: identifier: $ref: '#/components/schemas/identifier' campaignEntity: type: object required: - campaignId properties: campaignId: type: integer title: Campaign ID description: The ID of the campaign that owns this entity. example: 211 applicationEntity: type: object required: - applicationId properties: applicationId: type: integer description: The ID of the application that owns this entity. example: 322 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' 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' 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' CouponReservationResponse: type: object required: - id - campaignId - value - usageLimit - usageCounter - created properties: id: type: integer format: int64 example: 20190408 description: The internal ID of this entity. campaignId: type: integer format: int64 example: 30 description: The ID of the campaign that owns this entity. value: type: string example: SUMMER-####-2022 description: The coupon code. usageLimit: type: integer format: int64 example: 1 description: The number of times the coupon code can be redeemed. `0` means unlimited redemptions but any campaign usage limits will still apply. usageCounter: type: integer description: The number of times the coupon has been successfully redeemed. example: 1 created: type: string format: date-time description: The time this entity was created. example: '2022-03-02T16:46:17.758585Z' attributes: type: object description: Custom attributes associated with this coupon. additionalProperties: true batchId: type: string description: The ID of the batch the coupon belongs to. example: 32535-43255 isReservationMandatory: type: boolean example: false description: Indicates whether the code can be redeemed only if it has been reserved first. implicitlyReserved: description: Indicates whether the coupon is implicitly reserved for all customers. type: boolean example: false reservation: type: boolean example: false description: 'Defines the reservation type: - `true`: The coupon can be reserved for multiple customers. - `false`: The coupon can be reserved only for one customer. It is a personal code. ' 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). ' 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 Type type: boolean example: false description: 'Defines the reservation type: - `true`: The coupon can be reserved for multiple customers. - `false`: The coupon can be reserved only for one customer. It is a personal code. ' default: true batchId: title: Batch ID type: string description: The id of the batch the coupon belongs to. example: 32535-43255 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' userEntity: type: object required: - userId properties: userId: type: integer description: The ID of the account that owns this entity. 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 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 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 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. 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 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:\n\n1. `open` -> `closed`\n2. `open` -> `cancelled`\n3. Either:\n - `closed` -> `cancelled` (**only** via [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)) or\n - `closed` -> `partially_returned` (**only** via [Return cart items](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/returnCartItems))\n4. `partially_returned` -> `cancelled`\n\nFor more information, see [Customer session states](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).\n" 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. **Note:** If `null`, the attribute is deleted from the customer session. ' additionalProperties: true example: ShippingCity: Berlin 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. 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 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 BrazeCouponResponse: 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. ' Limits: type: array items: type: object properties: action: type: string description: 'The limitable action to which this limit applies. For example: - `redeemCoupon` ' example: redeemCoupon limit: type: number minimum: 0 example: 1000 description: The value to set for the limit. entities: type: array description: The entity that this limit applies to. example: - Coupon, Profile items: type: string enum: - Coupon - Profile StartDate: type: string format: date-time example: '2021-09-30T15:35:02.371569+02:00' ExpiryDate: type: string format: date-time example: '2022-02-28T11:00:00.569+02:00' RecipientIntegrationID: type: string example: URN-GV8294NV UsageLimit: type: integer format: int64 example: 1 Attributes: type: object example: language: english newReturn: type: object required: - returnedCartItems properties: returnedCartItems: type: array description: List of cart items to be returned. items: $ref: '#/components/schemas/returnedCartItem' 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' accountEntity: type: object required: - accountId properties: accountId: $ref: '#/components/schemas/id' 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 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' 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. 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. 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. 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. 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 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 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. integrationProfileEntity: type: object properties: profileId: type: string description: 'ID of the customers profile as used within this Talon.One account. ' example: URN-GV8294NV 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' 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 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. cartItem: type: object required: - sku - quantity 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/rules/understanding-cart-item-flattening), 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 the item in the currency defined by your Application. This field is required if this item is not part of a [catalog](https://docs.talon.one/docs/product/account/dev-tools/managing-cart-item-catalogs). If it is part of a catalog, setting a price here overrides the price from the catalog. 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 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. 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' 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 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. 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` ' 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' 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. 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. errorResponseWithStatus: type: object properties: StatusCode: type: integer description: The error code. example: 400 Error: type: string example: Bad request RequestUUID: type: string example: 51fad142-3563-4fe2-b4aa-41ab20be31d911 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 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. 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. 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. 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. 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. ' 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. 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. 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. couponValue: type: object properties: value: type: string title: Coupon Code description: The coupon code. minLength: 4 example: XMAS-20-2021 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. 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. 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. attributeValuePairs: type: object description: 'Property to set the attributes of your choice to the values of your choice. 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: Language: english ShippingCountry: DE ProductClicked: true 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. 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. 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' 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-07T11: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 examples: CouponReservationRequest: value: deploymentUrl: mycompany.europe-west1.talon.one couponValue: EW-1BC2 integrationId: URN-GV8294NV 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! BrazeCouponResponse: 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 IsReservationMandatory: false Limits: - entities: - Coupon - Profile limit: 1 action: redeemCoupon Attributes: email: user@mailbox.com country: DE CouponReservationResponse: value: id: 1 campaignId: 1 created: '2022-03-02T16:46:17.758585Z' value: EW-1BC2 usageCounter: 0 usageLimit: 1 BrazeCouponRequest: 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-#### isReservationMandatory: false limits: - entities: - Coupon - Profile limit: 1 action: redeemCoupon attributes: venueId: BER4271 venueName: Admiralspalast 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 responses: 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 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 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 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 parameters: 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 securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: "To authenticate to use these endpoints, create a Third-party API key in the Campaign Manager:\n\n1. Sign in to the Campaign Manager, and open the [Application](https://docs.talon.one/docs/product/applications/overview) of your choice.\n2. Click **Settings** > **Integration API Keys**.\n3. Click **Create API Key**.\n4. In the **Create API Key** drawer, if you are asked for a key type, select **Production**.\n5. In **Key name**, type a name to identify the key.\n6. In **Key expiration date**, select a date.\n \n **Tip**: Avoid choosing expiration dates that fall at the end of\n the year or during other high-traffic periods.\n\n7. In **Third-party integration**, select **Yes** and the platform to integrate with.\n8. Click **Create API Key**, and copy the generated value for use.\n\nYou can now use the API key in the `Authorization` HTTP header of your requests, prefixing it with `ApiKey-v1 `:\n\n```\nAuthorization: ApiKey-v1 dbc644d33aa74d582bd9479c59e16f970fe13bf3\n```\n" ApiKeyBasicAuth: type: http scheme: basic description: "To authenticate to use these endpoints, create a Third-party API key in the Campaign Manager:\n\n1. Sign in to the Campaign Manager, and open the [Application](https://docs.talon.one/docs/product/applications/overview) of your choice.\n2. Click **Settings** > **Integration API Keys**.\n3. Click **Create API Key**.\n4. In the **Create API Key** drawer, if you are asked for a key type, select **Production**.\n5. In **Key name**, type a name to identify the key.\n6. In **Key expiration date**, select a date.\n\n **Tip**: Avoid choosing expiration dates that fall at the end of\n the year or during other high-traffic periods.\n \n7. In **Third-party integration**, select **Yes** and the platform to integrate with.\n8. Click **Create API Key**, and copy the generated value for use.\n9. Modify the generated value by prefixing it with `ApiKey-v1 ` and suffixing it with `:`. For example: `ApiKey-v1 :`.\n10. Encode this modified value to Base64.\n\nYou can now use the API key, prefixing the Base64-encoded string with `Authorization: Basic `:\n\n```\nAuthorization: Basic YmFzZTY0ZW5vZGV0aGlzcGxlYXNlYXNhcDQzMjE0MTI=\n```\n"