> ## 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. # List Campaigns > Retrieve a list of campaigns in a project. The campaigns are returned sorted by creation date, with the most recent campaigns appearing first. When you get a list of campaigns, you can optionally specify query parameters to customize the amount of campaigns returned per call using `limit`, which page of campaigns to return using `page`, sort the campaigns using the `order` query parameter and filter the results by the `campaign_type`. This method will return an error when trying to return a limit of more than 100 campaigns. ## OpenAPI ````yaml /openapi/campaigns.json get /v1/campaigns openapi: 3.0.1 info: title: Voucherify API - Campaigns 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/campaigns: get: tags: - Campaigns summary: List Campaigns description: >- Retrieve a list of campaigns in a project. The campaigns are returned sorted by creation date, with the most recent campaigns appearing first. When you get a list of campaigns, you can optionally specify query parameters to customize the amount of campaigns returned per call using `limit`, which page of campaigns to return using `page`, sort the campaigns using the `order` query parameter and filter the results by the `campaign_type`. This method will return an error when trying to return a limit of more than 100 campaigns. operationId: list-campaigns parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/campaign_type' - schema: $ref: '#/components/schemas/ParameterExpandListCampaigns' in: query name: expand description: >- Includes an expanded `categories` object in the response. If the [Areas and Stores](/orchestrate/areas-and-stores) Enterprise feature is enabled, add `access_settings_assignments` to return assigned areas and stores. - schema: $ref: '#/components/schemas/ParameterCampaignStatusListCampaigns' in: query name: campaign_status description: Sorts the results by the status of the campaign. - schema: $ref: '#/components/schemas/ParameterIsReferralCodeListCampaigns' in: query name: is_referral_code description: Sorts the results that are or are not referral campaigns. - schema: $ref: '#/components/schemas/ParameterOrderListCampaigns' in: query name: order description: >- Sorts the results using one of the filtering options, where the dash `-` preceding a sorting option means sorting in a descending order. - schema: $ref: '#/components/schemas/ParameterFiltersListCampaigns' in: query name: filters description: Filters the results by various campaign properties. style: deepObject explode: true - schema: $ref: '#/components/schemas/ParameterCampaignsAccessSetttings' in: query name: access_settings description: >- Filter by areas and stores IDs to return campaigns that are assigned to areas, stores, and all stores in an area. style: deepObject explode: true responses: '200': description: >- Returns a dictionary with a `campaign` property that contains an array of campaigns. The maximum number of campaigns returned is determined by the `limit` query parameter. Each entry in the array is a separate campaign object. If no more campaigns are available, the resulting array on a given page will be empty. content: application/json: schema: $ref: '#/components/schemas/CampaignsListResponseBody' examples: Example: value: object: list data_ref: campaigns campaigns: - id: camp_SibPsDRKQvg3SUtptgPZCNZb name: Voucher Metadata campaign_type: DISCOUNT_COUPONS type: AUTO_UPDATE voucher: type: DISCOUNT_VOUCHER discount: type: PERCENT amount_limit: 4400 percent_off: 30 effect: APPLY_TO_ORDER redemption: quantity: null code_config: length: 9 charset: >- 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ pattern: '#########' prefix: Discount- postfix: YY is_referral_code: false start_date: '2022-09-20T00:00:00.000Z' expiration_date: '2022-09-30T00:00:00.000Z' validity_timeframe: interval: P3D duration: P1D auto_join: false join_once: false use_voucher_metadata_schema: false start_date: '2022-09-20T00:00:00.000Z' expiration_date: '2022-09-30T00:00:00.000Z' validity_timeframe: interval: P3D duration: P1D validity_day_of_week: - 1 - 2 - 3 - 4 activity_duration_after_publishing: P24D vouchers_count: 1 active: true metadata: region: AMER created_at: '2022-09-20T09:32:29.530Z' creation_status: DONE vouchers_generation_status: DONE protected: false category_id: null object: campaign - id: camp_HgsbCKauXmEoPnnh8aas0ISe name: Static Campaign campaign_type: DISCOUNT_COUPONS type: STATIC voucher: type: DISCOUNT_VOUCHER discount: type: AMOUNT amount_off: 3000 effect: APPLY_TO_ORDER redemption: quantity: 1 code_config: length: 8 charset: >- 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ pattern: '########' is_referral_code: false auto_join: false join_once: true use_voucher_metadata_schema: true vouchers_count: 1 active: true metadata: {} created_at: '2022-09-20T07:52:34.499Z' updated_at: '2022-09-20T11:38:13.501Z' creation_status: DONE vouchers_generation_status: DONE protected: false category_id: null object: campaign - id: camp_f7fBbQxUuTN7dI7tGOo5XMDA name: Loyalty Program Fall 2022 campaign_type: LOYALTY_PROGRAM type: AUTO_UPDATE voucher: type: LOYALTY_CARD loyalty_card: points: 0 expiration_rules: period_type: MONTH period_value: 7 rounding_type: END_OF_YEAR redemption: quantity: null code_config: length: 8 charset: >- 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ pattern: '########' prefix: LOYALTY-CARD- is_referral_code: false auto_join: true join_once: true use_voucher_metadata_schema: true vouchers_count: 1 active: true metadata: {} created_at: '2022-09-19T07:56:22.103Z' creation_status: DONE vouchers_generation_status: DONE protected: false category_id: cat_0bb343dee3cdb5ec0c object: campaign - id: camp_4tHsQEDUOER6PeW8SoMdnHH6 name: Dynamic Discounts campaign_type: DISCOUNT_COUPONS type: AUTO_UPDATE voucher: type: DISCOUNT_VOUCHER discount: type: PERCENT percent_off: 5 percent_off_formula: IF(ORDER_AMOUNT > 300;15;5) effect: APPLY_TO_ORDER redemption: quantity: null code_config: length: 8 charset: >- 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ pattern: '########' prefix: DYNAMIC- is_referral_code: false auto_join: false join_once: false use_voucher_metadata_schema: true vouchers_count: 1 active: true metadata: marketing_text: >- Purchases above $300 are eligible for a 15% discount. created_at: '2022-07-12T15:12:02.575Z' updated_at: '2022-07-20T10:48:05.617Z' category: test creation_status: DONE vouchers_generation_status: DONE protected: false category_id: cat_0b688929a2476386a8 object: campaign - id: camp_JlsseNSDO7l4neFtev6p6945 name: $20 OFF Entire Order campaign_type: DISCOUNT_COUPONS type: AUTO_UPDATE voucher: type: DISCOUNT_VOUCHER discount: type: AMOUNT amount_off: 2000 effect: APPLY_TO_ORDER redemption: quantity: null code_config: length: 8 charset: >- 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ pattern: '########' prefix: $20OFFORDER- is_referral_code: false auto_join: false join_once: false use_voucher_metadata_schema: true vouchers_count: 1 active: true metadata: {} created_at: '2022-07-11T09:43:36.057Z' creation_status: DONE vouchers_generation_status: DONE protected: false category_id: null object: campaign - id: camp_Uj3cNbWSgt7Zl4AyHM7Sa5Qk name: 3% OFF Entire Order campaign_type: DISCOUNT_COUPONS type: AUTO_UPDATE voucher: type: DISCOUNT_VOUCHER discount: type: PERCENT percent_off: 3 effect: APPLY_TO_ORDER redemption: quantity: null code_config: length: 8 charset: >- 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ pattern: '########' prefix: 3%OFFORDER- is_referral_code: false auto_join: false join_once: false use_voucher_metadata_schema: true vouchers_count: 1 active: true metadata: {} created_at: '2022-07-11T09:41:12.087Z' creation_status: DONE vouchers_generation_status: DONE protected: false category_id: null object: campaign total: 6 security: - X-App-Id: [] X-App-Token: [] - X-Voucherify-OAuth: - api - campaigns components: parameters: limit: name: limit in: query required: false schema: $ref: '#/components/schemas/ParameterLimit' description: >- Limits the number of objects to be returned. The limit can range between 1 and 100 items. If no limit is set, it returns 10 items. page: name: page in: query required: false schema: $ref: '#/components/schemas/ParameterPage' description: Which page of results to return. The lowest value is `1`. campaign_type: name: campaign_type in: query required: false schema: $ref: '#/components/schemas/ParameterCampaignType' description: This attribute allows filtering by campaign type. schemas: ParameterExpandListCampaigns: type: string enum: - category - access_settings_assignments ParameterCampaignStatusListCampaigns: type: string description: |- Status of the campaign. Allowed values: `DONE`, `IN_PROGRESS`, `DRAFT`, `FAILED` `MODIFYING` enum: - DONE - IN_PROGRESS - FAILED - DRAFT - MODIFYING ParameterIsReferralCodeListCampaigns: type: boolean description: Lists campaigns that have or do not have referral codes. ParameterOrderListCampaigns: type: string enum: - created_at - '-created_at' - updated_at - '-updated_at' ParameterFiltersListCampaigns: type: object properties: campaigns: type: object description: Name of the campaign. properties: conditions: $ref: '#/components/schemas/FilterConditionsString' campaigns_id: type: object description: Unique identifier of the campaign. It is assigned by Voucherify. properties: conditions: $ref: '#/components/schemas/FilterConditionsString' campaign_status: type: object description: |- Status of the campaign. Allowed values: `DONE`, `IN_PROGRESS`, `DRAFT`, `FAILED` `MODIFYING` properties: conditions: type: object description: >- Data conditions used to narrow down the data records to be returned in the result. properties: $in: type: array description: >- Array of resource values that should be included in the results (multiple values). items: type: string enum: - DONE - IN_PROGRESS - FAILED - DRAFT - MODIFYING $not_in: type: array description: >- Array of resource values that should be included in the results (multiple values). items: type: string enum: - DONE - IN_PROGRESS - FAILED - DRAFT - MODIFYING $is: type: string description: Value is exactly this value (single value). enum: - DONE - IN_PROGRESS - FAILED - DRAFT - MODIFYING $is_not: type: string description: Results omit this value (single value). enum: - DONE - IN_PROGRESS - FAILED - DRAFT - MODIFYING $has_value: type: string description: >- Value is NOT null. The value for this parameter is an empty string. $is_unknown: type: string description: >- Value is null. The value for this parameter is an empty string. $starts_with: type: string description: Value starts with the specified string. $ends_with: type: string description: Value ends with the specified string. status: type: object description: >- Filters campaigns by their code generation status. Pass the filter as an empty object, for example `filters[status][conditions][$active]=` properties: conditions: type: object description: >- Data conditions used to narrow down the data records to be returned in the result. properties: $active: type: object description: >- Campaigns finished generation codes. This also returns campaigns regardless of their `expiration_date` and `start_date`. additionalProperties: false $failed: type: object description: Campaigs failed to generated codes. additionalProperties: false $in_progress: type: object description: Campaigns are generating codes or they are updating. additionalProperties: false $expired: type: object description: >- Campaigns generated codes, but their `expiration_date` is in the past. additionalProperties: false before_start: type: object description: >- Campaigns generated codes, but their `start_date` is in the future. additionalProperties: false active: type: object description: >- Filters campaigns by their `active` state. Pass the filter as an empty object, for example `filters[active][conditions][$enabled]=`. properties: $enabled: type: object description: Campaigns are enabled. additionalProperties: false $disabled: type: object description: Campaigns are disabled. additionalProperties: false $expired: type: object description: Campaign `expiration_date` is in the past. additionalProperties: false $active: type: object description: >- Campaigns are active, `start_date` is `null` or in the past, and `expiration_date` is `null` or in the future. additionalProperties: false is_referral_code: type: object description: Determines if the campaign is or is not a referral campaign. properties: conditions: type: object properties: $is: type: string description: Value is exactly this value (single value). enum: - 'TRUE' - 'FALSE' $is_not: type: string description: Results omit this value (single value). enum: - 'TRUE' - 'FALSE' validity_timeframe: description: Filter by validity timeframe type: object properties: conditions: $ref: '#/components/schemas/FilterConditionsDateTime' voucher_type: type: object description: |- Type of the voucher. Allowed values: `DISCOUNT_VOUCHER`, `GIFT_VOUCHER`, `LOYALTY_CARD`. properties: conditions: properties: $in: type: array description: >- Array of resource values that should be included in the results (multiple values). items: type: string enum: - GIFT_VOUCHER - DISCOUNT_VOUCHER - LOYALTY_CARD $not_in: type: array description: >- Array of resource values that should be included in the results (multiple values). items: type: string enum: - GIFT_VOUCHER - DISCOUNT_VOUCHER - LOYALTY_CARD $is: type: string description: Value is exactly this value (single value). enum: - GIFT_VOUCHER - DISCOUNT_VOUCHER - LOYALTY_CARD $is_not: type: string description: Results omit this value (single value). enum: - GIFT_VOUCHER - DISCOUNT_VOUCHER - LOYALTY_CARD $has_value: type: string description: >- Value is NOT null. The value for this parameter is an empty string. $is_unknown: type: string description: >- Value is null. The value for this parameter is an empty string. $starts_with: type: string description: Value starts with the specified string. $ends_with: type: string description: Value ends with the specified string. categories: type: object description: Filter by categories names properties: conditions: $ref: '#/components/schemas/FilterConditionsString' category_ids: type: object description: Filter by categories IDs properties: conditions: $ref: '#/components/schemas/FilterConditionsString' type: type: object description: >- Type of the campaign. Allowed values: `AUTO_UPDATE`, `BULK`, `STANDALONE`, `STATIC`. `BULK` is a virtual type that returns campaigns with the `AUTO_UPDATE` or `STATIC` type. properties: conditions: properties: $in: type: array description: >- Array of resource values that should be included in the results (multiple values). items: type: string enum: - AUTO_UPDATE - BULK - STANDALONE - STATIC $not_in: type: array description: >- Array of resource values that should be included in the results (multiple values). items: type: string enum: - AUTO_UPDATE - BULK - STANDALONE - STATIC created_date: description: >- Timestamp representing the date and time when the campaign was created. The value is shown in the ISO 8601 format. type: object properties: conditions: $ref: '#/components/schemas/FilterConditionsDateTime' updated_at: type: object description: >- Timestamp representing the date and time when the campaign was last updated. The value is shown in the ISO 8601 format. properties: conditions: $ref: '#/components/schemas/FilterConditionsDateTime' start_date: type: object description: >- Timestamp representing the date and time when the campaign starts to be active. Campaign is *inactive before* this date. The value is shown in the ISO 8601 format. properties: conditions: $ref: '#/components/schemas/FilterConditionsDateTime' expiration_date: description: >- Timestamp representing the date and time when the campaign expired. The value is shown in the ISO 8601 format. type: object properties: conditions: $ref: '#/components/schemas/FilterConditionsDateTime' validity_day_of_week: description: >- Filters days of week when the campaign is active. The value is an integer array corresponding to the particular days of the week in which the campaign is valid. - `0` Sunday - `1` Monday - `2` Tuesday - `3` Wednesday - `4` Thursday - `5` Friday - `6` Saturday If the campaign is valid throughout all week days, it is always returned. type: object properties: conditions: type: object description: >- Data conditions used to narrow down the data records to be returned in the result. properties: $is: type: array description: >- Array of resource values that should be included in the results (multiple values). items: type: integer minimum: 0 maximum: 6 enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 junction: $ref: '#/components/schemas/Junction' ParameterCampaignsAccessSetttings: type: object properties: filter: type: object properties: areas_ids: type: array description: >- Add area IDs to list all campaigns that are assigned to those areas. items: type: string example: ar_0ab12cde3456789fgh area_all_stores_ids: type: array description: >- Add area IDs to list all campaigns that are assigned to all stores in those areas. items: type: string example: ar_0ab12cde3456789fgh area_stores_ids: type: array description: >- Add store IDs to list all campaigns that are assigned to those stores. The response returns also those campaigns that are assigned to those stores with the assignment to all stores. items: type: string example: ars_0ab12cde3456789fgh CampaignsListResponseBody: type: object description: Schema model for **GET** `v1/campaigns`. title: Campaigns List Response Body properties: object: type: string description: >- The type of the object represented by JSON. This object stores information about campaigns in a dictionary. default: list data_ref: type: string description: >- Identifies the name of the attribute that contains the array of campaign objects. default: campaigns campaigns: type: array description: Contains array of campaign objects. items: $ref: '#/components/schemas/CampaignBase' total: type: integer description: Total number of campaigns. ParameterLimit: type: integer minimum: 1 maximum: 100 ParameterPage: type: integer minimum: 1 maximum: 100 ParameterCampaignType: type: string enum: - PROMOTION - GIFT_VOUCHERS - REFERRAL_PROGRAM - DISCOUNT_COUPONS - LOYALTY_PROGRAM FilterConditionsString: title: Filter by conditions type: object description: >- Data filters used to narrow down the data records to be returned in the result. properties: $in: type: array description: >- Array of resource values that should be included in the results (multiple values). items: type: string $not_in: type: array description: >- Array of resource values that should be included in the results (multiple values). items: type: string $is: type: string description: Value is exactly this value (single value). $is_not: type: string description: Results omit this value (single value). $has_value: type: string description: Value is NOT null. The value for this parameter is an empty string. $is_unknown: type: string description: Value is null. The value for this parameter is an empty string. $starts_with: type: string description: Value starts with the specified string. $ends_with: type: string description: Value ends with the specified string. $contains: type: string description: Value includes the specified string. $not_contain: type: string description: Value does NOT include the specified string. FilterConditionsDateTime: title: Filter by conditions type: object description: >- Data filters used to narrow down the data records to be returned in the result. properties: $after: type: string description: >- Value is after this date. The value for this parameter is shown in the ISO 8601 format. format: date-time example: '2024-01-01T00:00:00.000Z' $before: type: string description: >- Value is before this date. The value for this parameter is shown in the ISO 8601 format. format: date-time example: '2024-01-01T00:00:00.000Z' $has_value: type: string description: Value is NOT null. The value for this parameter is an empty string. $is_unknown: type: string description: Value is null. The value for this parameter is an empty string. $more_than: type: integer description: >- Value is more days ago before the current date and time, e.g. more than `10` days ago. $less_than: type: integer description: >- Value is less days before the current date and time, e.g. less than `10` days ago. Junction: title: Junction description: >- Logical Operator Between Filters. Filter by conditions set on the `junction` parameter indicating how the `conditions` should be accounted for in the query. An `AND` is an all-inclusive logical operator, meaning the `AND` operator displays a record if **ALL** the conditions separated by AND are TRUE, while an `OR` operator displays a record if **ANY** of the conditions separated by OR is TRUE. enum: - and - or 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 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 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' 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 description: Type of reward. enum: - LOYALTY_CARD - GIFT_VOUCHER 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 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 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. 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 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 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`. ````