REST Resource: accounts.programs.loyaltyPrograms

Resource: LoyaltyProgram

A loyalty program for a merchant.

JSON representation 
{
  "name": string,
  "programName": string,
  "tiers": [
    {
      object (LoyaltyProgramTier)
    }
  ],
  "programDescriptions": [
    string
  ],
  "signupUrl": string,
  "reviewResult": {
    object (ReviewResult)
  },
  "regionCodes": [
    string
  ],
  "advancedSettings": {
    object (AdvancedSettings)
  }
}
Fields
name

string

Identifier. The resource name of the LoyaltyProgram. Format: accounts/{account}/programs/{program}/loyaltyPrograms/{loyaltyProgram} For example, accounts/123456/programs/loyalty/loyaltyPrograms/my_loyalty_program.
programName

string

Required. The name of the LoyaltyProgram that will be displayed to users. The programName can have a max length of 25 characters.
tiers[]

object (LoyaltyProgramTier)

Required. Tiers of the LoyaltyProgram. A loyalty program must have at least 1 tier and can have up to 7 tiers.
programDescriptions[]

string

Required. A list of free-form string descriptions for the LoyaltyProgram. A program_description should not exceed a length of 39 characters. Only the first program description will be displayed to users.
signupUrl

string

Required. Signup URL for the LoyaltyProgram. When the Signup URL from the tier level is missing, this program-level one will be used as a default. This must be a valid URL pattern to be acceptable.
reviewResult

object (ReviewResult)

Output only. Review result of the LoyaltyProgram. After submitting a new or updated LoyaltyProgram, the review process will begin and the review status will be UNDER_REVIEW. The LoyaltyProgram will be updated to APPROVED or REJECTED once the review is complete.
regionCodes[]

string

Required. The countries where you want to showcase LoyaltyProgram. The countries are represented as CLDR region codes (e.g., "US", "CH").
advancedSettings

object (AdvancedSettings)

Optional. The settings controlling the behavior of the LoyaltyProgram. This includes whether targeted and untargeted loyalty prices are displayed.

LoyaltyProgramTier

A tier of a LoyaltyProgram.

JSON representation 
{
  "tierName": string,
  "tierLabel": string,
  "tierBenefits": [
    {
      object (TierBenefit)
    }
  ],
  "requirements": {
    object (LoyaltyProgramTierRequirements)
  },
  "signupUrl": string
}
Fields
tierName

string

Required. The name displayed to users for the tier. The tierName can have a max length of 25 characters.
tierLabel

string

Required. The label of the tier. The label may not contain any spaces and can have a max length of 25 characters.
tierBenefits[]

object (TierBenefit)

Required. A list of benefits for the LoyaltyProgramTier. Each benefit is either structured or a free-form string. All tier benefits will be displayed to users as a list.

Structured benefits will be used to generate a description of the benefit. For example, a PointsEarningBenefit with a PointsEarningBenefitAnnotation of 5 points per $1 spent will be displayed to users as "5 points earned per $1 spent". Only one of each type of StructuredBenefit is allowed. That is, only one PointsEarningBenefit, one ShippingBenefit, and one PointsRedemptionBenefit is allowed per tier.

Free-form strings will be displayed to users as-is. A maximum of 10 free-form string benefits are allowed per tier.

These constraints are enforced during API requests.
requirements

object (LoyaltyProgramTierRequirements)

Required. Requirements to join/advance to the given membership tier.
signupUrl

string

Optional. Signup URL for the tier. If this optional field is not provided, the program-level signup URL will be used as a default.

TierBenefit

A benefit for a LoyaltyProgramTier. Each tier must have at least 1 benefit.

JSON representation 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "structuredBenefit": {
    object (StructuredBenefit)
  },
  "otherBenefit": string
  // End of mutually exclusive fields.
}
Fields
The structured or free-form string benefit. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
structuredBenefit

object (StructuredBenefit)

A specific benefit which is described using metadata rather than a free-form string. For example, a shipping benefit or a points benefit.
otherBenefit

string

A benefit that is described using a free-form string. Free-form benefits have a maximum length of 39 characters. For example: "Free gift on your birthday".
End of mutually exclusive fields.

StructuredBenefit

Benefit of a LoyaltyProgram tier in a structured form.

JSON representation 
{
  "customId": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "pointsEarningBenefit": {
    object (PointsEarningBenefit)
  },
  "shippingBenefit": {
    object (ShippingBenefit)
  },
  "pointsRedemptionBenefit": {
    object (PointsRedemptionBenefit)
  }
  // End of mutually exclusive fields.
}
Fields
customId

string (int64 format)

Optional. Merchant-provided identifier for the benefit rule.
The specific benefit. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
pointsEarningBenefit

object (PointsEarningBenefit)

Points earning benefit.
shippingBenefit

object (ShippingBenefit)

Shipping benefit.
pointsRedemptionBenefit

object (PointsRedemptionBenefit)

Points redemption benefit.
End of mutually exclusive fields.

PointsEarningBenefit

Benefit that gives points to the user. If minimumMoneySpent is set, then the benefit will only be applied to orders larger than the minimumMoneySpent. The rate at which points are earned is determined by the PointsEarningBenefitAnnotation.

JSON representation 
{
  "minimumMoneySpent": {
    object (Money)
  },
  "pointsEarningBenefitAnnotation": {
    object (PointsEarningBenefitAnnotation)
  },
  "taxRate": number,
  "disableGlobalApplicability": boolean
}
Fields
minimumMoneySpent

object (Money)

Optional. The amount of money required to spend in order to earn points. For example, a value of $25.00 means point earnings are only applied to orders over $25.00.
pointsEarningBenefitAnnotation

object (PointsEarningBenefitAnnotation)

Required. Annotation for the point benefit.
taxRate

number

Optional. Optionally, define the tax rate for accurate points calculation.
disableGlobalApplicability

boolean

Optional. By default, the PointsEarningBenefit will be applied to all products. When this field is true, the PointsEarningBenefit will only be applied to eligible products.

Money

Represents an amount of money with its currency type.

JSON representation 
{
  "currencyCode": string,
  "units": string,
  "nanos": integer
}
Fields
currencyCode

string

The three-letter currency code defined in ISO 4217.
units

string (int64 format)

The whole units of the amount. For example if currencyCode is "USD", then 1 unit is one US dollar.
nanos

integer

Number of nano (10^-9) units of the amount. The value must be between -999,999,999 and +999,999,999 inclusive. If units is positive, nanos must be positive or zero. If units is zero, nanos can be positive, zero, or negative. If units is negative, nanos must be negative or zero. For example $-1.75 is represented as units=-1 and nanos=-750,000,000.

PointsEarningBenefitAnnotation

Structured metadata for point benefit annotation. For example, $pointsEarned points per $amountSpent spent.

JSON representation 
{
  "pointsEarned": number,
  "amountSpent": {
    object (Money)
  }
}
Fields
pointsEarned

number

Required. The points earned for each $amountSpent spent. If the calculated amount of points is not an integer, the points will be rounded down to the nearest integer.
amountSpent

object (Money)

Required. The amount spent to earn $pointsEarned points.

ShippingBenefit

Benefit provided to the user which relates to shipping.

JSON representation 
{
  "hasShippingBenefit": boolean
}
Fields
hasShippingBenefit

boolean

Required. Indicate whether or not that this tier has a shipping benefit.

PointsRedemptionBenefit

Redemption rules for points redemption.

JSON representation 
{
  "minimumOrderValue": {
    object (Money)
  },
  "maxDiscountValue": {
    object (Money)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "fixedRewardRule": {
    object (FixedRewardRule)
  }
  // End of mutually exclusive fields.
}
Fields
minimumOrderValue

object (Money)

Optional. Spending thresholds for the points redemption rule.
maxDiscountValue

object (Money)

Optional. Maximum discount value (e.g., 30% off with 10K points, max $50 discount).
The strategy for how points can be redeemed. This field is required when setting a PointsRedemptionBenefit. This constraint is enforced during API requests. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
fixedRewardRule

object (FixedRewardRule)

Strategy where a fixed amount of points can redeem a fixed reward. For example, 500 points can redeem $5.00 off.
End of mutually exclusive fields.

FixedRewardRule

Fixed reward rule for points redemption, where a certain number of points can be redeemed for a fixed reward (e.g., $5.00 off with 500 points).

JSON representation 
{
  "requiredPoints": string,
  "reward": {
    object (RedemptionReward)
  }
}
Fields
requiredPoints

string (int64 format)

Optional. The number of points required to redeem the reward.
reward

object (RedemptionReward)

Optional. The reward to be redeemed when the required points are met. Can be a fixed currency amount (e.g., $5.00 off) or a percentage discount (e.g., 15 for 15% off).

RedemptionReward

Reward that can be redeemed with points when the conditions are met.

JSON representation 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "amountOff": {
    object (Money)
  },
  "percentOff": integer
  // End of mutually exclusive fields.
}
Fields
The type of reward which can be redeemed with points. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
amountOff

object (Money)

Fixed currency amount (e.g., $5.00 off)
percentOff

integer

Percentage discount. For example, 15 for 15% off.
End of mutually exclusive fields.

LoyaltyProgramTierRequirements

The requirements to join a particular tier of a LoyaltyProgram.

JSON representation 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "freeToJoin": boolean,
  "brandedCard": {
    object (BrandedCard)
  },
  "membershipFee": {
    object (MembershipCost)
  },
  "purchaseSpending": {
    object (MembershipCost)
  },
  "loyaltyPointAccumulation": {
    object (LoyaltyPoints)
  },
  "orderPlacement": {
    object (PlacedOrders)
  }
  // End of mutually exclusive fields.
}
Fields
The tier requirement. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
freeToJoin

boolean

Whether the tier is free to join or not.
brandedCard

object (BrandedCard)

Requirement to have a branded card to join the tier and use it during checkout to receive benefits.
membershipFee

object (MembershipCost)

Requirement to pay a membership fee in order to qualify as a member of the tier.
purchaseSpending

object (MembershipCost)

Requirement to spend with the merchant in order to qualify as a member of the tier.
loyaltyPointAccumulation

object (LoyaltyPoints)

Requirement to have a certain number of points to qualify as a member of the tier.
orderPlacement

object (PlacedOrders)

Requirement to place a certain number of orders to qualify as a member of the tier.
End of mutually exclusive fields.

BrandedCard

Requirement to have a branded credit card.

JSON representation 
{
  "cardName": string
}
Fields
cardName

string

Required. Specifies the name of the card (e.g. "Target RedCard") for display purposes.

MembershipCost

Membership cost required to join a particular tier.

JSON representation 
{
  "amount": {
    object (Money)
  },
  "frequency": enum (CalendarPeriod)
}
Fields
amount

object (Money)

Required. The amount required to pay or spend for the given frequency to qualify as a member of the tier.
frequency

enum (CalendarPeriod)

Optional. The frequency of the payment or spending requirement. Example: per year, per month. If unset, a one-time payment is assumed.

CalendarPeriod

A CalendarPeriod represents the abstract concept of a time period that has a canonical start. Grammatically, "the start of the current CalendarPeriod." All calendar times begin at midnight UTC.

Enums
CALENDAR_PERIOD_UNSPECIFIED Undefined period, raises an error.
DAY A day.
WEEK A week. Weeks begin on Monday, following ISO 8601.
FORTNIGHT A fortnight. The first calendar fortnight of the year begins at the start of week 1 according to ISO 8601.
MONTH A month.
QUARTER A quarter. Quarters start on dates 1-Jan, 1-Apr, 1-Jul, and 1-Oct of each year.
HALF A half-year. Half-years start on dates 1-Jan and 1-Jul.
YEAR A year.

LoyaltyPoints

Points required to reach or maintain a particular tier.

JSON representation 
{
  "pointAmount": string,
  "frequency": enum (CalendarPeriod)
}
Fields
pointAmount

string (int64 format)

Required. Number of points required.
frequency

enum (CalendarPeriod)

Optional. The earning frequency of the points, for example per year, per month. The field does not need to be set if the points are total accumulated or lifetime points.

PlacedOrders

Requirement to place a certain number of orders.

JSON representation 
{
  "orderCount": string,
  "frequency": enum (CalendarPeriod)
}
Fields
orderCount

string (int64 format)

Required. Number of orders required.
frequency

enum (CalendarPeriod)

Optional. The cadence/frequency for placing these orders, if applicable. For example, orders placed per year. The field does not need to be set if the orders are lifetime orders.

ReviewResult

Indicates the review result of the LoyaltyProgram.

JSON representation 
{
  "reviewStatus": enum (State),
  "rejectReason": enum (RejectReason)
}
Fields
reviewStatus

enum (State)

Output only. Indicates the review status of the LoyaltyProgram.
rejectReason

enum (RejectReason)

Output only. Provides a RejectReason to indicate the reason the LoyaltyProgram was rejected.

State

The current state of the LoyaltyProgram review.

Enums
STATE_UNSPECIFIED Default value. This value is unused.
UNDER_REVIEW Under review.
APPROVED Approved.
REJECTED Rejected.

RejectReason

The reason the LoyaltyProgram was rejected.

Enums
REJECT_REASON_UNSPECIFIED Default value. This value is unused.
BROKEN_PROGRAM_LEVEL_URL The URL that should show the LoyaltyProgram tiers is broken or incorrect.
BROKEN_PROGRAM_URL The signup URL submitted is broken or incorrect.
NUMBER_OF_PROGRAM_LEVEL_DOES_NOT_MATCH_WEBSITE The number of tiers submitted does not match what is on the website.
PROGRAM_DESCRIPTION_DOES_NOT_MATCH_WEBSITE The description submitted does not match the description on the website.
PROGRAM_DESCRIPTION_DOES_NOT_MEET_STANDARDS The program description does not meet Google's editorial standards.
PROGRAM_LABEL_DOES_NOT_MEET_STANDARDS The program label does not meet Google's editorial standards.
PROGRAM_LEVEL_BENEFIT_DOES_NOT_MATCH_WEBSITE The benefits submitted do not match what is on the website.
PROGRAM_LEVEL_BENEFIT_DOES_NOT_MEET_STANDARDS The tier benefit does not meet Google's editorial standards.
PROGRAM_LEVEL_LABEL_DOES_NOT_MEET_STANDARDS The tier label does not meet Google's editorial standards.
PROGRAM_LEVEL_NAME_DOES_NOT_MATCH_WEBSITE The tier name submitted does not match the tier name on the website.
PROGRAM_LEVEL_NAME_DOES_NOT_MEET_STANDARDS The tier name does not meet Google's editorial standards.
PROGRAM_NAME_DOES_NOT_MATCH_WEBSITE The program name submitted does not match the name on the website.
PROGRAM_NAME_DOES_NOT_MEET_STANDARDS The program name does not meet Google's editorial standards.
MEMBER_PRICE_BENEFIT_MISMATCH The LoyaltyProgram was not accepted. The loyalty pricing submitted in the product data does not match what is shown on the website. Review and update the product data to ensure accurate prices are submitted. Once updated, contact the support team for re-review.
MEMBER_SHIPPING_BENEFIT_MISMATCH The LoyaltyProgram was not accepted. The shipping policy for loyalty tiers does not match the info on the website. Review and update the shipping policy to ensure accurate cost and speed are submitted. Once updated, contact the support team for re-review.
RESTRICTED_PARTICIPATION The loyalty program does not allow every individual to join.
UNSUPPORTED_COUNTRY The loyalty program is not in the supported country.
UNSTRUCTURED_PROGRAM It's a newsletter or text signup and not a structured loyalty program.
PROMOTIONAL_OFFER_NOT_PROGRAM It's a promotional offer rather than a loyalty program.

AdvancedSettings

Settings that control the behavior of the loyalty program, such as where it is shown.

JSON representation 
{
  "hideDisplayFromNonMembers": boolean,
  "hideDisplayFromMembers": boolean
}
Fields
hideDisplayFromNonMembers

boolean

Optional. Controls whether your loyalty program benefits are hidden from users who are not matched to any member lists you have shared with Google. If this optional value is not provided, your loyalty benefits will be displayed to these users. This setting, currently, only works for paid listings.
hideDisplayFromMembers

boolean

Optional. Controls whether your loyalty program benefits are hidden from users who are matched to the member lists you have shared with Google. If this optional value is not provided, your loyalty benefits are displayed to these users. This setting, currently, only works for paid listings.

Methods

create

 Creates a new LoyaltyProgram.

delete

 Deletes the LoyaltyProgram matching the requested name.

get

 Retrieves a LoyaltyProgram matching the requested name.

list

 Retrieves the LoyaltyPrograms for the account.

patch

 Updates the LoyaltyProgram matching the requested name.