TAtalon
Campaigns

Create campaign

Changed on

[!note] Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Create a campaign. A campaign is part of an Application and contains a set of rules.

post/v1/applications/{applicationId}/campaigns

Request

Path parameters

applicationIdinteger required

The ID of the Application. It is displayed in your Talon.One deployment URL.

Request body

namestring required

A user-facing name for this campaign.

descriptionstring

A detailed description of the campaign.

startTimestring date-time

Timestamp when the campaign will become active.

endTimestring date-time

Timestamp when the campaign will become inactive.

attributesobject

Arbitrary properties associated with this campaign.

state'enabled' | 'disabled' | 'archived' required

A disabled or archived campaign is not evaluated for rules or coupons.

activeRulesetIdinteger

ID of Ruleset this campaign applies on customer session evaluation.

tagsstring[] required

A list of tags for the campaign.

reevaluateOnReturnboolean

Indicates whether this campaign should be reevaluated when a customer returns an item.

featuresstring[] required

The features enabled in this campaign.

campaignGroupsinteger[]

The IDs of the campaign groups this campaign belongs to.

type'cartItem' | 'advanced'

The campaign type. Possible type values:

  • cartItem: Type of campaign that can apply effects only to cart items.
  • advanced: Type of campaign that can apply effects to customer sessions and cart items.
linkedStoreIdsinteger[]

A list of store IDs that you want to link to the campaign.

Note: Campaigns with linked store IDs will only be evaluated when there is a customer session update that references a linked store.

couponAttributesobject

Arbitrary properties associated with coupons in this campaign.

evaluationGroupIdinteger

The ID of the campaign evaluation group the campaign belongs to.

Example request

{
  "name": "Summer promotions",
  "description": "Campaign for all summer 2021 promotions",
  "startTime": "2021-07-20T22:00:00Z",
  "endTime": "2021-09-22T22:00:00Z",
  "state": "enabled",
  "activeRulesetId": 6,
  "tags": [
    "summer"
  ],
  "reevaluateOnReturn": true,
  "features": [
    "coupons",
    "referrals"
  ],
  "couponSettings": {
    "validCharacters": [
      "A",
      "B",
      "C",
      "D",
      "E",
      "F",
      "G",
      "H",
      "I",
      "J",
      "K",
      "L",
      "M",
      "N",
      "O",
      "P",
      "Q",
      "R",
      "S",
      "T",
      "U",
      "V",
      "W",
      "X",
      "Y",
      "Z",
      "0",
      "1",
      "2",
      "3",
      "4",
      "5",
      "6",
      "7",
      "8",
      "9"
    ],
    "couponPattern": "SUMMER-####-####"
  },
  "referralSettings": {
    "validCharacters": [
      "A",
      "B",
      "C",
      "D",
      "E",
      "F",
      "G",
      "H",
      "I",
      "J",
      "K",
      "L",
      "M",
      "N",
      "O",
      "P",
      "Q",
      "R",
      "S",
      "T",
      "U",
      "V",
      "W",
      "X",
      "Y",
      "Z",
      "0",
      "1",
      "2",
      "3",
      "4",
      "5",
      "6",
      "7",
      "8",
      "9"
    ],
    "couponPattern": "SUMMER-####-####"
  },
  "limits": [
    {
      "action": "createCoupon",
      "limit": 1000,
      "period": "yearly",
      "entities": [
        "Coupon"
      ]
    }
  ],
  "campaignGroups": [
    1,
    3
  ],
  "type": "advanced",
  "linkedStoreIds": [
    1,
    2,
    3
  ],
  "evaluationGroupId": 2
}

Response

Created

idinteger required

Unique ID for this entity.

createdstring date-time required

The exact moment this entity was created.

applicationIdinteger required

The ID of the Application that owns this entity.

userIdinteger required

The ID of the user associated with this entity.

namestring required

A user-facing name for this campaign.

descriptionstring required

A detailed description of the campaign.

startTimestring date-time

Timestamp when the campaign will become active.

endTimestring date-time

Timestamp when the campaign will become inactive.

attributesobject

Arbitrary properties associated with this campaign.

state'enabled' | 'disabled' | 'archived' required

A disabled or archived campaign is not evaluated for rules or coupons.

activeRulesetIdinteger

ID of Ruleset this campaign applies on customer session evaluation.

tagsstring[] required

A list of tags for the campaign.

reevaluateOnReturnboolean required

Indicates whether this campaign should be reevaluated when a customer returns an item.

featuresstring[] required

The features enabled in this campaign.

campaignGroupsinteger[]

The IDs of the campaign groups this campaign belongs to.

type'cartItem' | 'advanced' required

The campaign type. Possible type values:

  • cartItem: Type of campaign that can apply effects only to cart items.
  • advanced: Type of campaign that can apply effects to customer sessions and cart items.
linkedStoreIdsinteger[]

A list of store IDs that you want to link to the campaign.

Note: Campaigns with linked store IDs will only be evaluated when there is a customer session update that references a linked store.

couponAttributesobject

Arbitrary properties associated with coupons in this campaign.

couponRedemptionCountinteger

This property is deprecated. The count should be available under budgets property. Number of coupons redeemed in the campaign.

referralRedemptionCountinteger

This property is deprecated. The count should be available under budgets property. Number of referral codes redeemed in the campaign.

discountCountnumber

This property is deprecated. The count should be available under budgets property. Total amount of discounts redeemed in the campaign.

discountEffectCountinteger

This property is deprecated. The count should be available under budgets property. Total number of times discounts were redeemed in this campaign.

couponCreationCountinteger

This property is deprecated. The count should be available under budgets property. Total number of coupons created by rules in this campaign.

customEffectCountinteger

This property is deprecated. The count should be available under budgets property. Total number of custom effects triggered by rules in this campaign.

referralCreationCountinteger

This property is deprecated. The count should be available under budgets property. Total number of referrals created by rules in this campaign.

addFreeItemEffectCountinteger

This property is deprecated. The count should be available under budgets property. Total number of times the add free item effect can be triggered in this campaign.

awardedGiveawaysCountinteger

This property is deprecated. The count should be available under budgets property. Total number of giveaways awarded by rules in this campaign.

createdLoyaltyPointsCountnumber

This property is deprecated. The count should be available under budgets property. Total number of loyalty points created by rules in this campaign.

createdLoyaltyPointsEffectCountinteger

This property is deprecated. The count should be available under budgets property. Total number of loyalty point creation effects triggered by rules in this campaign.

redeemedLoyaltyPointsCountnumber

This property is deprecated. The count should be available under budgets property. Total number of loyalty points redeemed by rules in this campaign.

redeemedLoyaltyPointsEffectCountinteger

This property is deprecated. The count should be available under budgets property. Total number of loyalty point redemption effects triggered by rules in this campaign.

callApiEffectCountinteger

This property is deprecated. The count should be available under budgets property. Total number of webhooks triggered by rules in this campaign.

reservecouponEffectCountinteger

This property is deprecated. The count should be available under budgets property. Total number of reserve coupon effects triggered by rules in this campaign.

lastActivitystring date-time

Timestamp of the most recent event received by this campaign.

updatedstring date-time

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.

createdBystring

Name of the user who created this campaign if available.

updatedBystring

Name of the user who last updated this campaign if available.

templateIdinteger

The ID of the Campaign Template this Campaign was created from.

frontendState'expired' | 'scheduled' | 'running' | 'disabled' | 'archived' | 'staged' required

The campaign state displayed in the Campaign Manager.

storesImportedboolean required

Indicates whether the linked stores were imported via a CSV file.

valueMapsIdsinteger[]

A list of value map IDs for the campaign.

experimentIdinteger

The ID of the Experiment this Campaign is part of.

revisionFrontendState'revised' | 'pending'

The campaign revision state displayed in the Campaign Manager.

activeRevisionIdinteger

ID of the revision that was last activated on this campaign.

activeRevisionVersionIdinteger

ID of the revision version that is active on the campaign.

versioninteger

Incrementing number representing how many revisions have been activated on this campaign. Starts from 0 for a new campaign.

currentRevisionIdinteger

ID of the revision currently being modified for the campaign.

currentRevisionVersionIdinteger

ID of the latest version applied on the current revision.

stageRevisionboolean

Flag for determining whether we use current revision when sending requests with staging API key.

Example response

{
  "id": 4,
  "created": "2020-06-10T09:05:27.993483Z",
  "applicationId": 322,
  "userId": 388,
  "name": "Summer promotions",
  "description": "Campaign for all summer 2021 promotions",
  "startTime": "2021-07-20T22:00:00Z",
  "endTime": "2021-09-22T22:00:00Z",
  "state": "enabled",
  "activeRulesetId": 6,
  "tags": [
    "summer"
  ],
  "reevaluateOnReturn": true,
  "features": [
    "coupons",
    "referrals"
  ],
  "couponSettings": {
    "validCharacters": [
      "A",
      "B",
      "C",
      "D",
      "E",
      "F",
      "G",
      "H",
      "I",
      "J",
      "K",
      "L",
      "M",
      "N",
      "O",
      "P",
      "Q",
      "R",
      "S",
      "T",
      "U",
      "V",
      "W",
      "X",
      "Y",
      "Z",
      "0",
      "1",
      "2",
      "3",
      "4",
      "5",
      "6",
      "7",
      "8",
      "9"
    ],
    "couponPattern": "SUMMER-####-####"
  },
  "referralSettings": {
    "validCharacters": [
      "A",
      "B",
      "C",
      "D",
      "E",
      "F",
      "G",
      "H",
      "I",
      "J",
      "K",
      "L",
      "M",
      "N",
      "O",
      "P",
      "Q",
      "R",
      "S",
      "T",
      "U",
      "V",
      "W",
      "X",
      "Y",
      "Z",
      "0",
      "1",
      "2",
      "3",
      "4",
      "5",
      "6",
      "7",
      "8",
      "9"
    ],
    "couponPattern": "SUMMER-####-####"
  },
  "limits": [
    {
      "action": "createCoupon",
      "limit": 1000,
      "period": "yearly",
      "entities": [
        "Coupon"
      ]
    }
  ],
  "campaignGroups": [
    1,
    3
  ],
  "type": "advanced",
  "linkedStoreIds": [
    1,
    2,
    3
  ],
  "budgets": [
    {
      "action": "createCoupon",
      "limit": 1000,
      "counter": 42
    }
  ],
  "couponRedemptionCount": 163,
  "referralRedemptionCount": 3,
  "discountCount": 288,
  "discountEffectCount": 343,
  "couponCreationCount": 16,
  "referralCreationCount": 8,
  "awardedGiveawaysCount": 9,
  "createdLoyaltyPointsCount": 9,
  "createdLoyaltyPointsEffectCount": 2,
  "redeemedLoyaltyPointsCount": 8,
  "redeemedLoyaltyPointsEffectCount": 9,
  "reservecouponEffectCount": 9,
  "lastActivity": "2022-11-10T23:00:00Z",
  "updated": "2022-10-27T15:00:00Z",
  "createdBy": "John Doe",
  "updatedBy": "Jane Doe",
  "templateId": 3,
  "frontendState": "running",
  "storesImported": true,
  "valueMapsIds": [
    100,
    215
  ],
  "experimentId": 1,
  "revisionFrontendState": "revised",
  "activeRevisionId": 6,
  "activeRevisionVersionId": 6,
  "version": 6,
  "currentRevisionId": 6,
  "currentRevisionVersionId": 6
}

Changes