643 matches
60 actions
Square
60 actions
Finance/Square
Returns a list of loyalty programs in the seller's account. 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 .
Replaced with when used with the keyword main.
{
"type": "object",
"description": "A response that contains all loyalty programs.",
"properties": {
"errors": {
"type": "array",
"description": "Any errors that occurred during the request.",
"items": {
"type": "object",
"description": "Represents an error encountered during a request to the Connect API.\n\nSee [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) for more information.",
"required": [
"category",
"code"
],
"properties": {
"category": {
"type": "string",
"description": "The high-level category for the error."
},
"code": {
"type": "string",
"description": "The specific code of the error."
},
"detail": {
"type": "string",
"description": "A human-readable description of the error for debugging purposes."
},
"field": {
"type": "string",
"description": "The name of the field provided in the original request (if any) that\nthe error pertains to."
}
}
}
},
"programs": {
"type": "array",
"description": "A list of `LoyaltyProgram` for the merchant.",
"items": {
"type": "object",
"description": "Represents a Square loyalty program. Loyalty programs define how buyers can earn points and redeem points for rewards. \nSquare sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. \nFor more information, see [Loyalty Program Overview](https://developer.squareup.com/docs/loyalty/overview).",
"required": [
"id",
"status",
"reward_tiers",
"terminology",
"location_ids",
"created_at",
"updated_at",
"accrual_rules"
],
"properties": {
"accrual_rules": {
"type": "array",
"description": "Defines how buyers can earn loyalty points.",
"items": {
"type": "object",
"description": "Defines an accrual rule, which is how buyers can earn points.",
"required": [
"accrual_type"
],
"properties": {
"accrual_type": {
"type": "string",
"description": "The type of the accrual rule that defines how buyers can earn points."
},
"catalog_object_id": {
"type": "string",
"description": "When the accrual rule is item-based or category-based, this field specifies the ID \nof the [catalog object](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject) that buyers can purchase to earn points. \nIf `accrual_type` is `ITEM_VARIATION`, the object is an item variation. \nIf `accrual_type` is `CATEGORY`, the object is a category."
},
"excluded_category_ids": {
"type": "array",
"description": "When the accrual rule is spend-based (`accrual_type` is `SPEND`), this field \nlists the IDs of any `CATEGORY` catalog objects that are excluded from points accrual. \n\nYou can use the [BatchRetrieveCatalogObjects](https://developer.squareup.com/reference/square_2021-08-18/catalog-api/batch-retrieve-catalog-objects) \nendpoint to retrieve information about the excluded categories.",
"items": {
"type": "string"
}
},
"excluded_item_variation_ids": {
"type": "array",
"description": "When the accrual rule is spend-based (`accrual_type` is `SPEND`), this field \nlists the IDs of any `ITEM_VARIATION` catalog objects that are excluded from points accrual. \n\nYou can use the [BatchRetrieveCatalogObjects](https://developer.squareup.com/reference/square_2021-08-18/catalog-api/batch-retrieve-catalog-objects) \nendpoint to retrieve information about the excluded item variations.",
"items": {
"type": "string"
}
},
"points": {
"type": "integer",
"description": "The number of points that \nbuyers earn based on the `accrual_type`."
},
"spend_amount_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case."
},
"currency": {
"type": "string",
"description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
}
}
},
"visit_minimum_amount_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case."
},
"currency": {
"type": "string",
"description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
}
}
}
}
}
},
"created_at": {
"type": "string",
"description": "The timestamp when the program was created, in RFC 3339 format."
},
"expiration_policy": {
"type": "object",
"description": "Describes when the loyalty program expires.",
"required": [
"expiration_duration"
],
"properties": {
"expiration_duration": {
"type": "string",
"description": "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. \nPoints 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": {
"type": "string",
"description": "The Square-assigned ID of the loyalty program. Updates to \nthe loyalty program do not modify the identifier."
},
"location_ids": {
"type": "array",
"description": "The [locations](https://developer.squareup.com/reference/square_2021-08-18/objects/Location) at which the program is active.",
"items": {
"type": "string"
}
},
"reward_tiers": {
"type": "array",
"description": "The list of rewards for buyers, sorted by ascending points.",
"items": {
"type": "object",
"description": "Represents a reward tier in a loyalty program. A reward tier defines how buyers can redeem points for a reward, such as the number of points required and the value and scope of the discount. A loyalty program can offer multiple reward tiers.",
"required": [
"id",
"points",
"name",
"definition",
"created_at"
],
"properties": {
"created_at": {
"type": "string",
"description": "The timestamp when the reward tier was created, in RFC 3339 format."
},
"definition": {
"type": "object",
"description": "Provides details about the reward tier discount. DEPRECATED at version 2020-12-16. Discount details\nare now defined using a catalog pricing rule and other catalog objects. For more information, see\n[Get discount details for the reward](https://developer.squareup.com/docs/loyalty-api/overview#get-discount-details).",
"required": [
"scope",
"discount_type"
],
"properties": {
"catalog_object_ids": {
"type": "array",
"description": "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.\nDEPRECATED at version 2020-12-16. You can find this information in the `product_set_data.product_ids_any` field\nof the `PRODUCT_SET` catalog object referenced by the pricing rule.",
"items": {
"type": "string"
}
},
"discount_type": {
"type": "string",
"description": "The type of discount the reward tier offers. DEPRECATED at version 2020-12-16. You can find this information\nin the `discount_data.discount_type` field of the `DISCOUNT` catalog object referenced by the pricing rule."
},
"fixed_discount_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case."
},
"currency": {
"type": "string",
"description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
}
}
},
"max_discount_money": {
"type": "object",
"description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.",
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case."
},
"currency": {
"type": "string",
"description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
}
}
},
"percentage_discount": {
"type": "string",
"description": "The fixed percentage of the discount. Present if `discount_type` is `FIXED_PERCENTAGE`.\nFor example, a 7.25% off discount will be represented as \"7.25\". DEPRECATED at version 2020-12-16. You can find this\ninformation in the `discount_data.percentage` field of the `DISCOUNT` catalog object referenced by the pricing rule."
},
"scope": {
"type": "string",
"description": "Indicates the scope of the reward tier. DEPRECATED at version 2020-12-16. You can find this information in the\n`discount_target_scope` field of the `PRICING_RULE` catalog object and the `product_set_data` field of the `PRODUCT_SET`\ncatalog object referenced by the pricing rule. For `ORDER` scopes, the target scope is `WHOLE_PURCHASE` and `all_products`\nis true. For `ITEM_VARIATION` and `CATEGORY` scopes, the target scope is `LINE_ITEM` and `product_ids_any` is a list of\ncatalog object IDs of the given type."
}
}
},
"id": {
"type": "string",
"description": "The Square-assigned ID of the reward tier."
},
"name": {
"type": "string",
"description": "The name of the reward tier."
},
"points": {
"type": "integer",
"description": "The points exchanged for the reward tier."
},
"pricing_rule_reference": {
"type": "object",
"description": "A reference to a Catalog object at a specific version. In general this is\nused as an entry point into a graph of catalog objects, where the objects exist\nat a specific version.",
"properties": {
"catalog_version": {
"type": "integer",
"format": "int64",
"description": "The version of the object."
},
"object_id": {
"type": "string",
"description": "The ID of the referenced object."
}
}
}
}
}
},
"status": {
"type": "string",
"description": "Whether the program is currently active."
},
"terminology": {
"type": "object",
"description": "Represents the naming used for loyalty points.",
"required": [
"one",
"other"
],
"properties": {
"one": {
"type": "string",
"description": "A singular unit for a point (for example, 1 point is called 1 star)."
},
"other": {
"type": "string",
"description": "A plural unit for point (for example, 10 points is called 10 stars)."
}
}
},
"updated_at": {
"type": "string",
"description": "The timestamp when the reward was last updated, in RFC 3339 format."
}
}
}
}
}
}