---
title: "Create Loyalty Campaign"
method: POST
path: "/v1/loyalties"
tags: ["Loyalties"]
---

# Create Loyalty Campaign

`POST /v1/loyalties`

Creates a batch of [loyalty cards](/api-reference/loyalties/get-member) aggregated in a single loyalty campaign. It also allows you to define a custom codes pattern.  


> 📘 Global uniqueness
> All codes are unique across the whole project. Voucherify won't allow to generate the same codes in any of your campaigns.


> 🚧 Asynchronous action!
>
> This is an asynchronous action, you can't read or modify a newly created campaign until the code generation is completed. See `creation_status` field in the [loyalty campaign object](/api-reference/loyalties/loyalty-campaign-object) description.

## Request body

- LoyaltiesCreateCampaignRequestBody — Body schema for creating a campaign of loyalty type using **POST** `v1/campaigns`.
  - `name` string — Campaign name.
  - `description` string — An optional field to keep any extra textual information about the campaign such as a campaign description and details.
  - `type` 'AUTO_UPDATE' | 'STATIC' | 'STANDALONE' — 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`: the campaign is a generic (standalone) one with a single voucher for public use (only for discount and gift card campaigns)
  - `join_once` boolean — 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` boolean — Indicates whether customers will be able to auto-join a loyalty campaign if any earning rule is fulfilled.
  - `use_voucher_metadata_schema` boolean — Flag indicating whether the campaign is to use the voucher's metadata schema instead of the campaign metadata schema.
  - `vouchers_count` integer — Total number of unique vouchers in campaign (size of campaign).
  - `start_date` string, date-time — Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is *inactive before* this date.
  - `expiration_date` string, date-time — Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is *inactive after* this date.
  - `validity_timeframe` ValidityTimeframe — 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`.
    - `duration` string — 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.
    - `interval` string — 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.
  - `validity_day_of_week` integer[] — 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
  - `validity_hours` ValidityHours — Determines the hours of validity, e.g. to create a happy hours scenario.
    - `daily` object[] — Defines the recurring period(s) when the resource is active. The periods should not overlap.
      - `start_time` string, time — Defines the starting hour of validity in the HH:mm format. The resource is *inactive before* this time.
      - `days_of_week` integer[] — 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
      - `expiration_time` string, time — Defines the ending hour of validity in the HH:mm format. The resource is *inactive after* this time.
  - `activity_duration_after_publishing` string — 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` string — Unique category ID that this campaign belongs to. Either pass this parameter OR the `category`.
  - `category` string — The category assigned to the campaign. Either pass this parameter OR the `category_id`.
  - `metadata` object — 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` AccessSettings — 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.
    - `assign` object — 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.
      - `areas_ids` string[] — List all area IDs to which the campaign will be assigned.
      - `area_stores_ids` string[] — List all store IDs to which the campaign will be assigned.
      - `area_all_stores_ids` string[] — 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.
    - `unassign` object — 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.
      - `areas_ids` string[] — List all area IDs from which the campaign will be unassigned.
      - `area_stores_ids` string[] — List all store IDs from which the campaign will be unassigned.
      - `area_all_stores_ids` string[] — 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.
  - `campaign_type` 'LOYALTY_PROGRAM' — Type of campaign.
  - `voucher` CampaignLoyaltyVoucher — Schema model for a discount voucher.
    - `type` 'LOYALTY_CARD', required — Type of voucher.
    - `loyalty_card` CampaignLoyaltyCard, required — Schema model for a campaign loyalty card.
      - `points` integer, required — 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` object — Defines the loyalty point expiration rule. This expiration rule applies when there are no `expiration_rules` defined for an earning rule.
        - `period_type` 'FIXED_DAY_OF_YEAR' | 'MONTH', required — 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.
        - `period_value` integer — Value of the period. Required for the `period_type: MONTH`.
        - `rounding_type` 'END_OF_MONTH' | 'END_OF_QUARTER' | 'END_OF_HALF_YEAR' | 'END_OF_YEAR' | 'PARTICULAR_MONTH' — Type of rounding of the expiration period. Optional for the `period_type: MONTH`.
        - `rounding_value` integer — Value of rounding of the expiration period. Required for the `rounding_type`.
        - `fixed_month` integer — 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`.
        - `fixed_day` integer — Determines the day of the month when the points expire. Required for the `period_type: FIXED_DAY_OF_YEAR`.
    - `redemption` object — Defines the redemption limits on vouchers.
      - `quantity` integer, nullable — How many times a voucher can be redeemed. A `null` value means unlimited.
    - `code_config` CodeConfig — Contains information about the config used for the voucher code. Defines the code's pattern (prefix, postfix, length, charset, etc).
      - `length` number — Number of characters in a generated code (excluding prefix and postfix).
      - `charset` string — 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` string — A text appended before the code.
      - `postfix` string — A text appended after the code.
      - `pattern` string — A pattern for codes where hashes (#) will be replaced with random characters. Overrides `length`.
      - `initial_count` integer — Internal value, does not change anything if provided.

## Response `200`

Returns a campaign object with its settings but without the loyalty card codes.

- LoyaltiesCreateCampaignResponseBody
  - `id` string, required — Unique campaign ID, assigned by Voucherify.
  - `name` string, required — Campaign name.
  - `description` string — An optional field to keep any extra textual information about the campaign such as a campaign description and details.
  - `campaign_type` 'LOYALTY_PROGRAM', required — Type of campaign.
  - `type` 'AUTO_UPDATE' | 'STATIC', required — Defines whether the campaign can be updated with new vouchers after campaign creation. - `AUTO_UPDATE`: the campaign is dynamic, i.e. vouchers will generate based on set criteria - `STATIC`: vouchers need to be manually published
  - `voucher` LoyaltyCampaignVoucher — Schema model for a campaign voucher.
    - `type` 'LOYALTY_CARD', required — Type of voucher.
    - `loyalty_card` CampaignLoyaltyCard — Schema model for a campaign loyalty card.
      - `points` integer, required — 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` object — Defines the loyalty point expiration rule. This expiration rule applies when there are no `expiration_rules` defined for an earning rule.
        - `period_type` 'FIXED_DAY_OF_YEAR' | 'MONTH', required — 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.
        - `period_value` integer — Value of the period. Required for the `period_type: MONTH`.
        - `rounding_type` 'END_OF_MONTH' | 'END_OF_QUARTER' | 'END_OF_HALF_YEAR' | 'END_OF_YEAR' | 'PARTICULAR_MONTH' — Type of rounding of the expiration period. Optional for the `period_type: MONTH`.
        - `rounding_value` integer — Value of rounding of the expiration period. Required for the `rounding_type`.
        - `fixed_month` integer — 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`.
        - `fixed_day` integer — Determines the day of the month when the points expire. Required for the `period_type: FIXED_DAY_OF_YEAR`.
    - `redemption` object, required — Defines the redemption limits on vouchers.
      - `quantity` integer, nullable, required — How many times a voucher can be redeemed. A `null` value means unlimited.
    - `code_config` CodeConfig, required — Contains information about the config used for the voucher code. Defines the code's pattern (prefix, postfix, length, charset, etc).
      - `length` number — Number of characters in a generated code (excluding prefix and postfix).
      - `charset` string — 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` string — A text appended before the code.
      - `postfix` string — A text appended after the code.
      - `pattern` string — A pattern for codes where hashes (#) will be replaced with random characters. Overrides `length`.
      - `initial_count` integer — Internal value, does not change anything if provided.
    - `is_referral_code` boolean, required — Always `false` for a loyalty card voucher
    - `start_date` string, date-time — Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is *inactive before* this date.
    - `expiration_date` string, date-time — Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is *inactive after* this date.
    - `validity_timeframe` ValidityTimeframe — 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`.
      - `duration` string — 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.
      - `interval` string — 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.
    - `validity_day_of_week` integer[] — 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
    - `validity_hours` ValidityHours — Determines the hours of validity, e.g. to create a happy hours scenario.
      - `daily` object[] — Defines the recurring period(s) when the resource is active. The periods should not overlap.
        - `start_time` string, time — Defines the starting hour of validity in the HH:mm format. The resource is *inactive before* this time.
        - `days_of_week` integer[] — 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
        - `expiration_time` string, time — Defines the ending hour of validity in the HH:mm format. The resource is *inactive after* this time.
  - `auto_join` boolean, required — Indicates whether customers will be able to auto-join a loyalty campaign if any earning rule is fulfilled.
  - `join_once` boolean, required — Always set to `true` for loyalty campaigns, meaning customers can join the campaign only once. It can't be changed to `false`.
  - `use_voucher_metadata_schema` boolean, required — Flag indicating whether the campaign is to use the voucher's metadata schema instead of the campaign metadata schema.
  - `validity_timeframe` ValidityTimeframe — 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`.
    - `duration` string — 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.
    - `interval` string — 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.
  - `validity_day_of_week` integer[] — 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
  - `validity_hours` ValidityHours — Determines the hours of validity, e.g. to create a happy hours scenario.
    - `daily` object[] — Defines the recurring period(s) when the resource is active. The periods should not overlap.
      - `start_time` string, time — Defines the starting hour of validity in the HH:mm format. The resource is *inactive before* this time.
      - `days_of_week` integer[] — 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
      - `expiration_time` string, time — Defines the ending hour of validity in the HH:mm format. The resource is *inactive after* this time.
  - `activity_duration_after_publishing` string — Defines the amount of time the campaign will be active in ISO 8601 format after publishing. For example, a campaign with a `duration` of `P24D` will be valid for a duration of 24 days.
  - `vouchers_count` integer — Total number of unique vouchers in campaign.
  - `start_date` string, date-time — Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is *inactive before* this date.
  - `expiration_date` string, date-time — Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is *inactive after* this date.
  - `active` boolean — 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` object — 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` string, date-time, required — Timestamp representing the date and time when the campaign was created. The value is shown in the ISO 8601 format.
  - `updated_at` string, date-time — Timestamp representing the date and time when the campaign was last updated in ISO 8601 format.
  - `category` string — Unique category name.
  - `creation_status` 'DONE' | 'IN_PROGRESS' | 'FAILED' | 'DRAFT' | 'MODIFYING', required — Indicates the status of the campaign creation.
  - `vouchers_generation_status` 'DONE' | 'IN_PROGRESS' | 'FAILED' | 'DRAFT' | 'MODIFYING', required — Indicates the status of the campaign's voucher generation.
  - `readonly` boolean — 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.
  - `protected` boolean, required — Indicates whether the resource can be deleted.
  - `category_id` string, nullable, required — Unique category ID that this campaign belongs to.
  - `categories` Category[], required — Contains details about the category.
    - `id` string, required — Unique category ID assigned by Voucherify.
    - `name` string, required — Category name.
    - `hierarchy` integer, required — Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
    - `object` 'category', required — The type of the object represented by the JSON. This object stores information about the category.
    - `created_at` string, date-time, required — Timestamp representing the date and time when the category was created. The value is shown in the ISO 8601 format.
    - `updated_at` string, date-time — Timestamp representing the date and time when the category was updated. The value is shown in the ISO 8601 format.
  - `object` string, required — The type of the object represented by JSON. This object stores information about the campaign.
  - `loyalty_tiers_expiration` LoyaltyTiersExpirationAll — Defines the Loyalty Tiers Expiration.
    - `qualification_type` 'BALANCE' | 'POINTS_IN_PERIOD', required — 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` 'MONTH' | 'QUARTER' | 'HALF_YEAR' | 'YEAR' — 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<br />January, February, March, etc. | | **Calendar Quarter** | Points collected in the quarter<br />- January - March<br />- April - June<br />- July - September<br />- October - December | | **Calendar Half-year** | Points collected in the half-year<br />- January - June<br />- July - December | | **Calendar Year** | Points collected in one calendar year<br />January - December |
    - `start_date` object, required — Defines the conditions for the start date of the tier.
      - `type` 'IMMEDIATE' | 'NEXT_PERIOD', required — 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.
    - `expiration_date` object, required — Defines the conditions for the expiration date of a tier.
      - `type` 'END_OF_PERIOD' | 'END_OF_NEXT_PERIOD' | 'BALANCE_DROP' | 'CUSTOM', required — 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` string, required — 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` object — Defines the rounding mechanism for tier expiration.
        - `type` 'MONTH' | 'QUARTER' | 'HALF_YEAR' | 'YEAR' | 'CUSTOM' — This mechanism describes a custom rounding for the expiration date.
        - `strategy` 'START' | 'END' — This mechanism describes a rounding strategy for the expiration date.
        - `unit` 'MONTH' — Defines the type of unit of time in which the rounding period is counted.
        - `value` integer — 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
  - `validation_rules_assignments` ValidationRulesAssignmentsList — List of Validation Rules Assignments
    - `object` 'list', required — The type of the object represented by JSON. This object stores information about validation rules assignments.
    - `data_ref` 'data', required — Identifies the name of the attribute that contains the array of validation rules assignments.
    - `data` BusValRuleAssignment[], required — Contains array of validation rules assignments.
      - `id` string, required — The unique identifier for a assignment
      - `rule_id` string, required — The unique identifier for a rule
      - `related_object_id` string, required — The unique identifier for a related object
      - `related_object_type` string, required — The type of related object
      - `created_at` string, date-time — Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format.
      - `updated_at` string, date-time — Timestamp representing the date and time when the object was last updated in ISO 8601 format.
      - `object` 'validation_rules_assignment', required — The type of the object represented by JSON.
      - `validation_status` 'VALID' | 'PARTIALLY_VALID' | 'INVALID' — The validation status of the assignment
      - `validation_omitted_rules` string[] — The list of omitted rules
    - `total` integer, required — Total number of validation rules assignments.
  - `access_settings_assignments` AccessSettingsCampaignAssignmentsList — 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.
    - `object` 'list', required — The type of the object represented by JSON. Default is `list`. This object stores information about campaign assignments to areas and stores
    - `data_ref` 'data', required — Identifies the name of the attribute that contains the array of campaign assignments.
    - `data` AreaStoreCampaignAssignment[], required — Contains an array of campaign assignments.
      - `id` string, required — Unique identifier of the campaign assignment.
      - `area_id` string, required — Unique identifier of the area to which the campaign is assigned.
      - `all_stores` boolean — 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` string — Unique identifier of the store to which the campaign is assigned.
      - `created_at` string, date-time, required — Date and time when the assignment was made. The value is shown in the ISO 8601 format.
      - `object` 'area_store_campaign_assignment', required — The type of the object represented by JSON. This object stores information about the campaign assignment to areas or stores.
    - `total` integer, required — Total number of areas and stores to which the campaign is assigned.

## Other responses

- `409` — Returns an error if a loyalty campaign with the same name already exists.

---

[API](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-api-async-actions/versions/4982266e0494/schema)