---
title: "List Loyalty Campaigns"
method: GET
path: "/v1/loyalties"
tags: ["Loyalties"]
---

# List Loyalty Campaigns

`GET /v1/loyalties`

Returns a list of your loyalty campaigns.

## Query parameters

- `limit` integer
- `page` integer
- `expand` 'category' | 'access_settings_assignments'
- `order` 'created_at' | '-created_at' | 'updated_at' | '-updated_at'

## Response `200`

Returns a dictionary with loyalty program objects. The loyalty campaigns are returned sorted by creation date, with the most recent campaigns appearing first.

- LoyaltiesListCampaignsResponseBody — Response body schema for **Get** `/loyalties`.
  - `object` string — The type of the object represented by JSON. This object stores information about loyalty campaigns in a dictionary.
  - `data_ref` 'campaigns' — Identifies the name of the attribute that contains the array of loyalty campaign objects.
  - `campaigns` LoyaltyCampaign[] — Contains an array of loyalty campaign objects.
    - `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.
  - `total` integer — Total number of loyalty campaign objects.

---

[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/revisions/4982266e0494/schema)