--- title: "RetrieveLoyaltyProgram" method: GET path: "/v2/loyalty/programs/{program_id}" tags: ["Loyalty"] --- # RetrieveLoyaltyProgram `GET /v2/loyalty/programs/{program_id}` Retrieves the loyalty program in a seller's account, specified by the program ID or the keyword `main`. Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see [Loyalty Program Overview](https://developer.squareup.com/docs/loyalty/overview). ## Path parameters - `program_id` string, required ## Response `200` Success - RetrieveLoyaltyProgramResponse — A response that contains the loyalty program. - `errors` Error[] — Any errors that occurred during the request. - `category` string, required — The high-level category for the error. - `code` string, required — The specific code of the error. - `detail` string — A human-readable description of the error for debugging purposes. - `field` string — The name of the field provided in the original request (if any) that the error pertains to. - `program` LoyaltyProgram — Represents a Square loyalty program. Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see [Loyalty Program Overview](https://developer.squareup.com/docs/loyalty/overview). - `accrual_rules` LoyaltyProgramAccrualRule[], required — Defines how buyers can earn loyalty points. - `accrual_type` string, required — The type of the accrual rule that defines how buyers can earn points. - `catalog_object_id` string — When the accrual rule is item-based or category-based, this field specifies the ID of the [catalog object](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject) that buyers can purchase to earn points. If `accrual_type` is `ITEM_VARIATION`, the object is an item variation. If `accrual_type` is `CATEGORY`, the object is a category. - `excluded_category_ids` string[] — When the accrual rule is spend-based (`accrual_type` is `SPEND`), this field lists the IDs of any `CATEGORY` catalog objects that are excluded from points accrual. You can use the [BatchRetrieveCatalogObjects](https://developer.squareup.com/reference/square_2021-08-18/catalog-api/batch-retrieve-catalog-objects) endpoint to retrieve information about the excluded categories. - `excluded_item_variation_ids` string[] — When the accrual rule is spend-based (`accrual_type` is `SPEND`), this field lists the IDs of any `ITEM_VARIATION` catalog objects that are excluded from points accrual. You can use the [BatchRetrieveCatalogObjects](https://developer.squareup.com/reference/square_2021-08-18/catalog-api/batch-retrieve-catalog-objects) endpoint to retrieve information about the excluded item variations. - `points` integer — The number of points that buyers earn based on the `accrual_type`. - `spend_amount_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `visit_minimum_amount_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `created_at` string, required — The timestamp when the program was created, in RFC 3339 format. - `expiration_policy` LoyaltyProgramExpirationPolicy — Describes when the loyalty program expires. - `expiration_duration` string, required — The number of months before points expire, in `P[n]M` RFC 3339 duration format. For example, a value of `P12M` represents a duration of 12 months. Points are valid through the last day of the month in which they are scheduled to expire. For example, with a `P12M` duration, points earned on July 6, 2020 expire on August 1, 2021. - `id` string, required — The Square-assigned ID of the loyalty program. Updates to the loyalty program do not modify the identifier. - `location_ids` string[], required — The [locations](https://developer.squareup.com/reference/square_2021-08-18/objects/Location) at which the program is active. - `reward_tiers` LoyaltyProgramRewardTier[], required — The list of rewards for buyers, sorted by ascending points. - `created_at` string, required — The timestamp when the reward tier was created, in RFC 3339 format. - `definition` LoyaltyProgramRewardDefinition, required — Provides details about the reward tier discount. DEPRECATED at version 2020-12-16. Discount details are now defined using a catalog pricing rule and other catalog objects. For more information, see [Get discount details for the reward](https://developer.squareup.com/docs/loyalty-api/overview#get-discount-details). - `catalog_object_ids` string[] — The list of catalog objects to which this reward can be applied. They are either all item-variation ids or category ids, depending on the `type` field. DEPRECATED at version 2020-12-16. You can find this information in the `product_set_data.product_ids_any` field of the `PRODUCT_SET` catalog object referenced by the pricing rule. - `discount_type` string, required — The type of discount the reward tier offers. DEPRECATED at version 2020-12-16. You can find this information in the `discount_data.discount_type` field of the `DISCOUNT` catalog object referenced by the pricing rule. - `fixed_discount_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `max_discount_money` Money — Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. - `amount` integer — The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case. - `currency` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values. - `percentage_discount` string — The fixed percentage of the discount. Present if `discount_type` is `FIXED_PERCENTAGE`. For example, a 7.25% off discount will be represented as "7.25". DEPRECATED at version 2020-12-16. You can find this information in the `discount_data.percentage` field of the `DISCOUNT` catalog object referenced by the pricing rule. - `scope` string, required — Indicates the scope of the reward tier. DEPRECATED at version 2020-12-16. You can find this information in the `discount_target_scope` field of the `PRICING_RULE` catalog object and the `product_set_data` field of the `PRODUCT_SET` catalog object referenced by the pricing rule. For `ORDER` scopes, the target scope is `WHOLE_PURCHASE` and `all_products` is true. For `ITEM_VARIATION` and `CATEGORY` scopes, the target scope is `LINE_ITEM` and `product_ids_any` is a list of catalog object IDs of the given type. - `id` string, required — The Square-assigned ID of the reward tier. - `name` string, required — The name of the reward tier. - `points` integer, required — The points exchanged for the reward tier. - `pricing_rule_reference` CatalogObjectReference — A reference to a Catalog object at a specific version. In general this is used as an entry point into a graph of catalog objects, where the objects exist at a specific version. - `catalog_version` integer — The version of the object. - `object_id` string — The ID of the referenced object. - `status` string, required — Whether the program is currently active. - `terminology` LoyaltyProgramTerminology, required — Represents the naming used for loyalty points. - `one` string, required — A singular unit for a point (for example, 1 point is called 1 star). - `other` string, required — A plural unit for point (for example, 10 points is called 10 stars). - `updated_at` string, required — The timestamp when the reward was last updated, in RFC 3339 format. --- [API](https://skmtc.net/square/apis/squareup.md) · [All operations](https://skmtc.net/square/apis/squareup/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/squareup/revisions/8d95e3639487/schema)