Gift Cards (aka Vouchers)

Note: This is a pilot.

Warning: This document is a Work In Progress document. Information may change often.

This guide outlines the requirements, data modeling recommendations, and best practices for implementing gift cards (also known as vouchers) in your offers feed. These recommendations supplement the standard Actions Center documentation and address gift-card-specific integration aspects.

Offer Mode and Categorization

When submitting gift card inventory, ensure the following core attributes are configured correctly:

• Offer Mode: offer_modes must always be set as a singleton array containing "OFFER_MODE_GIFT_CARD_PURCHASE":

  "offer_modes": ["OFFER_MODE_GIFT_CARD_PURCHASE"]
  

• Stored-Value Vouchers vs. Walk-In Instant Discounts:

  • gift_card_info is strictly reserved for pre-purchased stored-value vouchers and gift cards (OFFER_MODE_GIFT_CARD_PURCHASE).
  • If a customer pays directly at the physical store counter on the spot for an immediate discount without purchasing a voucher code to claim or redeem later, model the offer as a standard walk-in discount (OFFER_MODE_WALK_IN) and omit the gift_card_info message entirely.

• Denomination Modeling: The gift card denomination should represent what the voucher is worth (what it can be redeemed for), not what the user pays (the user pays the discounted price).

• Consolidating Multiple Denominations: Multiple vouchers sharing the exact same discount percentage and terms, but differing in face value, must be grouped into a single offer entry. Since denomination_type operates as a oneof, partners must choose between setting fixed_denominations or a custom_range:

  • Fixed Denominations: Use when discrete, preset gift card amounts are offered (e.g., ₹500, ₹1,000, and ₹2,000, all with a flat 10% discount). Ensure that any fixed denominations that are sold out or unavailable on the landing page are explicitly excluded from feed submissions.
  • Custom Range: Use strictly when users can freely enter any arbitrary face value within defined bounds on the purchasing page (e.g., any value between ₹100 and ₹5,000 with a 5% discount). If the destination landing page offers discrete, preset amounts, model the inventory strictly under fixed_denominations. Furthermore, if both fixed denominations and custom denominations are available for an offer, partners should set the flexible custom range.

Handling Multi-Location Chains

For gift vouchers that apply across large retail or dining chains where the terms are identical across multiple points of interest (POIs), do not provide a separate Offer object for every single store location. Instead, use an aggregated feeding approach by providing a single Offer object containing a list of all participating store entity IDs (entity_ids).

Note: An exception applies if the destination landing page URL (offer_url) is unique for each store outlet. In such cases, partners must submit one separate Offer object per outlet.

Portal Branding (brand_id)

Some vouchers are offered through specific bank or loyalty portals (e.g., bank loyalty programs or partner platforms) rather than the main merchant site. To ensure accurate branding for these portals, partners must populate the brand_id field on top-level Offer objects.

While omitting brand_id defaults to the primary brand of the account (and brand_id is not required when using the account's default brand), explicitly populating brand_id accurately associates inventory with its corresponding branded portal, ensuring that the correct partner-specific logos and names are displayed to users. Further instructions on configuring brands can be found in Brands Configuration.

Validity Structure (ValidityScope)

Gift cards have a unique validity structure distinguishing the timeframe to purchase the deal from the duration to redeem the card. Partners must always use the relevant ValidityScope enum values:

• VALIDITY_SCOPE_CLAIM: Defines the timeframe when the gift card offering is available to be purchased on the partner platform. This entry must always be present. When submitting feeds, populate the claim validity period starting from the exact feed submission date. Furthermore, never leave claim periods open-ended if the landing page explicitly advertises a campaign end date; match valid_through_time to the advertised expiration date.
• VALIDITY_SCOPE_REDEEM: Defines the post-purchase redemption duration (the timeframe users have to redeem the voucher at the store after purchasing it, which can be specified as a duration or a timeframe).

Action Type Mapping

Partners often categorize vouchers using constructs like "redeemable online/offline", "online/outlet", or "in-store". In feed submissions, this must be mapped to the ActionType enum to accurately define how the product is consumed:

• Dining / Food Vertical: Map "Dine-in" gift cards to ACTION_TYPE_DINING. Map "Delivery" gift cards to ACTION_TYPE_FOOD_DELIVERY. Map "Takeout" gift cards to ACTION_TYPE_FOOD_TAKEOUT.
• Shopping Retail Vertical: Map "In-store" gift cards to ACTION_TYPE_SHOPPING_IN_STORE. (Note: Online-only retail vouchers are unsupported).
• Single Channel Mapping: Each offer_id can belong to strictly one ActionType. If an inventory item supports multiple fulfillment channels (e.g., both food delivery and takeout), create distinct Offer objects with unique IDs for each mode.

Tiered Discounts and Add-On Offers

• Tiered Discounts Across Payment Methods: If different discount percentages are offered based on the specific payment instrument used (e.g., a higher discount for an e-wallet versus Credit Cards), these must be modeled as separate Offer objects. Partners should provide exhaustive promotional coverage across all supported payment instruments (e.g., e-wallets, Credit Cards, Debit Cards, Net Banking) to ensure a reliable savings experience. If an offer applies universally to all payment methods accepted on the platform, the payment instrument field shouldn't be set.
• Add-On Offers Construct: To represent stacked benefits, such as bank-specific reward points or extra cashback applicable to a gift card purchase, submit them as entirely separate Add-On offers by using the appropriate OfferCategory enum - OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER. Describe the reward inside OfferDetails.other_offer_details_text (e.g., "Up to 5X Reward Points"), and link it to the base gift card deal by populating OfferRestrictions.combinable_offer_ids with the base gift card's offer_id.

Terms and Special Conditions

Partners should rely on terms.terms_and_conditions to provide the full legalese Terms & Conditions of the gift card or voucher. Consolidate all user-facing instructions and usage guidelines into this field.

If critical restrictions require dedicated UI prominence (such as single-use balance expiration, non-refundability, or transaction combining caps like "Maximum 2 vouchers can be combined per bill"), highlight them in offer_restrictions.special_conditions.

Important: Any critical condition populated in special_conditions must also be exhaustively included within the main terms.terms_and_conditions string.

Offer Title Recommendations

Offer title length should remain strictly under 40 characters. Strip merchant brand names from offer_display_text, as offers are surfaced directly on the merchant's dedicated place sheet. We recommend the following title formats:

Use case	Recommended Title
Flat discount on vouchers	X% off on Gift Cards
Variable discount based on payment method	X% off on Gift Cards using {e-wallet}
Variable discounts on different denominations	X% off on Gift Cards (Send different discounts as separate offers)
B2B2C Gift cards	X% off on Gift Cards (Branding is shown through thumbnail using brand_id)
Add-on offers	Flat/Up to 5X reward points/ <Platform> coins

Landing Page requirement

Every advertised offer_url must return HTTP 200 OK directly without intermediary redirects and resolve to an active destination page substantiating the offer.

The feed must not include sold out or unavailable denominations. Maintain strict inventory synchronization between feed denomination fields and live purchasing options on the destination landing page.

The destination landing page should clearly mention that the offer applies specifically to gift cards or vouchers.

For example, if a partner landing page only displays generic payment calls to action like "Pay bill" without explicitly stating upfront that completing the transaction issues a stored-value gift card voucher, users redirected from Google expecting to buy a gift card may experience confusion or abandonment. Even if a voucher notice appears at a subsequent checkout step, upfront clarity on the initial landing page is required.

Offers with coupon codes

Certain offers require the entry of a coupon code by the user, such as "Apply code SAVE20 to get 20% off on the total bill". It is important to note that Google doesn't display coupon codes from the coupon definition. Partners may include this information within the OfferDetails.offer_display_text to be displayed to users. Coupon-based offers generally fall into two categories:

• Offers where the coupon is automatically presented at checkout to any user arriving from Google. These are permitted.
• Offers that require the user to enter the coupon code at checkout but don't provide instructions on how to apply the coupon code on the offer URL landing page, or don't automatically apply the coupon when following the offer URL, are not permitted.

Example Gift Card Offer JSON

{
  "data": [
    {
      "offer_id": "example-dining-gift-card-10off",
      "entity_ids": [
        "dining-1",
        "dining-2"
      ],
      "offer_modes": [
        "OFFER_MODE_GIFT_CARD_PURCHASE"
      ],
      "action_type": "ACTION_TYPE_DINING",
      "offer_source": "OFFER_SOURCE_AGGREGATOR",
      "offer_category": "OFFER_CATEGORY_BASE_OFFER",
      "offer_details": {
        "offer_display_text": "10% off on Gift Cards",
        "discount_percent": 10.0,
        "gift_card_info": {
          "fixed_denominations": {
            "amounts": [
              {
                "units": 500,
                "currency_code": "INR"
              },
              {
                "units": 1000,
                "currency_code": "INR"
              },
              {
                "units": 2000,
                "currency_code": "INR"
              }
            ]
          }
        }
      },
      "offer_restrictions": {
        "combinable_with_other_offers": false,
        "special_conditions": [
          "Single-use balance expiration applies",
          "Maximum 2 gift card vouchers can be combined per bill",
          "No cash refund will be provided against this voucher"
        ]
      },
      "terms": {
        "restricted_to_certain_users": false,
        "terms_and_conditions": "1. Redeemable exclusively at participating dining outlets.\n2. Single-use balance expiration applies.\n3. Maximum 2 gift card vouchers can be combined per bill.\n4. No cash refund will be provided against this voucher."
      },
      "validity_periods": [
        {
          "valid_period": {
            "valid_from_time": {
              "seconds": "1774934350"
            },
            "valid_through_time": {
              "seconds": "1806470350"
            }
          },
          "validity_scope": "VALIDITY_SCOPE_CLAIM"
        },
        {
          "validity_duration_in_days": 365,
          "validity_scope": "VALIDITY_SCOPE_REDEEM"
        }
      ],
      "offer_url": "https://www.example-portal.com/dining-gift-cards/buy"
    }
  ]
}