--- title: "Create campaign" method: POST path: "/v1/applications/{applicationId}/campaigns" tags: ["Campaigns"] --- # Create campaign `POST /v1/applications/{applicationId}/campaigns` ## Request - Base URL: `https://yourbaseurl.talon.one` - URL: `https://yourbaseurl.talon.one/v1/applications/{applicationId}/campaigns` - Auth: one of: - API key in header `Authorization` - API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) > [!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. ## Path parameters - `applicationId` integer, required ## Request body - NewCampaign - `name` string, required: A user-facing name for this campaign. - `description` string: A detailed description of the campaign. - `startTime` string, date-time: Timestamp when the campaign will become active. - `endTime` string, date-time: Timestamp when the campaign will become inactive. - `attributes` object: Arbitrary properties associated with this campaign. - `state` 'enabled' | 'disabled' | 'archived', required: A disabled or archived campaign is not evaluated for rules or coupons. - `activeRulesetId` integer: [ID of Ruleset](https://docs.talon.one/management-api#tag/Campaigns/operation/getRulesets) this campaign applies on customer session evaluation. - `tags` string[], required: A list of tags for the campaign. - `reevaluateOnReturn` boolean: Indicates whether this campaign should be reevaluated when a customer returns an item. - `features` string[], required: The features enabled in this campaign. - `couponSettings` CodeGeneratorSettings - `validCharacters` string[], required: List of characters used to generate the random parts of a code. - `couponPattern` string, required: The pattern used to generate codes, such as coupon codes, referral codes, and loyalty cards. The character `#` is a placeholder and is replaced by a random character from the `validCharacters` set. - `referralSettings` CodeGeneratorSettings - `validCharacters` string[], required: List of characters used to generate the random parts of a code. - `couponPattern` string, required: The pattern used to generate codes, such as coupon codes, referral codes, and loyalty cards. The character `#` is a placeholder and is replaced by a random character from the `validCharacters` set. - `limits` LimitConfig[], required: The set of [budget limits](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets) for this campaign. - `action` string, required: The limitable action to which this limit applies. For example: - `setDiscount` - `setDiscountEffect` - `redeemCoupon` - `createCoupon` - `limit` number, required: The value to set for the limit. - `period` 'daily' | 'weekly' | 'monthly' | 'yearly': The period on which the budget limit recurs. - `entities` string[], required: The entity that this limit applies to. - `campaignGroups` integer[]: The IDs of the [campaign groups](https://docs.talon.one/docs/product/account/managing-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. - `linkedStoreIds` integer[]: A list of store IDs that you want to link to the campaign. **Note:** Campaigns with linked store IDs will only be evaluated when there is a [customer session update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) that references a linked store. - `couponAttributes` object: Arbitrary properties associated with coupons in this campaign. - `evaluationGroupId` integer: The ID of the campaign evaluation group the campaign belongs to. ## Response `201` Created - Campaign - `id` integer, required: Unique ID for this entity. - `created` string, date-time, required: The exact moment this entity was created. - `applicationId` integer, required: The ID of the Application that owns this entity. - `userId` integer, required: The ID of the user associated with this entity. - `name` string, required: A user-facing name for this campaign. - `description` string, required: A detailed description of the campaign. - `startTime` string, date-time: Timestamp when the campaign will become active. - `endTime` string, date-time: Timestamp when the campaign will become inactive. - `attributes` object: Arbitrary properties associated with this campaign. - `state` 'enabled' | 'disabled' | 'archived', required: A disabled or archived campaign is not evaluated for rules or coupons. - `activeRulesetId` integer: [ID of Ruleset](https://docs.talon.one/management-api#tag/Campaigns/operation/getRulesets) this campaign applies on customer session evaluation. - `tags` string[], required: A list of tags for the campaign. - `reevaluateOnReturn` boolean, required: Indicates whether this campaign should be reevaluated when a customer returns an item. - `features` string[], required: The features enabled in this campaign. - `couponSettings` CodeGeneratorSettings - `validCharacters` string[], required: List of characters used to generate the random parts of a code. - `couponPattern` string, required: The pattern used to generate codes, such as coupon codes, referral codes, and loyalty cards. The character `#` is a placeholder and is replaced by a random character from the `validCharacters` set. - `referralSettings` CodeGeneratorSettings - `validCharacters` string[], required: List of characters used to generate the random parts of a code. - `couponPattern` string, required: The pattern used to generate codes, such as coupon codes, referral codes, and loyalty cards. The character `#` is a placeholder and is replaced by a random character from the `validCharacters` set. - `limits` LimitConfig[], required: The set of [budget limits](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets) for this campaign. - `action` string, required: The limitable action to which this limit applies. For example: - `setDiscount` - `setDiscountEffect` - `redeemCoupon` - `createCoupon` - `limit` number, required: The value to set for the limit. - `period` 'daily' | 'weekly' | 'monthly' | 'yearly': The period on which the budget limit recurs. - `entities` string[], required: The entity that this limit applies to. - `campaignGroups` integer[]: The IDs of the [campaign groups](https://docs.talon.one/docs/product/account/managing-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. - `linkedStoreIds` integer[]: A list of store IDs that you want to link to the campaign. **Note:** Campaigns with linked store IDs will only be evaluated when there is a [customer session update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) that references a linked store. - `couponAttributes` object: Arbitrary properties associated with coupons in this campaign. - `budgets` CampaignBudget[]: A list of all the budgets that are defined by this campaign and their usage. **Note:** Budgets that are not defined do not appear in this list and their usage is not counted until they are defined. - `action` string, required: The limitable action to which this limit applies. For example: - `setDiscount` - `setDiscountEffect` - `redeemCoupon` - `createCoupon` - `limit` number, required: The value to set for the limit. - `counter` number, required: The number of occurrences of the limited action in the context of the campaign. - `couponRedemptionCount` integer: This property is **deprecated**. The count should be available under *budgets* property. Number of coupons redeemed in the campaign. - `referralRedemptionCount` integer: This property is **deprecated**. The count should be available under *budgets* property. Number of referral codes redeemed in the campaign. - `discountCount` number: This property is **deprecated**. The count should be available under *budgets* property. Total amount of discounts redeemed in the campaign. - `discountEffectCount` integer: This property is **deprecated**. The count should be available under *budgets* property. Total number of times discounts were redeemed in this campaign. - `couponCreationCount` integer: This property is **deprecated**. The count should be available under *budgets* property. Total number of coupons created by rules in this campaign. - `customEffectCount` integer: This property is **deprecated**. The count should be available under *budgets* property. Total number of custom effects triggered by rules in this campaign. - `referralCreationCount` integer: This property is **deprecated**. The count should be available under *budgets* property. Total number of referrals created by rules in this campaign. - `addFreeItemEffectCount` integer: This property is **deprecated**. The count should be available under *budgets* property. Total number of times the [add free item effect](https://docs.talon.one/docs/dev/integration-api/api-effects#addfreeitem) can be triggered in this campaign. - `awardedGiveawaysCount` integer: This property is **deprecated**. The count should be available under *budgets* property. Total number of giveaways awarded by rules in this campaign. - `createdLoyaltyPointsCount` number: This property is **deprecated**. The count should be available under *budgets* property. Total number of loyalty points created by rules in this campaign. - `createdLoyaltyPointsEffectCount` integer: 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. - `redeemedLoyaltyPointsCount` number: This property is **deprecated**. The count should be available under *budgets* property. Total number of loyalty points redeemed by rules in this campaign. - `redeemedLoyaltyPointsEffectCount` integer: 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. - `callApiEffectCount` integer: This property is **deprecated**. The count should be available under *budgets* property. Total number of webhooks triggered by rules in this campaign. - `reservecouponEffectCount` integer: This property is **deprecated**. The count should be available under *budgets* property. Total number of reserve coupon effects triggered by rules in this campaign. - `lastActivity` string, date-time: Timestamp of the most recent event received by this campaign. - `updated` string, 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. - `createdBy` string: Name of the user who created this campaign if available. - `updatedBy` string: Name of the user who last updated this campaign if available. - `templateId` integer: 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. - `storesImported` boolean, required: Indicates whether the linked stores were imported via a CSV file. - `valueMapsIds` integer[]: A list of value map IDs for the campaign. - `experimentId` integer: The ID of the Experiment this Campaign is part of. - `revisionFrontendState` 'revised' | 'pending': The campaign revision state displayed in the Campaign Manager. - `activeRevisionId` integer: ID of the revision that was last activated on this campaign. - `activeRevisionVersionId` integer: ID of the revision version that is active on the campaign. - `version` integer: Incrementing number representing how many revisions have been activated on this campaign. Starts from `0` for a new campaign. - `currentRevisionId` integer: ID of the revision currently being modified for the campaign. - `currentRevisionVersionId` integer: ID of the latest version applied on the current revision. - `stageRevision` boolean: Flag for determining whether we use current revision when sending requests with staging API key. ## Changes - **2026-11-07** `7ef1b9504c3a`: 1 info - endpoint added [Operation history](https://skmtc.dev/talon/apis/management-api/changes/v1/applications/:applicationId/campaigns/post.md) --- [API](https://skmtc.dev/talon/apis/management-api.md) - [All operations](https://skmtc.dev/talon/apis/management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/talon/apis/management-api/revisions/7ef1b9504c3a?raw)