{"templateId":"markdown","versions":[{"version":"2.0","label":"v2.0","link":"/percents-api/offers","default":true,"active":true,"folderId":"27d36c3a"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Offers"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"offers","__idx":0},"children":["Offers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your wallet needs offers it can show before registration and offers selected for a known customer afterward. Use general discovery, targeted discovery and eligibility lookups to present the rate and terms and show whether the cardholder group can use an offer. A cardholder group holds rewards for one or more cardholders."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"general-offers","__idx":1},"children":["General offers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/listIssuerOffers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v2/offers"]}]}," without a cardholder group. Results contain live and scheduled baseline offers broadly available to your customers. Customer-specific offers with a higher rate are returned only with the appropriate customer context. Purchase requirements and activation still apply."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rewardProductType"]}," to select the product your experience presents. Pages include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageSize"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalCount"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hasNextPage"]},". Defaults are page 1 and 25 items, with a maximum page size of 100. Continue until ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hasNextPage"]}," is false."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"targeted-offers","__idx":2},"children":["Targeted offers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For segmented offers, purchase history can determine which merchant offer a cardholder group qualifies for. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/merchant-segments"},"children":["Offer Segments and Purchase History"]}," for backfilling and how matching works when history is missing."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use general offers for the initial display before cardholder accounts exist. Once registration or lazy provisioning gives you a cardholder group, call ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/listAvailableOffers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v2/chg/{chgId}/offers"]}]}," with its returned ID (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chgId"]},"). Targeted discovery can include offers omitted from general discovery, with the same or better terms for that customer than the general baseline."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Display the returned offer IDs, rates and terms."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Offers that still need activation remain visible. Check ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/user-activity#when-offers-need-to-be-activated-again"},"children":["when offers need to be activated again"]}," to distinguish activation scope from the total redemption limit."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Offers that have reached their redemption limit also remain visible. Explain why they cannot be used."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To narrow discovery to a merchant, call ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/listMerchantOffers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v2/chg/{chgId}/merchant/{merchantId}/offers"]}]},". For a complete view of that merchant's live offers and the group's eligibility and activation, use the eligibility lookup below."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"offer-definition-by-id","__idx":3},"children":["Offer definition by ID"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/getOfferDetails"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v2/offer/{offerId}"]}]}," to read an offer's current terms, rate, limits and dates. You do not need a merchant or cardholder group in the path. Your issuer credential still determines access. An unknown or inaccessible offer returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET <env-host>/api/v2/offer/mpo_66666666-6666-4666-8666-666666666666\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This read returns the offer's current definition. Percents may preserve activation across related offers. Use the offer’s current activation status from the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#merchant-eligibility"},"children":["eligibility response"]}," to determine whether the cardholder needs to activate again."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"merchant-eligibility","__idx":4},"children":["Merchant eligibility"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/getEligibilityForMerchant"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v2/chg/{chgId}/merchant/{merchantId}/eligibility"]}]}," with the required query parameter ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope=cashback"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope=branded"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response includes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Live offers selected for the cardholder group at that merchant and scope. Scheduled and ended offers are excluded."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["segmentSource"]},", explaining how customer context was determined."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chgQualified"]},", showing the offer's current qualification."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["activated"]},", showing activation independently of other qualification restrictions."]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"activated"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["activated"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The current activation covers the next redemption."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Activation is required."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The offer needs no activation."]}]}]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"chgQualified"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chgQualified"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What to do"},"children":["What to do"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["yes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The group passes offer-level checks. A qualifying purchase is still required."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notActivated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Record the required activation before expecting an earned reward."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redemptionLimitReached"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Explain that the group's redemption limit has been reached."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Percents selects the customer's offers, checks redemption limits and then activation. A failed evaluation returns an error."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Branded responses also return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canSpend"]},", which says whether the group can spend its existing balance. This is separate from earning a new reward. Read the offer's limit fields and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["termsAndConditionsText"]}," for the purchase requirements."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/merchant-segments"},"children":["Offer Segments and Purchase History guide"]}," explains how history supports offer selection. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/standards/units-and-ids"},"children":["Money, dates and limits"]}," explains rate representations and purchase restrictions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"group-wide-eligibility","__idx":5},"children":["Group-wide eligibility"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To check offers across all merchants for a cardholder group, call ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/getOfferEligibilityForGroup"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v2/chg/{chgId}/offer/eligibility"]}]}," with the required ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope=cashback"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope=branded"]},". Choose one product per request. Use this to load offers from several merchants with one request."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET <env-host>/api/v2/chg/{chgId}/offer/eligibility?scope=cashback\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response is a list of the merchant results described above. It covers all merchants with live offers available to your issuer for the selected product."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each result includes the merchant ID and the group's eligibility and activation status."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An empty list means no live offers are visible."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Both eligibility lookups require an existing cardholder group. An unknown or inaccessible group returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]},"."]}]}]},"headings":[{"value":"Offers","id":"offers","depth":1},{"value":"General offers","id":"general-offers","depth":2},{"value":"Targeted offers","id":"targeted-offers","depth":2},{"value":"Offer definition by ID","id":"offer-definition-by-id","depth":2},{"value":"Merchant eligibility","id":"merchant-eligibility","depth":2},{"value":"Group-wide eligibility","id":"group-wide-eligibility","depth":2}],"frontmatter":{"title":"Offers","description":"Browse general offers, read an offer by ID and check eligibility for a cardholder group.","seo":{"title":"Offers"}},"lastModified":"2026-11-10T20:25:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/percents-api/offers","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}