> ## Documentation Index > Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt > Use this file to discover all available pages before exploring further. # Create Campaign From Template > Creates a campaign out of a campaign template. To create a campaign, you need to provide the name in the request, while other fields are optional. If no other fields are sent, the configuration from the template will be used. You can send new values of the fields listed below to replace the settings saved in the template. However, you cannot assign an existing validation rule or create a new one in the request. If the template has a validation rule, a new validation rule is always created for the campaign. When the campaign has been created, then you can: - [Update the validation rule](/api-reference/validation-rules/update-validation-rule), - [Unassign the validation rule](/api-reference/validation-rules/delete-validation-rule-assignment), - [Assign an existing validation rule](/api-reference/validation-rules/create-validation-rules-assignments). > 👍 Promotion Tiers and Campaign Templates > >You can create a campaign template out of a promotion tier. Promotion tiers are converted to a discount campaign with the `DISCOUNT_COUPON` type. You can use this template to create: >- [Discount campaign](/api-reference/templates/create-campaign-from-template) >- [Promotion tier](/api-reference/templates/add-promotion-tier-from-template) > 📘 Campaign Templates – Documentation > >Read the [Campaign Templates documentation](/build/campaign-templates) to learn more about this feature. ## OpenAPI ````yaml /openapi/templates.json post /v1/templates/campaigns/{campaignTemplateId}/campaign-setup openapi: 3.0.1 info: title: Voucherify API - Templates version: v2018-08-01 description: >- Voucherify promotion engine REST API. Please see https://docs.voucherify.io/docs for more details. contact: name: Voucherify Team url: https://www.voucherify.io/contact-support email: support@voucherify.io termsOfService: https://www.voucherify.io/legal/subscription-agreement license: name: MIT url: https://github.com/voucherifyio/voucherify-js-sdk/blob/main/LICENSE servers: - url: https://{cluster}.voucherify.io description: Base URL variables: cluster: default: api enum: - api - us1.api - as1.api - download - us1.download - as1.download security: [] paths: /v1/templates/campaigns/{campaignTemplateId}/campaign-setup: parameters: - in: path name: campaignTemplateId description: Pass the campaign template ID that was assigned by Voucherify. schema: $ref: '#/components/schemas/ParameterCampaignTemplateId' required: true post: tags: - Templates summary: Create Campaign From Template description: >- Creates a campaign out of a campaign template. To create a campaign, you need to provide the name in the request, while other fields are optional. If no other fields are sent, the configuration from the template will be used. You can send new values of the fields listed below to replace the settings saved in the template. However, you cannot assign an existing validation rule or create a new one in the request. If the template has a validation rule, a new validation rule is always created for the campaign. When the campaign has been created, then you can: - [Update the validation rule](/api-reference/validation-rules/update-validation-rule), - [Unassign the validation rule](/api-reference/validation-rules/delete-validation-rule-assignment), - [Assign an existing validation rule](/api-reference/validation-rules/create-validation-rules-assignments). > 👍 Promotion Tiers and Campaign Templates > >You can create a campaign template out of a promotion tier. Promotion tiers are converted to a discount campaign with the `DISCOUNT_COUPON` type. You can use this template to create: >- [Discount campaign](/api-reference/templates/create-campaign-from-template) >- [Promotion tier](/api-reference/templates/add-promotion-tier-from-template) > 📘 Campaign Templates – Documentation > >Read the [Campaign Templates documentation](/build/campaign-templates) to learn more about this feature. operationId: create-campaign-from-template parameters: [] requestBody: description: >- Only `name` is required. The rest of the fields will overwrite the template configuration. content: application/json: schema: $ref: >- #/components/schemas/TemplatesCampaignsCampaignSetupCreateRequestBody examples: Example: value: name: Campaign-out-of-template description: Created out of a template auto_join: true join_once: true required: true responses: '200': description: >- Returns the details about the created campaign and about the resources that have been created out of the template and added to the project. content: application/json: schema: $ref: >- #/components/schemas/TemplatesCampaignsCampaignSetupCreateResponseBody examples: Example: value: created_resources: - id: val_3LBFw25WTmAK object: validation_rules campaign: id: camp_txDwyDPeLvBEq490bfV2nLwo name: Campaign-out-of-template campaign_type: DISCOUNT_COUPONS type: AUTO_UPDATE is_referral_code: false voucher: type: DISCOUNT_VOUCHER discount: type: AMOUNT amount_off: 2500 aggregated_amount_limit: 25000 units: null effect: APPLY_TO_ITEMS gift: null loyalty_card: null redemption: quantity: 4 redeemed_quantity: 0 code_config: pattern: '##' length: 2 charset: xD prefix: U- postfix: '-WOT' auto_join: true join_once: true use_voucher_metadata_schema: true description: Winter 2024-25 start_date: null expiration_date: null validity_timeframe: null validity_hours: null validity_day_of_week: null activity_duration_after_publishing: null vouchers_count_invalid: null vouchers_count: 0 active: true metadata: null created_at: '2024-09-26T17:14:56.226Z' updated_at: null category: null creation_status: DONE protected: false validation_rules_assignments: data: - id: asgm_BLgJYmo64rnAK5eB rule_id: val_3LBFw25WTmAK related_object_id: camp_txDwyDPeLvBEq490bfV2nLwo related_object_type: campaign created_at: '2024-09-26T17:14:56.226Z' object: validation_rules_assignment total: 1 object: campaign deleted: false deleted_at: null category_id: null voucher_type: DISCOUNT_VOUCHER discount: type: AMOUNT amount_off: 2500 aggregated_amount_limit: 25000 units: null effect: APPLY_TO_ITEMS gift: null loyalty_card: null voucher_code_config: pattern: '##' length: 2 charset: xD prefix: Your- postfix: '-Voucher' default_voucher_redemption: quantity: 4 object: campaign_setup '404': description: Returns an error if a resource is not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Resource not found: value: code: 404 key: not_found message: Resource not found details: >- Cannot find campaign_template with id camp_tpl_zLtn2H9fgcG3NwO7t4PAfHc request_id: v-0f6d3efe61099b2824 resource_id: camp_tpl_zLtn2H9fgcG3NwO7t4PAfHc resource_type: campaign_template '409': description: Returns an error if a campaign with the same name already exists. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Duplicate: value: code: 409 key: duplicate_found message: Duplicated resource found details: >- Duplicated campaign exists with name CampaignFromTemplate-01 request_id: v-0f754b9c091c095e33 resource_id: CampaignFromTemplate-01 resource_type: campaign security: - X-App-Id: [] X-App-Token: [] - X-Voucherify-OAuth: - api - templates components: schemas: ParameterCampaignTemplateId: type: string example: camp_tpl_zLtn2H9fgcG3NwO7t4PAfHcq TemplatesCampaignsCampaignSetupCreateRequestBody: type: object title: Templates Campaign Template Create Campaign Request Body description: >- Request body schema for **POST** `/v1/templates/campaigns/{campaignTemplateId}/campaign-setup`. allOf: - $ref: '#/components/schemas/CampaignsCreateBase' - type: object properties: voucher: type: object description: '' properties: code_config: $ref: '#/components/schemas/CodeConfig' redemption: type: object description: >- Stores the quantity of redemptions that can be applied to the voucher. properties: quantity: type: integer description: >- How many times a voucher can be redeemed. A `null` value means unlimited. required: - name TemplatesCampaignsCampaignSetupCreateResponseBody: type: object title: Templates Campaigns Create Campaign From Template Response Body description: >- Response body schema for **POST** `/v1/templates/campaigns/{campaignTemplateId}/campaign-setup`. properties: created_resources: type: array description: >- Contains a list of resources that have been added to the project when the campaign has been created out of the template. items: type: object properties: id: type: string description: >- Unique identifier assigned to the created resource. It is assigned by Voucherify. object: type: string description: The type of the created resource. enum: - validation_rules - product - sku - products_collection - segments - location required: - id - object campaign: description: Details of the created campaign. allOf: - $ref: '#/components/schemas/Campaign' object: type: string description: >- The type of the object represented by JSON. This object stores information about the campaign created out of the campaign template. enum: - campaign_setup required: - created_resources - campaign - object Error: title: Error Object type: object description: Error details properties: code: type: integer description: Error's HTTP status code. key: type: string description: Short string describing the kind of error which occurred. message: type: string description: A human-readable message providing a short description of the error. details: type: string description: A human-readable message providing more details about the error. request_id: type: string example: v-0a885062c80375740f description: >- This ID is useful when troubleshooting and/or finding the root cause of an error response by our support team. resource_id: type: string description: >- Unique resource ID that can be used in another endpoint to get more details. example: rf_0c5d710a87c8a31f86 resource_type: type: string description: The resource type. example: voucher error: type: object description: Includes additional information about the error. properties: message: type: string description: The message configured by the user in a validation rule. required: - code - message CampaignsCreateBase: type: object title: Campaign Create Schema Base description: Base body schema for creating a campaign properties: name: type: string description: Campaign name. description: type: string description: >- An optional field to keep any extra textual information about the campaign such as a campaign description and details. type: type: string description: >- Defines whether the campaign can be updated with new vouchers after campaign creation or if the campaign consists of generic (standalone) vouchers. - `AUTO_UPDATE`: the campaign is dynamic, i.e. vouchers will generate based on set criteria - `STATIC`: vouchers need to be manually published enum: - AUTO_UPDATE - STATIC join_once: type: boolean description: >- If this value is set to `true`, customers will be able to join the campaign only once. For loyalty campaigns, it's forced to `true`, even if `join_once: false` is passed in the request. auto_join: type: boolean description: >- Indicates whether customers will be able to auto-join a loyalty campaign if any earning rule is fulfilled. use_voucher_metadata_schema: type: boolean description: >- Flag indicating whether the campaign is to use the voucher's metadata schema instead of the campaign metadata schema. vouchers_count: type: integer description: Total number of unique vouchers in campaign (size of campaign). start_date: type: string format: date-time description: >- Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is *inactive before* this date. example: '2022-09-20T00:00:00.000Z' expiration_date: type: string format: date-time description: >- Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is *inactive after* this date. example: '2022-09-30T00:00:00.000Z' validity_timeframe: $ref: '#/components/schemas/ValidityTimeframe' validity_day_of_week: $ref: '#/components/schemas/ValidityDayOfWeek' validity_hours: $ref: '#/components/schemas/ValidityHours' activity_duration_after_publishing: type: string description: >- Defines the amount of time the vouchers will be active after publishing. The value is shown in the ISO 8601 format. For example, a voucher with the value of P24D will be valid for a duration of 24 days. category_id: type: string description: >- Unique category ID that this campaign belongs to. Either pass this parameter OR the `category`. example: cat_0b688929a2476386a7 category: type: string description: >- The category assigned to the campaign. Either pass this parameter OR the `category_id`. metadata: type: object description: >- The metadata object stores all custom attributes assigned to the campaign. A set of key/value pairs that you can attach to a campaign object. It can be useful for storing additional information about the campaign in a structured format. access_settings: $ref: '#/components/schemas/AccessSettings' CodeConfig: title: Code Config type: object description: >- Contains information about the config used for the voucher code. Defines the code's pattern (prefix, postfix, length, charset, etc). properties: length: type: number description: >- Number of characters in a generated code (excluding prefix and postfix). charset: type: string description: >- Characters that can appear in the code. Examples: - Alphanumeric: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ` - Alphabetic: `abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ` - Alphabetic Lowercase: `abcdefghijklmnopqrstuvwxyz` - Alphabetic Uppercase: `ABCDEFGHIJKLMNOPQRSTUVWXYZ` - Numbers: `0123456789` - Custom: a custom character set prefix: type: string description: A text appended before the code. postfix: type: string description: A text appended after the code. pattern: type: string description: >- A pattern for codes where hashes (#) will be replaced with random characters. Overrides `length`. initial_count: type: integer description: Internal value, does not change anything if provided. Campaign: title: Campaign allOf: - $ref: '#/components/schemas/CampaignBase' - title: Campaign Additional Data type: object properties: promotion: $ref: '#/components/schemas/PromotionTiersList' validation_rules_assignments: $ref: '#/components/schemas/ValidationRulesAssignmentsList' ValidityTimeframe: title: Validity Timeframe type: object description: >- Set recurrent time periods when the earning rule is valid. For example, valid for 1 hour every other day.`start_date` **required** when including the `validity_timeframe`. properties: duration: type: string description: >- Defines the amount of time an earning rule will be active in ISO 8601 format. For example, an earning rule with a `duration` of `PT1H` will be valid for a duration of one hour. example: PT1H interval: type: string description: >- Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, an earning rule with an `interval` of `P2D` will be valid every other day. example: P2D ValidityDayOfWeek: title: Validity Day Of Week type: array description: >- Integer array corresponding to the particular days of the week in which the voucher is valid. - `0` Sunday - `1` Monday - `2` Tuesday - `3` Wednesday - `4` Thursday - `5` Friday - `6` Saturday items: type: integer enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 ValidityHours: title: Validity Hours type: object description: Determines the hours of validity, e.g. to create a happy hours scenario. properties: daily: type: array description: >- Defines the recurring period(s) when the resource is active. The periods should not overlap. items: type: object description: Defines the recurring period(s) when the resource will be active. properties: start_time: type: string format: time description: >- Defines the starting hour of validity in the HH:mm format. The resource is *inactive before* this time. example: '12:00' days_of_week: type: array description: >- Integer array corresponding to the particular days of the week in which the resource is valid. - `0` Sunday - `1` Monday - `2` Tuesday - `3` Wednesday - `4` Thursday - `5` Friday - `6` Saturday items: type: integer enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 expiration_time: type: string format: time description: >- Defines the ending hour of validity in the HH:mm format. The resource is *inactive after* this time. example: '14:00' AccessSettings: type: object title: Access Settings description: >- Assigns or unassigns an area or store to the campaign. **NOTE**: this object can be sent if the Areas and Stores enterprise feature is enabled. Contact [Voucherify Sales](https://www.voucherify.io/contact-sales) to learn more. properties: assign: type: object description: >- Assigns the campaign to an area or a store. Provide the area and/or store IDs in the respective arrays. If a campaign changes assignments between areas or stores, unassign it from the area. For example, if a campaign is assigned to Area-01, but it must be now assigned to Store-01 within this area, you have to unassign the campaign from Area-01 and assign to Store-01 only. If you want to assign the campaign to stores only, you do not have to send the area ID. properties: areas_ids: type: array description: List all area IDs to which the campaign will be assigned. items: type: string area_stores_ids: type: array description: List all store IDs to which the campaign will be assigned. items: type: string area_all_stores_ids: type: array description: >- List all area IDs where the campaign is assigned to all stores in the area. This assignment is not equal to the assignment to all `area_stores_ids` listed separately. items: type: string unassign: type: object description: >- Unassigns the campaign from an area or a store. Provide the area and/or store IDs in the respective arrays. If a campaign changes assignments between areas or stores, unassign it first. For example, if a campaign is assigned to Area-01, but it must be now assigned to Store-01 within this area, you have to unassign the campaign from Area-01 and assigned to Store-01 only. If you want to assign the campaign to stores only, you do not have to send the area ID. properties: areas_ids: type: array description: List all area IDs from which the campaign will be unassigned. items: type: string area_stores_ids: type: array description: List all store IDs from which the campaign will be unassigned. items: type: string area_all_stores_ids: type: array description: >- List all area IDs where the campaign will be unassigned from all stores in the area. This unassignment is not equal to the unassignment from all `area_stores_ids` listed separately. items: type: string CampaignBase: type: object title: Campaign Base description: This is an object representing a campaign. properties: id: type: string description: Unique campaign ID, assigned by Voucherify. example: camp_f7fBbQxUuTN7dI7tGOo5XMDA name: type: string description: Campaign name. description: type: string description: >- An optional field to keep any extra textual information about the campaign such as a campaign description and details. campaign_type: type: string enum: - LOYALTY_PROGRAM - GIFT_VOUCHERS - DISCOUNT_COUPONS - PROMOTION - REFERRAL_PROGRAM description: Type of campaign. type: type: string description: >- Defines whether the campaign can be updated with new vouchers after campaign creation or if the campaign consists of generic (standalone) vouchers. - `AUTO_UPDATE`: the campaign is dynamic, i.e. vouchers will generate based on set criteria - `STATIC`: vouchers need to be manually published - `STANDALONE`: campaign for single vouchers enum: - AUTO_UPDATE - STATIC - STANDALONE voucher: $ref: '#/components/schemas/CampaignVoucher' auto_join: type: boolean description: >- Indicates whether customers will be able to auto-join a loyalty campaign if any earning rule is fulfilled. join_once: type: boolean description: >- If this value is set to `true`, customers will be able to join the campaign only once. It is always `false` for generic (standalone) vouchers campaigns and it cannot be changed in them. It is always `true` for loyalty campaigns and it cannot be changed in them. use_voucher_metadata_schema: type: boolean description: >- Flag indicating whether the campaign is to use the voucher's metadata schema instead of the campaign metadata schema. validity_timeframe: $ref: '#/components/schemas/ValidityTimeframe' validity_day_of_week: $ref: '#/components/schemas/ValidityDayOfWeek' validity_hours: $ref: '#/components/schemas/ValidityHours' activity_duration_after_publishing: type: string description: >- Defines the amount of time the vouchers will be active after publishing. The value is shown in the ISO 8601 format. For example, a voucher with the value of P24D will be valid for a duration of 24 days. vouchers_count: type: integer description: Total number of unique vouchers in campaign. start_date: type: string format: date-time description: >- Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is *inactive before* this date. example: '2022-09-20T00:00:00.000Z' expiration_date: type: string format: date-time description: >- Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is *inactive after* this date. example: '2022-09-30T00:00:00.000Z' active: type: boolean description: >- A flag to toggle the campaign on or off. You can disable a campaign even though it's within the active period defined by the `start_date` and `expiration_date`. - `true` indicates an *active* campaign - `false` indicates an *inactive* campaign metadata: type: object description: >- The metadata object stores all custom attributes assigned to the campaign. A set of key/value pairs that you can attach to a campaign object. It can be useful for storing additional information about the campaign in a structured format. created_at: type: string format: date-time example: '2021-12-01T08:00:50.038Z' description: >- Timestamp representing the date and time when the campaign was created. The value is shown in the ISO 8601 format. updated_at: type: string format: date-time example: '2022-09-20T09:18:19.623Z' description: >- Timestamp representing the date and time when the campaign was last updated in ISO 8601 format. category: type: string description: Unique category name. creation_status: type: string enum: - DONE - IN_PROGRESS - FAILED - DRAFT - MODIFYING description: Indicates the status of the campaign creation. vouchers_generation_status: type: string description: Indicates the status of the campaign's voucher generation. enum: - DONE - IN_PROGRESS - FAILED - DRAFT - MODIFYING readonly: type: boolean description: >- Indicates whether the campaign can be only read by a restricted user in the Areas and Stores enterprise feature. It is returned only to restricted users; this field is not returned for users with other roles. It is also not returned for restricted users who use the [GET Campaign summary](/api-reference/campaigns/get-campaign-summary) endpoint. protected: type: boolean description: Indicates whether the resource can be deleted. category_id: type: string nullable: true description: Unique category ID that this campaign belongs to. example: cat_0b688929a2476386a7 categories: type: array description: >- Contains details about the campaign category. For the GET [List campaigns](/api-reference/campaigns/list-campaigns) endpoint, this is returned only if the `expand=category` query parameter is passed in the request. Otherwise, it is returned as an empty array. For GET [Campaign summary](/api-reference/campaigns/get-campaign-summary) endpoint, it is always returned as an empty array. items: $ref: '#/components/schemas/Category' object: type: string default: campaign description: >- The type of the object represented by JSON. This object stores information about the campaign. referral_program: $ref: '#/components/schemas/ReferralProgram' loyalty_tiers_expiration: $ref: '#/components/schemas/LoyaltyTiersExpirationAll' access_settings_assignments: $ref: '#/components/schemas/AccessSettingsCampaignAssignmentsList' required: - id - name - campaign_type - type - auto_join - join_once - use_voucher_metadata_schema - created_at - creation_status - vouchers_generation_status - protected - category_id - categories - object PromotionTiersList: type: object description: Promotion Tiers title: Promotion Tiers properties: object: type: string default: list description: >- The type of the object represented by JSON. This object stores information about promotion tiers in a dictionary. data_ref: type: string default: tiers description: >- Identifies the name of the attribute that contains the array of promotion tier objects. tiers: type: array description: Contains array of promotion tier objects. items: $ref: '#/components/schemas/PromotionTier' total: type: integer description: Total number of promotion tiers. has_more: type: boolean description: >- As query results are always limited (by the limit parameter), the `has_more` flag indicates if there are more records for given filter parameters. This lets you know if you can run another request to get more records returned in the results. ValidationRulesAssignmentsList: title: Validation Rules Assignments List description: List of Validation Rules Assignments type: object properties: object: type: string default: list enum: - list description: >- The type of the object represented by JSON. This object stores information about validation rules assignments. data_ref: type: string default: data enum: - data description: >- Identifies the name of the attribute that contains the array of validation rules assignments. data: type: array description: Contains array of validation rules assignments. items: $ref: '#/components/schemas/BusValRuleAssignment' total: type: integer minimum: 0 description: Total number of validation rules assignments. required: - object - data_ref - data - total CampaignVoucher: type: object description: Schema model for a campaign voucher. title: Campaign Voucher properties: type: type: string description: Type of voucher. discount: description: Defines the voucher discount type and details. allOf: - $ref: '#/components/schemas/Discount' gift: description: Defines the voucher gift details. allOf: - $ref: '#/components/schemas/Gift' loyalty_card: description: Defines the voucher loyalty card details. allOf: - $ref: '#/components/schemas/CampaignLoyaltyCard' redemption: type: object description: Defines the redemption limits on vouchers. properties: quantity: type: integer nullable: true description: >- How many times a voucher can be redeemed. A `null` value means unlimited. required: - quantity code_config: allOf: - $ref: '#/components/schemas/CodeConfig' required: - length - charset - pattern is_referral_code: type: boolean description: >- Flag indicating whether this voucher is a referral code; `true` for campaign type `REFERRAL_PROGRAM`. start_date: type: string format: date-time description: >- Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is *inactive before* this date. example: '2022-09-20T00:00:00.000Z' expiration_date: type: string format: date-time description: >- Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is *inactive after* this date. example: '2022-09-30T00:00:00.000Z' validity_timeframe: $ref: '#/components/schemas/ValidityTimeframe' validity_day_of_week: $ref: '#/components/schemas/ValidityDayOfWeek' validity_hours: $ref: '#/components/schemas/ValidityHours' required: - type - redemption - code_config - is_referral_code Category: title: Category description: This is an object representing a category. type: object properties: id: type: string description: Unique category ID assigned by Voucherify. name: type: string description: Category name. hierarchy: type: integer description: >- Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value. minimum: 0 object: type: string default: category enum: - category description: >- The type of the object represented by the JSON. This object stores information about the category. created_at: type: string description: >- Timestamp representing the date and time when the category was created. The value is shown in the ISO 8601 format. example: '2022-07-14T10:45:13.156Z' format: date-time updated_at: type: string example: '2022-08-16T10:52:08.094Z' description: >- Timestamp representing the date and time when the category was updated. The value is shown in the ISO 8601 format. format: date-time required: - id - name - hierarchy - created_at - object ReferralProgram: title: Referral Program description: >- Defines the referee reward and the way a referral is triggered. Context: `REFERRAL_PROGRAM`. type: object properties: conversion_event_type: type: string enum: - redemption - custom_event description: Define how a referral is triggered. custom_event: type: object description: Contains details about the custom event. properties: id: type: string example: ms_Ll9enAm2BCN0M1s4VxWobLFM description: Unique custom event ID. name: type: string description: Custom event name. referee_reward: type: object description: Defines the referee reward. properties: related_object_parent: type: object description: Details of the resource from which the reward originates. properties: id: type: string example: camp_kdxp3vf1clQ9CFs1jpqv3tZe description: Unique ID of the reward source. name: type: string description: Name of the reward source. object: type: string default: CAMPAIGN enum: - CAMPAIGN description: Type of resource represented by the source of the reward. type: type: string enum: - LOYALTY_CARD - GIFT_VOUCHER description: Type of reward. amount: type: integer description: >- Define the number of `points` to add to a loyalty card or `credits` to the balance on a gift card. In case of the gift card, the value is multiplied by 100 to precisely represent 2 decimal places. For example, $100 amount is written as 10000. LoyaltyTiersExpirationAll: title: Loyalty Tiers Expiration type: object description: Defines the Loyalty Tiers Expiration. properties: qualification_type: type: string enum: - BALANCE - POINTS_IN_PERIOD description: >- Tier qualification. `BALANCE`: Points balance is based on the customer's current points balance. Customers qualify for the tier if their points balance is in the points range of the tier. `POINTS_IN_PERIOD`: A customer qualifies for the tier only if the sum of the accumulated points in a **defined time interval** reaches the tier threshold. qualification_period: type: string description: >- Customers can qualify for the tier if they collected enough points in a given time period. So, in addition to the customer having to reach a points range, they also need to have collected the points within a set time period. | **Period** | **Definition** | |:---|:---| | **Calendar Month** | Points collected in one calendar month
January, February, March, etc. | | **Calendar Quarter** | Points collected in the quarter
- January - March
- April - June
- July - September
- October - December | | **Calendar Half-year** | Points collected in the half-year
- January - June
- July - December | | **Calendar Year** | Points collected in one calendar year
January - December | enum: - MONTH - QUARTER - HALF_YEAR - YEAR start_date: type: object description: Defines the conditions for the start date of the tier. properties: type: type: string enum: - IMMEDIATE - NEXT_PERIOD description: |- What triggers the tier to be valid for a customer. `IMMEDIATE`: After reaching the minimum required points. `NEXT_PERIOD`: When the next qualification period starts. required: - type expiration_date: type: object description: Defines the conditions for the expiration date of a tier. properties: type: type: string enum: - END_OF_PERIOD - END_OF_NEXT_PERIOD - BALANCE_DROP - CUSTOM description: >- What triggers the tier to expire for a customer. `END_OF_PERIOD`: Expire tier at the end of the period. `END_OF_NEXT_PERIOD`: Expire tier at the end of the next period. `BALANCE_DROP`: Tier expires when the points balance drops below the required range of the tier. `CUSTOM`: Tier expires after a certain time period passes following the instance the points balance drops below the required range of the tier. extend: type: string description: >- Extend the expiration by adding extra months or days in ISO 8601 format. The tier will remain active even though it reaches its expiration time period. For example, a tier with a duration of `P3M` will be valid for an additional duration of 3 months and a tier with a duration of `P1D` will be valid for an additional duration of 1 day. rounding: description: Defines the rounding mechanism for tier expiration. properties: type: type: string enum: - MONTH - QUARTER - HALF_YEAR - YEAR - CUSTOM description: >- This mechanism describes a custom rounding for the expiration date. strategy: type: string enum: - START - END description: >- This mechanism describes a rounding strategy for the expiration date. unit: type: string description: >- Defines the type of unit of time in which the rounding period is counted. default: MONTH enum: - MONTH value: type: integer description: >- Value for the unit of time that the rounding applies to. Units for this parameter are defined by the `rounding.unit` parameter. - `0`: January - `1`: February - `2`: March - `3`: April - `4`: May - `5`: June - `6`: July - `7`: August - `8`: September - `9`: October - `10`: November - `11`: December required: - type - extend required: - qualification_type - start_date - expiration_date AccessSettingsCampaignAssignmentsList: title: Access Settings Campaign Assignments List type: object description: >- Lists all assignments of the campaign to areas and stores. For [GET List Campaigns](/api-reference/campaigns/list-campaigns), this is returned if the `expand=access_settings_assignments` query parameter is passed in the request. This object is not returned for the [GET Campaign summary endpoint](/api-reference/campaigns/get-campaign-summary). **NOTE**: This object is returned only if the Areas and Stores enterprise feature is enabled. Contact [Voucherify Sales](https://www.voucherify.io/contact-sales) to learn more. properties: object: type: string default: list description: >- The type of the object represented by JSON. Default is `list`. This object stores information about campaign assignments to areas and stores enum: - list data_ref: type: string default: data description: >- Identifies the name of the attribute that contains the array of campaign assignments. enum: - data data: type: array description: Contains an array of campaign assignments. items: $ref: '#/components/schemas/AreaStoreCampaignAssignment' total: type: integer description: Total number of areas and stores to which the campaign is assigned. minimum: 0 required: - object - data_ref - data - total PromotionTier: type: object description: >- This is an object representing a promotion tier. Promotion tiers are always assigned to a campaign and cannot be used standalone. title: Promotion Tier properties: id: type: string example: promo_63fYCt81Aw0h7lzyRkrGZh9p description: Unique promotion tier ID. created_at: type: string example: '2021-12-15T11:34:01.333Z' format: date-time description: >- Timestamp representing the date and time when the promotion tier was created. The value is shown in the ISO 8601 format. updated_at: type: string example: '2022-02-09T09:20:05.603Z' format: date-time description: >- Timestamp representing the date and time when the promotion tier was updated. The value is shown in the ISO 8601 format. name: type: string description: Name of the promotion tier. banner: type: string description: Text to be displayed to your customers on your website. action: type: object description: Contains details about the discount applied by the promotion tier. properties: discount: $ref: '#/components/schemas/Discount' metadata: type: object description: >- The metadata object stores all custom attributes assigned to the promotion tier. A set of key/value pairs that you can attach to a promotion tier object. It can be useful for storing additional information about the promotion tier in a structured format. hierarchy: type: integer description: >- The promotions hierarchy defines the order in which the discounts from different tiers will be applied to a customer's order. If a customer qualifies for discounts from more than one tier, discounts will be applied in the order defined in the hierarchy. promotion_id: type: string description: Promotion unique ID. campaign: type: object description: Contains details about promotion tier's parent campaign. properties: id: type: string description: Unique campaign ID. start_date: type: string description: >- Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is *inactive before* this date. format: date-time example: '2022-09-22T00:00:00.000Z' expiration_date: type: string format: date-time description: >- Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is *inactive after* this date. example: '2022-09-30T00:00:00.000Z' validity_timeframe: $ref: '#/components/schemas/ValidityTimeframe' validity_day_of_week: $ref: '#/components/schemas/ValidityDayOfWeek' validity_hours: $ref: '#/components/schemas/ValidityHours' active: type: boolean description: >- A flag indicating whether the campaign is active or not active. A campaign can be disabled even though it's within the active period defined by the `start_date` and `expiration_date` using the [Disable Campaign](/api-reference/disable-campaign) endpoint. - `true` indicates an *active* campaign - `false` indicates an *inactive* campaign category_id: type: string example: cat_0b688929a2476386a6 description: Unique category ID that this campaign belongs to. object: type: string description: >- The type of the object represented by the campaign object. This object stores information about the campaign. default: campaign campaign_id: type: string description: Promotion tier's parent campaign's unique ID. active: type: boolean description: >- A flag to toggle the promotion tier on or off. You can disable a promotion tier even though it's within the active period defined by the `start_date` and `expiration_date`. - `true` indicates an *active* promotion tier - `false` indicates an *inactive* promotion tier start_date: type: string description: >- Activation timestamp defines when the promotion tier starts to be active in ISO 8601 format. Promotion tier is *inactive before* this date. format: date-time example: '2022-09-23T00:00:00.000Z' expiration_date: type: string description: >- Activation timestamp defines when the promotion tier expires in ISO 8601 format. Promotion tier is *inactive after* this date. format: date-time example: '2022-09-26T00:00:00.000Z' validity_timeframe: $ref: '#/components/schemas/ValidityTimeframe' validity_day_of_week: $ref: '#/components/schemas/ValidityDayOfWeek' validity_hours: $ref: '#/components/schemas/ValidityHours' summary: type: object description: Contains statistics about promotion tier redemptions and orders. properties: redemptions: type: object description: Contains statistics about promotion tier redemptions. properties: total_redeemed: type: integer description: Number of times the promotion tier was redeemed. orders: type: object description: Contains statistics about orders related to the promotion tier. properties: total_amount: type: integer description: Sum of order totals. total_discount_amount: type: integer description: Sum of total discount applied using the promotion tier. object: type: string default: promotion_tier description: >- The type of the object represented by JSON. This object stores information about the promotion tier. validation_rule_assignments: $ref: '#/components/schemas/ValidationRuleAssignmentsList' category_id: type: string description: Promotion tier category ID. example: cat_0c9da30e7116ba6bba categories: type: array items: $ref: '#/components/schemas/Category' BusValRuleAssignment: title: Business Validation Rule Assignment description: Assignments of business validation rule example: id: asgm_LnY1g7UNFA9KyDrD rule_id: val_3gPNA6SnH4ae related_object_id: camp_CZOnEGiZfwIKWmSjhIoIT7Ol related_object_type: campaign object: validation_rules_assignment validation_status: PARTIALLY_VALID validation_omitted_rules: - '1' properties: id: type: string description: The unique identifier for a assignment rule_id: type: string description: The unique identifier for a rule related_object_id: type: string description: The unique identifier for a related object related_object_type: type: string description: The type of related object created_at: type: string description: >- Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format. example: '2022-03-09T11:19:04.819Z' format: date-time updated_at: type: string description: >- Timestamp representing the date and time when the object was last updated in ISO 8601 format. example: '2022-03-09T11:19:04.819Z' format: date-time object: type: string description: The type of the object represented by JSON. default: validation_rules_assignment enum: - validation_rules_assignment validation_status: type: string description: The validation status of the assignment enum: - VALID - PARTIALLY_VALID - INVALID validation_omitted_rules: type: array description: The list of omitted rules items: type: string required: - id - rule_id - related_object_id - related_object_type - object Discount: title: Discount type: object description: Contains information about discount. oneOf: - $ref: '#/components/schemas/DiscountAmount' - $ref: '#/components/schemas/DiscountUnit' - $ref: '#/components/schemas/DiscountUnitMultiple' - $ref: '#/components/schemas/DiscountPercent' - $ref: '#/components/schemas/DiscountFixed' Gift: title: Gift type: object description: Contains current gift card balance information. properties: amount: type: number description: >- Total gift card income over the lifetime of the card. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. subtracted_amount: type: integer description: Total amount of subtracted credits over the gift card lifetime. balance: type: number description: >- Available funds. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. `balance` = `amount` - `subtracted_amount` - `redemption.redeemed_amount`. effect: type: string description: Defines how the credits are applied to the customer's order. enum: - APPLY_TO_ORDER - APPLY_TO_ITEMS required: - amount - balance CampaignLoyaltyCard: type: object description: Schema model for a campaign loyalty card. title: Campaign Loyalty Card properties: points: type: integer description: >- The initial number of points to assign to the loyalty card. This is the current loyalty card score i.e. the number of loyalty points on the card. expiration_rules: type: object description: >- Defines the loyalty point expiration rule. This expiration rule applies when there are no `expiration_rules` defined for an earning rule. properties: period_type: type: string description: >- Type of period. Can be set for `MONTH` or `FIXED_DAY_OF_YEAR`. `MONTH` requires the `period_value` field. `FIXED_DAY_OF_YEAR` requires the `fixed_month` and `fixed_day` fields. enum: - FIXED_DAY_OF_YEAR - MONTH period_value: type: integer description: 'Value of the period. Required for the `period_type: MONTH`.' rounding_type: type: string description: >- Type of rounding of the expiration period. Optional for the `period_type: MONTH`. enum: - END_OF_MONTH - END_OF_QUARTER - END_OF_HALF_YEAR - END_OF_YEAR - PARTICULAR_MONTH rounding_value: type: integer description: >- Value of rounding of the expiration period. Required for the `rounding_type`. fixed_month: type: integer description: >- Determines the month when the points expire; `1` is January, `2` is February, and so on. Required for the `period_type: FIXED_DAY_OF_YEAR`. minimum: 1 maximum: 12 fixed_day: type: integer description: >- Determines the day of the month when the points expire. Required for the `period_type: FIXED_DAY_OF_YEAR`. minimum: 1 maximum: 31 required: - period_type required: - points AreaStoreCampaignAssignment: title: Areas and Stores Campain Assignment type: object description: An object representing an assignment of a campaign to an area or store. properties: id: type: string description: Unique identifier of the campaign assignment. example: arsca_0ef5ee192117ae2416 area_id: type: string description: Unique identifier of the area to which the campaign is assigned. example: ar_0ea6cd7b781b8f857f all_stores: type: boolean description: >- Determines if the campaign is assigned to all of the stores in the area, i.e. if an area ID is passed in the `access_settings.assign.area_all_stores_ids` in the request. area_store_id: type: string description: Unique identifier of the store to which the campaign is assigned. example: ars_0ec347e2016bed85f4 created_at: type: string description: >- Date and time when the assignment was made. The value is shown in the ISO 8601 format. format: date-time example: '2024-06-25T19:04:16.260Z' object: type: string description: >- The type of the object represented by JSON. This object stores information about the campaign assignment to areas or stores. default: area_store_campaign_assignment enum: - area_store_campaign_assignment required: - id - area_id - created_at - object ValidationRuleAssignmentsList: type: object description: Validation Rule Assignments List title: Validation Rule Assignments List properties: object: type: string description: >- The type of the object represented by JSON. This object stores information about validation rule assignments. default: list data_ref: type: string description: >- Identifies the name of the JSON property that contains the array of validation rule assignments. default: data data: type: array description: A dictionary that contains an array of validation rule assignments. items: $ref: '#/components/schemas/ValidationRuleAssignment' total: type: integer description: Total number of validation rule assignments. required: - object - data_ref - data - total DiscountAmount: type: object title: Amount properties: type: type: string default: AMOUNT enum: - AMOUNT description: Defines the type of the voucher. amount_off: type: number description: >- Amount taken off the subtotal of a price. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000. amount_off_formula: type: string description: Formula used to dynamically calculate the discount. aggregated_amount_limit: type: integer description: Maximum discount amount per order. effect: description: Defines how the discount is applied to the customer's order. allOf: - $ref: '#/components/schemas/DiscountAmountVouchersEffectTypes' is_dynamic: type: boolean description: Flag indicating whether the discount was calculated using a formula. required: - type - amount_off DiscountUnit: type: object title: Unit properties: type: type: string default: UNIT enum: - UNIT description: Discount type. unit_off: type: integer description: Number of units to be granted a full value discount. unit_off_formula: type: string description: Formula used to dynamically calculate the number of units. effect: description: Defines how the unit is added to the customer's order. allOf: - $ref: '#/components/schemas/DiscountUnitVouchersEffectTypes' unit_type: type: string description: >- The product deemed as free, chosen from product inventory (e.g. time, items). product: description: Contains information about the product. allOf: - $ref: '#/components/schemas/SimpleProductDiscountUnit' sku: $ref: '#/components/schemas/SimpleSkuDiscountUnit' is_dynamic: type: boolean description: Flag indicating whether the discount was calculated using a formula. required: - type - unit_type DiscountUnitMultiple: type: object title: Unit Multiple properties: type: type: string default: UNIT enum: - UNIT description: Discount type. effect: type: string default: ADD_MANY_ITEMS enum: - ADD_MANY_ITEMS description: Defines how the discount is applied to the customer's order. units: type: array items: $ref: '#/components/schemas/DiscountUnitMultipleOneUnit' required: - type - units DiscountPercent: type: object title: Percent properties: type: type: string default: PERCENT enum: - PERCENT description: Defines the type of the voucher. percent_off: type: number description: The percent discount that the customer will receive. percent_off_formula: type: string description: Formula used to dynamically calculate the discount. amount_limit: type: number description: >- Upper limit allowed to be applied as a discount. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $6 maximum discount is written as 600. aggregated_amount_limit: type: integer description: Maximum discount amount per order. effect: description: Defines how the discount is applied to the customer's order. allOf: - $ref: '#/components/schemas/DiscountPercentVouchersEffectTypes' is_dynamic: type: boolean description: Flag indicating whether the discount was calculated using a formula. required: - type - percent_off DiscountFixed: title: Fixed type: object properties: type: type: string default: FIXED enum: - FIXED description: Defines the type of the voucher. fixed_amount: type: number description: >- Sets a fixed value for an order total or the item price. The value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000. If the fixed amount is calculated by the formula, i.e. the `fixed_amount_formula` parameter is present in the fixed amount definition, this value becomes the **fallback value**. As a result, if the formula cannot be calculated due to missing metadata, for example, this value will be used as the fixed value. fixed_amount_formula: type: string description: Formula used to dynamically calculate the discount. effect: description: Defines how the discount is applied to the customer's order. allOf: - $ref: '#/components/schemas/DiscountFixedVouchersEffectTypes' is_dynamic: type: boolean description: Flag indicating whether the discount was calculated using a formula. required: - type - fixed_amount ValidationRuleAssignment: title: Validation Rule Assignment type: object description: This is an object representing a validation rule assignment. properties: id: type: string example: asgm_74F7QZoYbUoljwQO description: Validation rule assignment ID. rule_id: type: string example: val_4j7DCRm2IS59 description: Validation rule ID. related_object_id: type: string example: v_JtWunK6jUo7X2qOFj0SyRHq4p9tgENlT description: The resource ID to which the validation rule was assigned. related_object_type: type: string description: The type of resource to which the validation rule was assigned. enum: - voucher - campaign - earning_rule - reward_assignment - promotion_tier - distribution created_at: type: string example: '2022-02-17T08:18:15.085Z' description: >- Timestamp representing the date and time when the validation rule assignment was created. The value is shown in the ISO 8601 format. format: date-time object: type: string default: validation_rules_assignment description: The type of the object represented by the ID. enum: - validation_rules_assignment required: - id - rule_id - related_object_id - related_object_type - created_at - object DiscountAmountVouchersEffectTypes: title: Discount Amount Vouchers Effect Types enum: - APPLY_TO_ORDER - APPLY_TO_ITEMS - APPLY_TO_ITEMS_PROPORTIONALLY - APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY - APPLY_TO_ITEMS_BY_QUANTITY type: string DiscountUnitVouchersEffectTypes: title: Discount Unit Vouchers Effect Types enum: - ADD_MISSING_ITEMS - ADD_NEW_ITEMS - ADD_MANY_ITEMS - ADD_SAME_ITEMS type: string SimpleProductDiscountUnit: type: object title: Simple Product Discount Unit properties: id: type: string description: Unique product ID, assigned by Voucherify. source_id: type: string description: Product's source ID. name: type: string description: Product name. required: - id - name SimpleSkuDiscountUnit: type: object title: Simple Sku Discount Unit properties: id: type: string description: Unique SKU ID, assigned by Voucherify. source_id: type: string description: Product variant's source ID. name: type: string description: Sku name required: - id - name DiscountUnitMultipleOneUnit: type: object title: One Unit properties: unit_off: type: number description: Number of units to be granted a full value discount. unit_off_formula: type: string description: Formula used to dynamically calculate the number of units. effect: type: string enum: - ADD_NEW_ITEMS - ADD_MISSING_ITEMS description: |+ Defines how the unit is added to the customer's order. unit_type: type: string description: >- The product deemed as free, chosen from product inventory (e.g. time, items). product: description: Contains information about the product. allOf: - $ref: '#/components/schemas/SimpleProductDiscountUnit' sku: description: Contains information about the sku. allOf: - $ref: '#/components/schemas/SimpleSkuDiscountUnit' required: - effect - unit_type DiscountPercentVouchersEffectTypes: title: Discount Percent Vouchers Effect Types enum: - APPLY_TO_ORDER - APPLY_TO_ITEMS type: string DiscountFixedVouchersEffectTypes: title: Discount Fixed Vouchers Effect Types enum: - APPLY_TO_ORDER - APPLY_TO_ITEMS type: string securitySchemes: X-App-Id: type: apiKey name: X-App-Id in: header X-App-Token: type: apiKey name: X-App-Token in: header X-Voucherify-OAuth: type: oauth2 flows: implicit: authorizationUrl: https://api.voucherify.io/v1/oauth/token scopes: api: Gives access to whole server-side API. vouchers: >- Gives access to all endpoints and methods starting with `v1/vouchers`. client_api: Gives access to whole client-side API. client_vouchers: >- Gives access to all endpoints and methods starting with `/client/v1/vouchers`. promotions: >- Gives access to all endpoints and methods starting with `/v1/promotions`. client_promotions: >- Gives access to all endpoints and methods starting with `/client/v1/promotions` campaigns: >- Gives access to all endpoints and methods starting with `v1/campaigns`. client_publish: >- Gives access to all endpoints and methods starting with `/client/v1/publish`. exports: >- Gives access to all endpoints and methods starting with `/v1/exports`. publications: >- Gives access to all endpoints and methods starting with `/v1/publications`. client_validate: >- Gives access to all endpoints and methods starting with `/client/v1/validate`. validations: >- Gives access to all endpoints and methods starting with `/v1/validations`. client_validations: >- Gives access to all endpoints and methods starting with `/client/v1/validations`. qualifications: >- Gives access to all endpoints and methods starting with `/v1/qualifications`. client_qualifications: >- Gives access to all endpoints and methods starting with `/client/v1/qualifications`. client_redeem: >- Gives access to all endpoints and methods starting with `/client/v1/redeem redemptions: >- Gives access to all endpoints and methods starting with `/v1/redemptions`. client_redemptions: >- Gives access to all endpoints and methods starting with `/client/v1/redemptions` customers: >- Gives access to all endpoints and methods starting with `/v1/customers`. client_customers: >- Gives access to all endpoints and methods starting with `/client/v1/customers`. orders: >- Gives access to all endpoints and methods starting with `/v1/orders`. products: >- Gives access to all endpoints and methods starting with `/v1/products`. skus: >- Gives access to all endpoints and methods starting with `/v1/SKUs`. validation-rules: >- Gives access to all endpoints and methods starting with `/v1/validation-rules`. validation-rules-assignments: >- Gives access to all endpoints and methods starting with `/v1/validation-rules-assignments segments: >- Gives access to all endpoints and methods starting with `/v1/segments`. events: >- Gives access to all endpoints and methods starting with `/v1/events`. client_events: >- Gives access to all endpoints and methods starting with `client/v1/events`. rewards: >- Gives access to all endpoints and methods starting with `/v1/rewards`. assets: >- Gives access to all endpoints and methods starting with `/v1/assets`. task-results: >- Gives access to all endpoints and methods starting with `/v1/task-results`. loyalties: >- Gives access to all endpoints and methods starting with `/v1/loyalties`. client_consents: >- Gives access to all endpoints and methods starting with `client/v1/consents`. consents: >- Gives access to all endpoints and methods starting with `/v1/consents`. async-actions: >- Gives access to all endpoints and methods starting with `/v1/async-actions`. product-collections: >- Gives access to all endpoints and methods starting with `/v1/product-collections`. categories: >- Gives access to all endpoints and methods starting with `/v1/categories`. metadata-schemas: >- Gives access to all endpoints and methods starting with `/v1/metadata-schemas`. locations: >- Gives access to all endpoints and methods starting with `/v1/locations`. referrals: >- Gives access to all endpoints and methods starting with `/v1/referrals`. trash-bin: >- Gives access to all endpoints and methods starting with `/v1/trash-bin`. templates: >- Gives access to all endpoints and methods starting with `/v1/templates`. ````