GotCashback

Returns the cashback portals GotCashback compares, optionally for one country, each with its payout terms. Use it to list the portals available in a country ('which cashback portals are there in Canada?') or to compare portals side by side — which pays fastest, has the lowest minimum payout, offers PayPal, or gives the biggest sign-up bonus. It does not return store rates: for 'which portal has the best cashback for [store]' call get_cashback_rates_by_store_name instead; for one named portal use get_portals_by_name. Each portal includes its payout terms for that country: 'sign_up_bonus' (amount and the url that grants it, null when none), 'minimum_payout' with 'minimum_payout_currency' (smallest balance paid out, null when not published, 0 means no minimum), 'payment_frequency' (how often it pays, e.g. 'On demand', 'Weekly', 'Monthly'), and 'payment_methods' (payout options, e.g. 'PayPal', 'Direct deposit', 'Check', 'Gift card'). Use these to answer questions about a portal's sign-up bonus, payout threshold, payment schedule and payment options. When mentioning a sign-up bonus, show its 'url' as a clickable link — the bonus is only credited when the user signs up through it.

{
  "type": "object",
  "properties": {
    "country_code": {
      "description": "Optional. Lowercase ISO 3166-1 alpha-2 country code that limits results to one country, e.g. 'us' (United States), 'ca' (Canada), 'gb' (United Kingdom — use 'gb', not 'uk'), 'de' (Germany), 'au' (Australia), 'fr' (France). Pass it when the user names a country ('in Canada', 'UK cashback'); omit it to search all supported countries.",
      "type": [
        "string",
        "null"
      ],
      "default": null
    }
  }
}

{
  "type": "object",
  "properties": {
    "portals": {
      "type": "array",
      "items": {
        "description": "A cashback portal in one country, with the payout terms it offers there.",
        "type": "object",
        "properties": {
          "id": {
            "description": "GotCashback's numeric identifier of this portal-in-country entry. Pass it as portal_id to get_portal_by_id.",
            "type": "integer"
          },
          "name": {
            "description": "Portal name, e.g. 'Rakuten', 'TopCashback'.",
            "type": "string"
          },
          "country_code": {
            "description": "Lowercase ISO 3166-1 alpha-2 code of the country these terms apply to. The same portal appears once per country.",
            "type": "string"
          },
          "url": {
            "description": "Link to join or open the portal (GotCashback's referral link when the portal has one). Show it as a clickable link.",
            "type": "string"
          },
          "icon_url": {
            "description": "Portal logo image URL.",
            "type": "string"
          },
          "sign_up_bonus": {
            "description": "Sign-up bonus the portal currently offers new members in this country. Null when no active bonus is published.",
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "amount": {
                "description": "Bonus as the portal advertises it, e.g. '$10' or '£5 after your first purchase'.",
                "type": "string"
              },
              "url": {
                "description": "Link that grants the bonus. Always show it as a clickable link; the bonus is only credited when the user signs up through it.",
                "type": "string"
              }
            }
          },
          "minimum_payout": {
            "description": "Smallest balance the portal pays out in this country, in minimum_payout_currency. Null when not published; 0 means there is no minimum.",
            "type": [
              "number",
              "null"
            ]
          },
          "minimum_payout_currency": {
            "description": "ISO 4217 currency code of minimum_payout, e.g. 'USD', 'GBP'. Null when minimum_payout is null.",
            "type": [
              "string",
              "null"
            ]
          },
          "payment_frequency": {
            "description": "How often the portal pays out in this country, e.g. 'On demand', 'Weekly', 'Monthly', 'Quarterly'. Null when not published.",
            "type": [
              "string",
              "null"
            ]
          },
          "payment_methods": {
            "description": "Payout methods offered in this country, e.g. 'PayPal', 'Direct deposit', 'Check', 'Gift card'. Null when none are published.",
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "description": "Cashback portals with their payout terms, one entry per portal and country."
}

Returns the current online and in-store cashback rates from every cashback portal for one store identified by its numeric store_id, so the user can compare every portal and see the best. Use it only when a store_id is already known from an earlier result (a store, deals, favorites or alerts response). When the user gives a store name instead, call get_cashback_rates_by_store_name directly — do not look the id up first. Returns an error when the id does not exist. Rates reflect GotCashback's current data, refreshed several times a day. Present every returned portal's rate to the user (a table with a link column, not only the best one) and always show each rate's 'url' as a clickable link — cashback is only credited when the user clicks through it.

{
  "type": "object",
  "properties": {
    "store_id": {
      "description": "GotCashback's numeric store_id, taken from an earlier result (a store, cashback rate, gift card, deals, favorites or alerts response). If you only have a store name, use the by-name tool instead.",
      "type": "integer"
    }
  },
  "required": [
    "store_id"
  ]
}

{
  "type": "object",
  "properties": {
    "store": {
      "description": "A store (retailer) in one country, with its current cashback rates when returned by a cashback tool.",
      "type": "object",
      "properties": {
        "store_id": {
          "description": "GotCashback's numeric store identifier. Pass it as store_id to the *_by_store_id, favorite and alert tools.",
          "type": "integer"
        },
        "name": {
          "description": "Store (retailer) name as shown on GotCashback.",
          "type": "string"
        },
        "country_code": {
          "description": "Lowercase ISO 3166-1 alpha-2 code of the country this store entry belongs to (e.g. 'us', 'ca', 'gb'). The same retailer appears once per country with country-specific rates.",
          "type": "string"
        },
        "url": {
          "description": "GotCashback store page listing all of this store's offers. Show it as a clickable link.",
          "type": "string"
        },
        "domain": {
          "description": "The store's website domain, e.g. 'walmart.com'. Null when unknown.",
          "type": [
            "string",
            "null"
          ]
        },
        "has_gift_cards": {
          "description": "True when discounted gift cards are currently available for this store (present in get_stores_by_country results only; null/absent otherwise).",
          "type": [
            "boolean",
            "null"
          ]
        },
        "gift_cards_url": {
          "description": "GotCashback page listing the store's discounted gift cards. Present when has_gift_cards is true; show it as a clickable link.",
          "type": [
            "string",
            "null"
          ]
        },
        "cashback_rates": {
          "description": "Current cashback offers for this store, one per portal and location (online / in-store). Empty when no portal currently offers cashback here; null/absent for tools that return store identity only.",
          "type": [
            "array",
            "null"
          ],
          "items": {
            "description": "One cashback offer for the store from one cashback portal.",
            "type": "object",
            "properties": {
              "portal": {
                "description": "Name of the cashback portal offering this rate, e.g. 'Rakuten', 'TopCashback'.",
                "type": "string"
              },
              "type": {
                "description": "How the rate is expressed: 'percent' (rate is a percentage of the purchase amount) or 'fixedamount' (rate is a fixed amount in the store's local currency).",
                "type": "string"
              },
              "rate": {
                "description": "The cashback rate value. A percentage when type is 'percent' (5 means 5%), otherwise a fixed amount of cashback per purchase.",
                "type": "number"
              },
              "upto": {
                "description": "True when the rate is a maximum ('up to X%') that varies by product category or terms; false when it applies to all qualifying purchases. Rank 'up to' rates below a guaranteed rate of the same value.",
                "type": "boolean"
              },
              "location": {
                "description": "Where the cashback applies: 'online' (shop on the store's website through the link) or 'in-store' (linked-card cashback at physical locations).",
                "type": "string"
              },
              "url": {
                "description": "Tracked GotCashback click-through link that activates this cashback offer at the portal. Always show it to the user as a clickable link; cashback is only credited when they shop through it.",
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "description": "One store with its current cashback rates."
}

Returns the countries GotCashback covers, each with the lowercase ISO 3166-1 alpha-2 'code' to pass as country_code to the other tools (the United Kingdom is 'gb'). Use it only to confirm whether a country is supported or which code to use; it is not needed before store, cashback or gift card lookups — those tools accept country_code directly and search all countries when it is omitted.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "countries": {
      "type": "array",
      "items": {
        "description": "A country covered by GotCashback's cashback comparison.",
        "type": "object",
        "properties": {
          "country_id": {
            "description": "GotCashback's numeric country identifier (informational; tools take country_code, not this id).",
            "type": "integer"
          },
          "name": {
            "description": "Country name in English, e.g. 'United Kingdom'.",
            "type": "string"
          },
          "localized_name": {
            "description": "Country name in its own language, e.g. 'Deutschland'.",
            "type": "string"
          },
          "code": {
            "description": "Lowercase ISO 3166-1 alpha-2 code to pass as country_code to other tools, e.g. 'us', 'ca', 'gb' (United Kingdom), 'de'.",
            "type": "string"
          }
        }
      }
    }
  },
  "description": "Countries covered by GotCashback."
}

Returns the discounted gift cards currently on sale for one store identified by its numeric store_id, from multiple sellers, so the discounts can be compared. Use it only when a store_id is already known from an earlier result. When the user gives a store name instead, call get_gift_cards_by_store_name directly — do not look the id up first. Returns an empty list when no discounted cards are available and an error when the id does not exist. Present every returned seller's listing to the user (a table with a link column, not only the best discount) and always show each gift card's 'url' as a clickable link — that tracked link is where the user buys the card at the discounted price.

{
  "type": "object",
  "properties": {
    "store_id": {
      "description": "GotCashback's numeric store_id, taken from an earlier result (a store, cashback rate, gift card, deals, favorites or alerts response). If you only have a store name, use the by-name tool instead.",
      "type": "integer"
    }
  },
  "required": [
    "store_id"
  ]
}

{
  "type": "object",
  "properties": {
    "gift_cards": {
      "description": "Gift card listings from all sellers. Empty when none are available right now.",
      "type": "array",
      "items": {
        "description": "One discounted gift card listing for the store from one gift card seller.",
        "type": "object",
        "properties": {
          "gift_card_id": {
            "description": "GotCashback's numeric identifier of this listing.",
            "type": "integer"
          },
          "seller": {
            "description": "Name of the gift card seller / marketplace offering the card, e.g. 'CardCash', 'Raise'.",
            "type": "string"
          },
          "seller_icon_url": {
            "description": "Seller logo image URL. Null when none.",
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "description": "Card format, e.g. 'Digital' (e-gift code delivered online) or 'Physical' (plastic card shipped).",
            "type": "string"
          },
          "value_type": {
            "description": "1 = a single fixed face value (see value and price); 2 = a range of face values (see value_from/value_to and price_from/price_to).",
            "type": "integer"
          },
          "value": {
            "description": "Face value of the card in the store's currency, when value_type is 1. Null for ranges.",
            "type": [
              "number",
              "null"
            ]
          },
          "value_from": {
            "description": "Smallest face value available, when value_type is 2. Null for fixed-value cards.",
            "type": [
              "number",
              "null"
            ]
          },
          "value_to": {
            "description": "Largest face value available, when value_type is 2. Null for fixed-value cards.",
            "type": [
              "number",
              "null"
            ]
          },
          "price": {
            "description": "What the buyer pays for the card, when value_type is 1. The saving is value minus price.",
            "type": [
              "number",
              "null"
            ]
          },
          "price_from": {
            "description": "Price of the smallest face value, when value_type is 2.",
            "type": [
              "number",
              "null"
            ]
          },
          "price_to": {
            "description": "Price of the largest face value, when value_type is 2.",
            "type": [
              "number",
              "null"
            ]
          },
          "discount_percent": {
            "description": "Discount off face value in percent (e.g. 8.5 means the card costs 8.5% less than it is worth). Null when it cannot be computed. Compare listings by this field to find the best gift card discount.",
            "type": [
              "number",
              "null"
            ]
          },
          "count": {
            "description": "Number of cards in stock at the seller, when published. Null when unknown.",
            "type": [
              "integer",
              "null"
            ]
          },
          "url": {
            "description": "Tracked GotCashback purchase link that leads to this card at the seller. Always show it to the user as a clickable link; the discount is only obtained by buying through it.",
            "type": "string"
          }
        }
      }
    }
  },
  "description": "Discounted gift cards currently on sale for one store."
}

Searches cashback portals by name (e.g. 'Rakuten', 'TopCashback', 'Honey') and returns each match with its payout terms, one entry per country the portal operates in. Use it when the user asks about a named portal: its sign-up bonus, minimum payout, how often it pays, or which payout methods it offers. For a store's cashback rate at that portal, call get_cashback_rates_by_store_name and read the 'portal' field of each rate instead. Each portal includes its payout terms for that country: 'sign_up_bonus' (amount and the url that grants it, null when none), 'minimum_payout' with 'minimum_payout_currency' (smallest balance paid out, null when not published, 0 means no minimum), 'payment_frequency' (how often it pays, e.g. 'On demand', 'Weekly', 'Monthly'), and 'payment_methods' (payout options, e.g. 'PayPal', 'Direct deposit', 'Check', 'Gift card'). Use these to answer questions about a portal's sign-up bonus, payout threshold, payment schedule and payment options. When mentioning a sign-up bonus, show its 'url' as a clickable link — the bonus is only credited when the user signs up through it.

{
  "type": "object",
  "properties": {
    "portal_name": {
      "description": "The cashback portal name as users say it, e.g. 'Rakuten', 'TopCashback', 'Honey', 'Quidco'. Matched case-insensitively at word boundaries (exact, prefix, then word), best match first; a partial-word match is only returned when nothing better exists.",
      "type": "string"
    },
    "country_code": {
      "description": "Optional. Lowercase ISO 3166-1 alpha-2 country code that limits results to one country, e.g. 'us' (United States), 'ca' (Canada), 'gb' (United Kingdom — use 'gb', not 'uk'), 'de' (Germany), 'au' (Australia), 'fr' (France). Pass it when the user names a country ('in Canada', 'UK cashback'); omit it to search all supported countries.",
      "type": [
        "string",
        "null"
      ],
      "default": null
    }
  },
  "required": [
    "portal_name"
  ]
}

{
  "type": "object",
  "properties": {
    "portals": {
      "type": "array",
      "items": {
        "description": "A cashback portal in one country, with the payout terms it offers there.",
        "type": "object",
        "properties": {
          "id": {
            "description": "GotCashback's numeric identifier of this portal-in-country entry. Pass it as portal_id to get_portal_by_id.",
            "type": "integer"
          },
          "name": {
            "description": "Portal name, e.g. 'Rakuten', 'TopCashback'.",
            "type": "string"
          },
          "country_code": {
            "description": "Lowercase ISO 3166-1 alpha-2 code of the country these terms apply to. The same portal appears once per country.",
            "type": "string"
          },
          "url": {
            "description": "Link to join or open the portal (GotCashback's referral link when the portal has one). Show it as a clickable link.",
            "type": "string"
          },
          "icon_url": {
            "description": "Portal logo image URL.",
            "type": "string"
          },
          "sign_up_bonus": {
            "description": "Sign-up bonus the portal currently offers new members in this country. Null when no active bonus is published.",
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "amount": {
                "description": "Bonus as the portal advertises it, e.g. '$10' or '£5 after your first purchase'.",
                "type": "string"
              },
              "url": {
                "description": "Link that grants the bonus. Always show it as a clickable link; the bonus is only credited when the user signs up through it.",
                "type": "string"
              }
            }
          },
          "minimum_payout": {
            "description": "Smallest balance the portal pays out in this country, in minimum_payout_currency. Null when not published; 0 means there is no minimum.",
            "type": [
              "number",
              "null"
            ]
          },
          "minimum_payout_currency": {
            "description": "ISO 4217 currency code of minimum_payout, e.g. 'USD', 'GBP'. Null when minimum_payout is null.",
            "type": [
              "string",
              "null"
            ]
          },
          "payment_frequency": {
            "description": "How often the portal pays out in this country, e.g. 'On demand', 'Weekly', 'Monthly', 'Quarterly'. Null when not published.",
            "type": [
              "string",
              "null"
            ]
          },
          "payment_methods": {
            "description": "Payout methods offered in this country, e.g. 'PayPal', 'Direct deposit', 'Check', 'Gift card'. Null when none are published.",
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "description": "Cashback portals with their payout terms, one entry per portal and country."
}

Lists every store that currently has cashback offers in one country — identity, store page url and whether discounted gift cards exist ('has_gift_cards', 'gift_cards_url'), but no rates. The list can run to hundreds of stores. Use it when the user wants to browse or count what is available in a country ('which stores offer cashback in Canada?', 'what stores have gift card deals in the UK?'). Do not use it to find a particular store or its rates: get_cashback_rates_by_store_name and get_gift_cards_by_store_name accept a store name plus an optional country_code directly. Use get_countries to see the supported country codes. When presenting stores, include each store's 'url' as a clickable link (and 'gift_cards_url' when present).

{
  "type": "object",
  "properties": {
    "country_code": {
      "description": "Lowercase ISO 3166-1 alpha-2 country code, e.g. 'us' (United States), 'ca' (Canada), 'gb' (United Kingdom — use 'gb', not 'uk'), 'de' (Germany), 'au' (Australia). Call get_countries to list every supported code.",
      "type": "string"
    }
  },
  "required": [
    "country_code"
  ]
}

{
  "type": "object",
  "properties": {
    "stores": {
      "description": "Matching stores (one entry per country). Empty when nothing matched.",
      "type": "array",
      "items": {
        "description": "A store (retailer) in one country, with its current cashback rates when returned by a cashback tool.",
        "type": "object",
        "properties": {
          "store_id": {
            "description": "GotCashback's numeric store identifier. Pass it as store_id to the *_by_store_id, favorite and alert tools.",
            "type": "integer"
          },
          "name": {
            "description": "Store (retailer) name as shown on GotCashback.",
            "type": "string"
          },
          "country_code": {
            "description": "Lowercase ISO 3166-1 alpha-2 code of the country this store entry belongs to (e.g. 'us', 'ca', 'gb'). The same retailer appears once per country with country-specific rates.",
            "type": "string"
          },
          "url": {
            "description": "GotCashback store page listing all of this store's offers. Show it as a clickable link.",
            "type": "string"
          },
          "domain": {
            "description": "The store's website domain, e.g. 'walmart.com'. Null when unknown.",
            "type": [
              "string",
              "null"
            ]
          },
          "has_gift_cards": {
            "description": "True when discounted gift cards are currently available for this store (present in get_stores_by_country results only; null/absent otherwise).",
            "type": [
              "boolean",
              "null"
            ]
          },
          "gift_cards_url": {
            "description": "GotCashback page listing the store's discounted gift cards. Present when has_gift_cards is true; show it as a clickable link.",
            "type": [
              "string",
              "null"
            ]
          },
          "cashback_rates": {
            "description": "Current cashback offers for this store, one per portal and location (online / in-store). Empty when no portal currently offers cashback here; null/absent for tools that return store identity only.",
            "type": [
              "array",
              "null"
            ],
            "items": {
              "description": "One cashback offer for the store from one cashback portal.",
              "type": "object",
              "properties": {
                "portal": {
                  "description": "Name of the cashback portal offering this rate, e.g. 'Rakuten', 'TopCashback'.",
                  "type": "string"
                },
                "type": {
                  "description": "How the rate is expressed: 'percent' (rate is a percentage of the purchase amount) or 'fixedamount' (rate is a fixed amount in the store's local currency).",
                  "type": "string"
                },
                "rate": {
                  "description": "The cashback rate value. A percentage when type is 'percent' (5 means 5%), otherwise a fixed amount of cashback per purchase.",
                  "type": "number"
                },
                "upto": {
                  "description": "True when the rate is a maximum ('up to X%') that varies by product category or terms; false when it applies to all qualifying purchases. Rank 'up to' rates below a guaranteed rate of the same value.",
                  "type": "boolean"
                },
                "location": {
                  "description": "Where the cashback applies: 'online' (shop on the store's website through the link) or 'in-store' (linked-card cashback at physical locations).",
                  "type": "string"
                },
                "url": {
                  "description": "Tracked GotCashback click-through link that activates this cashback offer at the portal. Always show it to the user as a clickable link; cashback is only credited when they shop through it.",
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "description": "Stores matching the query, best match first, each with its current cashback rates."
}

Returns the signed-in user's cashback and gift card alerts. Use it for 'what alerts do I have?' or before changing an alert. Each alert carries store_id, alert_type ('cashback' or 'gift_card'), threshold_percent and the last notification; pass store_id and alert_type straight to set_store_alert or remove_store_alert — the values are identical. Requires OAuth sign-in with a GotCashback account and the 'alerts' scope; anonymous callers are prompted to authorize.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "alerts": {
      "description": "The user's alerts, newest first. Empty when they have none.",
      "type": "array",
      "items": {
        "description": "An alert the user has set on a store: it notifies them by email when the store's cashback rate or gift card discount reaches the threshold.",
        "type": "object",
        "properties": {
          "alert_id": {
            "description": "GotCashback's numeric identifier for this alert subscription. Informational — remove_store_alert takes store_id and alert_type, not this id.",
            "type": "integer"
          },
          "store_id": {
            "description": "GotCashback's numeric store identifier. Pass it as store_id to set_store_alert, remove_store_alert and the *_by_store_id tools.",
            "type": "integer"
          },
          "store_name": {
            "description": "Store (retailer) name as shown on GotCashback.",
            "type": "string"
          },
          "country_code": {
            "description": "Lowercase ISO 3166-1 alpha-2 code of the country this alert's store entry belongs to (e.g. 'us', 'ca', 'gb').",
            "type": [
              "string",
              "null"
            ]
          },
          "country_name": {
            "description": "Country name in English, e.g. 'United States'.",
            "type": [
              "string",
              "null"
            ]
          },
          "alert_type": {
            "description": "What the alert watches: 'cashback' (the store's best cashback rate) or 'gift_card' (the store's best gift card discount). Pass this value unchanged to set_store_alert or remove_store_alert.",
            "type": "string",
            "enum": [
              "gift_card",
              "cashback"
            ]
          },
          "threshold_percent": {
            "description": "The alert fires when the rate or discount reaches this percent or higher (10 means 10%).",
            "type": "number"
          },
          "active": {
            "description": "True while the alert is armed. Inactive alerts no longer notify and do not count against the 10-alert limit.",
            "type": "boolean"
          },
          "created_on": {
            "description": "UTC timestamp when the user created the alert.",
            "type": "string",
            "format": "date-time"
          },
          "last_notified_on": {
            "description": "UTC timestamp of the last notification sent for this alert. Null/absent when it has never fired.",
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "last_notified_value": {
            "description": "The rate or discount percent that triggered the last notification. Null/absent when the alert has never fired.",
            "type": [
              "number",
              "null"
            ]
          }
        }
      }
    }
  },
  "description": "The signed-in user's store alerts."
}

Finds a store by name and returns the discounted gift cards currently on sale for it from multiple gift card sellers — face value, price, discount percent, digital or physical — so the user can compare every seller and see the best discount. This is the preferred first call for any gift card question that names a store: 'best gift card discount for Gap', 'where can I buy discounted Instacart gift cards', 'compare Home Depot gift card discounts', 'current Target gift card deals'. No prior lookup is needed. Returns every matching store (best match first, one entry per country), each with its 'gift_cards' list and a 'gift_cards_url' page; an empty 'gift_cards' list means no discounted cards right now. Use get_gift_cards_by_store_id only when a store_id is already known, and get_cashback_rates_by_store_name when the user asks about cashback rates instead. Present every returned seller's listing to the user (a table with a link column, not only the best discount) and always show each gift card's 'url' as a clickable link — that tracked link is where the user buys the card at the discounted price. Also mention the store's 'gift_cards_url' page.

{
  "type": "object",
  "properties": {
    "store_name": {
      "description": "The retailer or brand name as a shopper would say it, e.g. 'Walmart', 'Nike', 'Best Buy', 'Expedia', 'Home Depot'. Matched case-insensitively at word boundaries of the store name and its known alternate names (exact name, then names starting with it, then names containing it as a word), best match first; a partial-word match (e.g. 'gap' inside 'Singapore') is only returned when nothing better exists. Pass the plain name only — no words like 'cashback', 'gift card' or a country.",
      "type": "string"
    },
    "country_code": {
      "description": "Optional. Lowercase ISO 3166-1 alpha-2 country code that limits results to one country, e.g. 'us' (United States), 'ca' (Canada), 'gb' (United Kingdom — use 'gb', not 'uk'), 'de' (Germany), 'au' (Australia), 'fr' (France). Pass it when the user names a country ('in Canada', 'UK cashback'); omit it to search all supported countries.",
      "type": [
        "string",
        "null"
      ],
      "default": null
    }
  },
  "required": [
    "store_name"
  ]
}

{
  "type": "object",
  "properties": {
    "stores": {
      "description": "Matching stores (one entry per country). Empty when nothing matched.",
      "type": "array",
      "items": {
        "description": "A store in one country with the discounted gift cards currently on sale for it.",
        "type": "object",
        "properties": {
          "store_id": {
            "description": "GotCashback's numeric store identifier.",
            "type": "integer"
          },
          "name": {
            "description": "Store (retailer) name.",
            "type": "string"
          },
          "country_code": {
            "description": "Lowercase ISO 3166-1 alpha-2 code of the country this store entry belongs to.",
            "type": "string"
          },
          "domain": {
            "description": "The store's website domain. Null when unknown.",
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "description": "GotCashback store page. Show it as a clickable link.",
            "type": [
              "string",
              "null"
            ]
          },
          "gift_cards_url": {
            "description": "GotCashback page listing all discounted gift cards for this store. Mention it as a clickable link.",
            "type": [
              "string",
              "null"
            ]
          },
          "gift_cards": {
            "description": "Discounted gift card listings from all sellers. Empty when no discounted cards are available right now.",
            "type": "array",
            "items": {
              "description": "One discounted gift card listing for the store from one gift card seller.",
              "type": "object",
              "properties": {
                "gift_card_id": {
                  "description": "GotCashback's numeric identifier of this listing.",
                  "type": "integer"
                },
                "seller": {
                  "description": "Name of the gift card seller / marketplace offering the card, e.g. 'CardCash', 'Raise'.",
                  "type": "string"
                },
                "seller_icon_url": {
                  "description": "Seller logo image URL. Null when none.",
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "type": {
                  "description": "Card format, e.g. 'Digital' (e-gift code delivered online) or 'Physical' (plastic card shipped).",
                  "type": "string"
                },
                "value_type": {
                  "description": "1 = a single fixed face value (see value and price); 2 = a range of face values (see value_from/value_to and price_from/price_to).",
                  "type": "integer"
                },
                "value": {
                  "description": "Face value of the card in the store's currency, when value_type is 1. Null for ranges.",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "value_from": {
                  "description": "Smallest face value available, when value_type is 2. Null for fixed-value cards.",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "value_to": {
                  "description": "Largest face value available, when value_type is 2. Null for fixed-value cards.",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "price": {
                  "description": "What the buyer pays for the card, when value_type is 1. The saving is value minus price.",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "price_from": {
                  "description": "Price of the smallest face value, when value_type is 2.",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "price_to": {
                  "description": "Price of the largest face value, when value_type is 2.",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "discount_percent": {
                  "description": "Discount off face value in percent (e.g. 8.5 means the card costs 8.5% less than it is worth). Null when it cannot be computed. Compare listings by this field to find the best gift card discount.",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "count": {
                  "description": "Number of cards in stock at the seller, when published. Null when unknown.",
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "url": {
                  "description": "Tracked GotCashback purchase link that leads to this card at the seller. Always show it to the user as a clickable link; the discount is only obtained by buying through it.",
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "description": "Stores matching the query, best match first, each with its discounted gift cards."
}

Returns the signed-in user's GotCashback profile (name, email, avatar). Use it when the user asks who they are signed in as or wants their account details. Requires OAuth sign-in with a GotCashback account; anonymous callers are prompted to authorize. All comparison tools work without signing in. Scope: 'profile'.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "profile": {
      "description": "The signed-in user's GotCashback account profile.",
      "type": "object",
      "properties": {
        "user_id": {
          "description": "GotCashback's numeric identifier for the account. Informational — no tool takes it as a parameter.",
          "type": "integer"
        },
        "first_name": {
          "description": "The name the user registered with. Null/absent when they never set one.",
          "type": [
            "string",
            "null"
          ]
        },
        "email": {
          "description": "The account's email address — where alert notifications are sent.",
          "type": [
            "string",
            "null"
          ]
        },
        "avatar": {
          "description": "URL of the user's profile picture. Null/absent when they have none.",
          "type": [
            "string",
            "null"
          ]
        }
      }
    }
  },
  "description": "The signed-in user's GotCashback profile."
}

Searches stores by name and returns the matching stores' identity only — store_id, name, country_code, website domain and GotCashback store page url — without cashback rates or gift cards. Use it when the user wants to know whether GotCashback covers a store, in which countries a store is listed, or when you need a store_id for the account tools (toggle_favorite_store, set_store_alert). For any question about cashback rates or gift card discounts call get_cashback_rates_by_store_name or get_gift_cards_by_store_name directly instead — they search by name themselves, so this tool is not a required first step. Returns matches best first; empty when nothing matched. When presenting stores, include each store's 'url' as a clickable link (and 'gift_cards_url' when present).

{
  "type": "object",
  "properties": {
    "store_name": {
      "description": "The retailer or brand name as a shopper would say it, e.g. 'Walmart', 'Nike', 'Best Buy', 'Expedia', 'Home Depot'. Matched case-insensitively at word boundaries of the store name and its known alternate names (exact name, then names starting with it, then names containing it as a word), best match first; a partial-word match (e.g. 'gap' inside 'Singapore') is only returned when nothing better exists. Pass the plain name only — no words like 'cashback', 'gift card' or a country.",
      "type": "string"
    },
    "country_code": {
      "description": "Optional. Lowercase ISO 3166-1 alpha-2 country code that limits results to one country, e.g. 'us' (United States), 'ca' (Canada), 'gb' (United Kingdom — use 'gb', not 'uk'), 'de' (Germany), 'au' (Australia), 'fr' (France). Pass it when the user names a country ('in Canada', 'UK cashback'); omit it to search all supported countries.",
      "type": [
        "string",
        "null"
      ],
      "default": null
    }
  },
  "required": [
    "store_name"
  ]
}

{
  "type": "object",
  "properties": {
    "stores": {
      "description": "Matching stores (one entry per country). Empty when nothing matched.",
      "type": "array",
      "items": {
        "description": "A store (retailer) in one country, with its current cashback rates when returned by a cashback tool.",
        "type": "object",
        "properties": {
          "store_id": {
            "description": "GotCashback's numeric store identifier. Pass it as store_id to the *_by_store_id, favorite and alert tools.",
            "type": "integer"
          },
          "name": {
            "description": "Store (retailer) name as shown on GotCashback.",
            "type": "string"
          },
          "country_code": {
            "description": "Lowercase ISO 3166-1 alpha-2 code of the country this store entry belongs to (e.g. 'us', 'ca', 'gb'). The same retailer appears once per country with country-specific rates.",
            "type": "string"
          },
          "url": {
            "description": "GotCashback store page listing all of this store's offers. Show it as a clickable link.",
            "type": "string"
          },
          "domain": {
            "description": "The store's website domain, e.g. 'walmart.com'. Null when unknown.",
            "type": [
              "string",
              "null"
            ]
          },
          "has_gift_cards": {
            "description": "True when discounted gift cards are currently available for this store (present in get_stores_by_country results only; null/absent otherwise).",
            "type": [
              "boolean",
              "null"
            ]
          },
          "gift_cards_url": {
            "description": "GotCashback page listing the store's discounted gift cards. Present when has_gift_cards is true; show it as a clickable link.",
            "type": [
              "string",
              "null"
            ]
          },
          "cashback_rates": {
            "description": "Current cashback offers for this store, one per portal and location (online / in-store). Empty when no portal currently offers cashback here; null/absent for tools that return store identity only.",
            "type": [
              "array",
              "null"
            ],
            "items": {
              "description": "One cashback offer for the store from one cashback portal.",
              "type": "object",
              "properties": {
                "portal": {
                  "description": "Name of the cashback portal offering this rate, e.g. 'Rakuten', 'TopCashback'.",
                  "type": "string"
                },
                "type": {
                  "description": "How the rate is expressed: 'percent' (rate is a percentage of the purchase amount) or 'fixedamount' (rate is a fixed amount in the store's local currency).",
                  "type": "string"
                },
                "rate": {
                  "description": "The cashback rate value. A percentage when type is 'percent' (5 means 5%), otherwise a fixed amount of cashback per purchase.",
                  "type": "number"
                },
                "upto": {
                  "description": "True when the rate is a maximum ('up to X%') that varies by product category or terms; false when it applies to all qualifying purchases. Rank 'up to' rates below a guaranteed rate of the same value.",
                  "type": "boolean"
                },
                "location": {
                  "description": "Where the cashback applies: 'online' (shop on the store's website through the link) or 'in-store' (linked-card cashback at physical locations).",
                  "type": "string"
                },
                "url": {
                  "description": "Tracked GotCashback click-through link that activates this cashback offer at the portal. Always show it to the user as a clickable link; cashback is only credited when they shop through it.",
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "description": "Stores matching the query, best match first, each with its current cashback rates."
}

Returns one cashback portal by its numeric id (the 'id' from a get_portals or get_portals_by_name result) with its payout terms for that country. Use it only when the id is already known; when the user names a portal, call get_portals_by_name instead. Returns an error when the id does not exist. Each portal includes its payout terms for that country: 'sign_up_bonus' (amount and the url that grants it, null when none), 'minimum_payout' with 'minimum_payout_currency' (smallest balance paid out, null when not published, 0 means no minimum), 'payment_frequency' (how often it pays, e.g. 'On demand', 'Weekly', 'Monthly'), and 'payment_methods' (payout options, e.g. 'PayPal', 'Direct deposit', 'Check', 'Gift card'). Use these to answer questions about a portal's sign-up bonus, payout threshold, payment schedule and payment options. When mentioning a sign-up bonus, show its 'url' as a clickable link — the bonus is only credited when the user signs up through it.

{
  "type": "object",
  "properties": {
    "portal_id": {
      "description": "GotCashback's numeric portal id, taken from the 'id' field of an earlier get_portals or get_portals_by_name result.",
      "type": "integer"
    }
  },
  "required": [
    "portal_id"
  ]
}

{
  "type": "object",
  "properties": {
    "portal": {
      "description": "A cashback portal in one country, with the payout terms it offers there.",
      "type": "object",
      "properties": {
        "id": {
          "description": "GotCashback's numeric identifier of this portal-in-country entry. Pass it as portal_id to get_portal_by_id.",
          "type": "integer"
        },
        "name": {
          "description": "Portal name, e.g. 'Rakuten', 'TopCashback'.",
          "type": "string"
        },
        "country_code": {
          "description": "Lowercase ISO 3166-1 alpha-2 code of the country these terms apply to. The same portal appears once per country.",
          "type": "string"
        },
        "url": {
          "description": "Link to join or open the portal (GotCashback's referral link when the portal has one). Show it as a clickable link.",
          "type": "string"
        },
        "icon_url": {
          "description": "Portal logo image URL.",
          "type": "string"
        },
        "sign_up_bonus": {
          "description": "Sign-up bonus the portal currently offers new members in this country. Null when no active bonus is published.",
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "amount": {
              "description": "Bonus as the portal advertises it, e.g. '$10' or '£5 after your first purchase'.",
              "type": "string"
            },
            "url": {
              "description": "Link that grants the bonus. Always show it as a clickable link; the bonus is only credited when the user signs up through it.",
              "type": "string"
            }
          }
        },
        "minimum_payout": {
          "description": "Smallest balance the portal pays out in this country, in minimum_payout_currency. Null when not published; 0 means there is no minimum.",
          "type": [
            "number",
            "null"
          ]
        },
        "minimum_payout_currency": {
          "description": "ISO 4217 currency code of minimum_payout, e.g. 'USD', 'GBP'. Null when minimum_payout is null.",
          "type": [
            "string",
            "null"
          ]
        },
        "payment_frequency": {
          "description": "How often the portal pays out in this country, e.g. 'On demand', 'Weekly', 'Monthly', 'Quarterly'. Null when not published.",
          "type": [
            "string",
            "null"
          ]
        },
        "payment_methods": {
          "description": "Payout methods offered in this country, e.g. 'PayPal', 'Direct deposit', 'Check', 'Gift card'. Null when none are published.",
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          }
        }
      }
    }
  },
  "description": "One cashback portal with its payout terms."
}

Finds a store by name and returns its current cashback rates from every cashback portal that lists it — online and in-store, percentage or fixed amount, with 'up to' flags — so the user can compare every portal and see the best. This is the preferred first call for any cashback question that names a store: 'best cashback for Walmart', 'highest Nike cashback', 'cashback at Expedia', 'Walmart cashback today', 'compare Walmart cashback portals', 'Best Buy in-store cashback', 'Dell cashback in Germany'. No prior lookup is needed — do not call get_stores_by_name, get_stores_by_country or get_countries first. Returns every matching store (best match first, one entry per country), each with its 'cashback_rates'; an empty list means no match — retry with a shorter name or without country_code. Use get_cashback_rates_by_store_id only when a store_id is already known, get_gift_cards_by_store_name for gift card discounts, and get_best_deals_by_brand when the user asks where to buy a brand's products rather than about a specific store. Rates reflect GotCashback's current data, refreshed several times a day. Present every returned portal's rate to the user (a table with a link column, not only the best one) and always show each rate's 'url' as a clickable link — cashback is only credited when the user clicks through it.

{
  "type": "object",
  "properties": {
    "store_name": {
      "description": "The retailer or brand name as a shopper would say it, e.g. 'Walmart', 'Nike', 'Best Buy', 'Expedia', 'Home Depot'. Matched case-insensitively at word boundaries of the store name and its known alternate names (exact name, then names starting with it, then names containing it as a word), best match first; a partial-word match (e.g. 'gap' inside 'Singapore') is only returned when nothing better exists. Pass the plain name only — no words like 'cashback', 'gift card' or a country.",
      "type": "string"
    },
    "country_code": {
      "description": "Optional. Lowercase ISO 3166-1 alpha-2 country code that limits results to one country, e.g. 'us' (United States), 'ca' (Canada), 'gb' (United Kingdom — use 'gb', not 'uk'), 'de' (Germany), 'au' (Australia), 'fr' (France). Pass it when the user names a country ('in Canada', 'UK cashback'); omit it to search all supported countries.",
      "type": [
        "string",
        "null"
      ],
      "default": null
    }
  },
  "required": [
    "store_name"
  ]
}

{
  "type": "object",
  "properties": {
    "stores": {
      "description": "Matching stores (one entry per country). Empty when nothing matched.",
      "type": "array",
      "items": {
        "description": "A store (retailer) in one country, with its current cashback rates when returned by a cashback tool.",
        "type": "object",
        "properties": {
          "store_id": {
            "description": "GotCashback's numeric store identifier. Pass it as store_id to the *_by_store_id, favorite and alert tools.",
            "type": "integer"
          },
          "name": {
            "description": "Store (retailer) name as shown on GotCashback.",
            "type": "string"
          },
          "country_code": {
            "description": "Lowercase ISO 3166-1 alpha-2 code of the country this store entry belongs to (e.g. 'us', 'ca', 'gb'). The same retailer appears once per country with country-specific rates.",
            "type": "string"
          },
          "url": {
            "description": "GotCashback store page listing all of this store's offers. Show it as a clickable link.",
            "type": "string"
          },
          "domain": {
            "description": "The store's website domain, e.g. 'walmart.com'. Null when unknown.",
            "type": [
              "string",
              "null"
            ]
          },
          "has_gift_cards": {
            "description": "True when discounted gift cards are currently available for this store (present in get_stores_by_country results only; null/absent otherwise).",
            "type": [
              "boolean",
              "null"
            ]
          },
          "gift_cards_url": {
            "description": "GotCashback page listing the store's discounted gift cards. Present when has_gift_cards is true; show it as a clickable link.",
            "type": [
              "string",
              "null"
            ]
          },
          "cashback_rates": {
            "description": "Current cashback offers for this store, one per portal and location (online / in-store). Empty when no portal currently offers cashback here; null/absent for tools that return store identity only.",
            "type": [
              "array",
              "null"
            ],
            "items": {
              "description": "One cashback offer for the store from one cashback portal.",
              "type": "object",
              "properties": {
                "portal": {
                  "description": "Name of the cashback portal offering this rate, e.g. 'Rakuten', 'TopCashback'.",
                  "type": "string"
                },
                "type": {
                  "description": "How the rate is expressed: 'percent' (rate is a percentage of the purchase amount) or 'fixedamount' (rate is a fixed amount in the store's local currency).",
                  "type": "string"
                },
                "rate": {
                  "description": "The cashback rate value. A percentage when type is 'percent' (5 means 5%), otherwise a fixed amount of cashback per purchase.",
                  "type": "number"
                },
                "upto": {
                  "description": "True when the rate is a maximum ('up to X%') that varies by product category or terms; false when it applies to all qualifying purchases. Rank 'up to' rates below a guaranteed rate of the same value.",
                  "type": "boolean"
                },
                "location": {
                  "description": "Where the cashback applies: 'online' (shop on the store's website through the link) or 'in-store' (linked-card cashback at physical locations).",
                  "type": "string"
                },
                "url": {
                  "description": "Tracked GotCashback click-through link that activates this cashback offer at the portal. Always show it to the user as a clickable link; cashback is only credited when they shop through it.",
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "description": "Stores matching the query, best match first, each with its current cashback rates."
}

Creates or updates an alert that emails the signed-in user when a store's cashback rate or gift card discount reaches the threshold percent or higher. Use it for 'alert me when Nike cashback hits 10%' or 'tell me when Target gift cards are 15% off'. Re-saving an existing alert updates its threshold and re-arms it. At most 10 active alerts per user. Needs the store_id: take it from an earlier result, or find it with get_stores_by_name (optionally with country_code). Requires OAuth sign-in with a GotCashback account and the 'alerts' scope; anonymous callers are prompted to authorize.

{
  "type": "object",
  "properties": {
    "store_id": {
      "description": "GotCashback's numeric store_id, taken from an earlier result (a store, cashback rate, gift card, deals, favorites or alerts response). If you only have a store name, use the by-name tool instead.",
      "type": "integer"
    },
    "alert_type": {
      "description": "Alert type: 'cashback' (fires on the store's best flat cash rate: 'up to' rates and airline miles, credit card and points portals are ignored) or 'gift_card' (fires on the store's best gift card discount). Use the alert_type value from get_my_alerts as-is.",
      "type": "string",
      "enum": [
        "gift_card",
        "cashback"
      ]
    },
    "threshold_percent": {
      "description": "Fire when the rate/discount reaches this percent or higher (greater than 0, at most 100), e.g. 10 for 10%",
      "type": "number"
    }
  },
  "required": [
    "store_id",
    "alert_type",
    "threshold_percent"
  ]
}

Adds a store to, or removes it from, the signed-in user's favorite stores. Use it for 'add Best Buy to my favorites' or 'remove Nike from my favorites'. Needs the store_id: take it from an earlier result, or find it with get_stores_by_name (optionally with country_code). Requires OAuth sign-in with a GotCashback account; anonymous callers are prompted to authorize. All comparison tools work without signing in. Scope: 'favorites'.

{
  "type": "object",
  "properties": {
    "store_id": {
      "description": "GotCashback's numeric store_id, taken from an earlier result (a store, cashback rate, gift card, deals, favorites or alerts response). If you only have a store name, use the by-name tool instead.",
      "type": "integer"
    },
    "favorite": {
      "description": "true to add the store to favorites, false to remove it",
      "type": "boolean"
    }
  },
  "required": [
    "store_id",
    "favorite"
  ]
}

Returns the signed-in user's favorite stores (with their store_id). Use it when the user asks about 'my favorites' or 'my saved stores'; pair the store_ids with get_cashback_rates_by_store_id to report current rates for them. Requires OAuth sign-in with a GotCashback account; anonymous callers are prompted to authorize. All comparison tools work without signing in. Scope: 'favorites'.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "stores": {
      "description": "The user's favorite stores. Empty when they have none.",
      "type": "array",
      "items": {
        "description": "A store the user has saved to their GotCashback favorites.",
        "type": "object",
        "properties": {
          "store_id": {
            "description": "GotCashback's numeric store identifier. Pass it as store_id to get_cashback_rates_by_store_id, get_gift_cards_by_store_id, set_store_alert or toggle_favorite_store.",
            "type": "integer"
          },
          "name": {
            "description": "Store (retailer) name as shown on GotCashback.",
            "type": "string"
          },
          "country_code": {
            "description": "Lowercase ISO 3166-1 alpha-2 code of the country this store entry belongs to (e.g. 'us', 'ca', 'gb').",
            "type": [
              "string",
              "null"
            ]
          },
          "country_name": {
            "description": "Country name in English, e.g. 'United States'.",
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  },
  "description": "The signed-in user's favorite stores."
}

Removes the signed-in user's alert for a store and alert type ('cashback' or 'gift_card'). Use it for 'stop alerting me about Nike cashback'. Use get_my_alerts to find the store_id and alert_type of an existing alert and pass both through unchanged. Requires OAuth sign-in with a GotCashback account and the 'alerts' scope; anonymous callers are prompted to authorize.

{
  "type": "object",
  "properties": {
    "store_id": {
      "description": "GotCashback's numeric store_id, taken from an earlier result (a store, cashback rate, gift card, deals, favorites or alerts response). If you only have a store name, use the by-name tool instead.",
      "type": "integer"
    },
    "alert_type": {
      "description": "Alert type: 'cashback' (fires on the store's best flat cash rate: 'up to' rates and airline miles, credit card and points portals are ignored) or 'gift_card' (fires on the store's best gift card discount). Use the alert_type value from get_my_alerts as-is.",
      "type": "string",
      "enum": [
        "gift_card",
        "cashback"
      ]
    }
  },
  "required": [
    "store_id",
    "alert_type"
  ]
}

Finds where to buy a brand's products with the most savings: returns the matching brands and, for each, the stores carrying it ranked by best current cashback rate, then best gift card discount. Use it when the user names a product brand rather than a specific retailer — 'where is the best cashback for Adidas products?', 'cheapest place to buy Apple products with cashback'. When the user names a retailer ('Nike cashback' meaning the Nike store), call get_cashback_rates_by_store_name instead; for a type of product use get_best_deals_by_category. Returns up to 5 matching brands, best match first; empty when nothing matched. Rates reflect GotCashback's current data, refreshed several times a day. Always show each store's links to the user: best_cashback_rate.url (clickable link that activates the cashback) and gift_cards_url (where to buy the discounted gift cards).

{
  "type": "object",
  "properties": {
    "brand_name": {
      "description": "The product brand name, e.g. 'Adidas', 'Dyson', 'LEGO'. Matched case-insensitively at word boundaries of the brand name and its alternate names, best match first; multi-word names fall back to matching individual words.",
      "type": "string"
    },
    "country_code": {
      "description": "Optional. Lowercase ISO 3166-1 alpha-2 country code that limits results to one country, e.g. 'us' (United States), 'ca' (Canada), 'gb' (United Kingdom — use 'gb', not 'uk'), 'de' (Germany), 'au' (Australia), 'fr' (France). Pass it when the user names a country ('in Canada', 'UK cashback'); omit it to search all supported countries.",
      "type": [
        "string",
        "null"
      ],
      "default": null
    }
  },
  "required": [
    "brand_name"
  ]
}

{
  "type": "object",
  "properties": {
    "matches": {
      "description": "Matched brands / categories (up to 5, best match first). Empty when nothing matched.",
      "type": "array",
      "items": {
        "description": "A matched brand or shopping category and the stores carrying it, ranked by best cashback rate, then best gift card discount.",
        "type": "object",
        "properties": {
          "name": {
            "description": "The matched brand or category name as GotCashback knows it. Several partial matches can be returned; pick the one that fits the user's request.",
            "type": "string"
          },
          "country_code": {
            "description": "Lowercase ISO 3166-1 alpha-2 code of the country this match belongs to.",
            "type": "string"
          },
          "stores": {
            "description": "Stores carrying the brand / in the category that currently have cashback or discounted gift cards, best cashback rate first. Empty when none qualify.",
            "type": "array",
            "items": {
              "description": "A store's current best money-saving options for the matched brand or category.",
              "type": "object",
              "properties": {
                "store_id": {
                  "description": "GotCashback's numeric store identifier.",
                  "type": "integer"
                },
                "name": {
                  "description": "Store (retailer) name.",
                  "type": "string"
                },
                "country_code": {
                  "description": "Lowercase ISO 3166-1 alpha-2 code of the store's country.",
                  "type": "string"
                },
                "url": {
                  "description": "GotCashback store page. Show it as a clickable link.",
                  "type": "string"
                },
                "best_cashback_rate": {
                  "description": "The store's best percentage cashback rate across all portals, with the portal name and the tracked 'url' that activates it. Null when the store has no percentage cashback.",
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "portal": {
                      "description": "Name of the cashback portal offering this rate, e.g. 'Rakuten', 'TopCashback'.",
                      "type": "string"
                    },
                    "type": {
                      "description": "How the rate is expressed: 'percent' (rate is a percentage of the purchase amount) or 'fixedamount' (rate is a fixed amount in the store's local currency).",
                      "type": "string"
                    },
                    "rate": {
                      "description": "The cashback rate value. A percentage when type is 'percent' (5 means 5%), otherwise a fixed amount of cashback per purchase.",
                      "type": "number"
                    },
                    "upto": {
                      "description": "True when the rate is a maximum ('up to X%') that varies by product category or terms; false when it applies to all qualifying purchases. Rank 'up to' rates below a guaranteed rate of the same value.",
                      "type": "boolean"
                    },
                    "location": {
                      "description": "Where the cashback applies: 'online' (shop on the store's website through the link) or 'in-store' (linked-card cashback at physical locations).",
                      "type": "string"
                    },
                    "url": {
                      "description": "Tracked GotCashback click-through link that activates this cashback offer at the portal. Always show it to the user as a clickable link; cashback is only credited when they shop through it.",
                      "type": "string"
                    }
                  }
                },
                "best_gift_card_discount_percent": {
                  "description": "The largest discount off face value (in percent) among the store's discounted gift cards. Null when no discounted gift cards are available.",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "gift_cards_url": {
                  "description": "GotCashback page listing the store's discounted gift cards. Present when best_gift_card_discount_percent is set; show it as a clickable link.",
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "description": "Brands or categories matching the query, each with its stores ranked by savings."
}

Finds where to buy products from a shopping category with the most savings: returns the matching categories and, for each, the stores in it ranked by best current cashback rate, then best gift card discount. Use it when the user names a type of product or a category rather than a store or brand — 'where can I buy dog food with the biggest discount?', 'best cashback for electronics', 'travel booking sites with cashback'. For a specific retailer use get_cashback_rates_by_store_name; for a product brand use get_best_deals_by_brand. Returns up to 5 matching categories, best match first; empty when nothing matched. Rates reflect GotCashback's current data, refreshed several times a day. Always show each store's links to the user: best_cashback_rate.url (clickable link that activates the cashback) and gift_cards_url (where to buy the discounted gift cards).

{
  "type": "object",
  "properties": {
    "category_name": {
      "description": "The shopping category or product type, e.g. 'Pet Supplies', 'dog food', 'electronics', 'travel'. Matched case-insensitively at word boundaries of the category name and its alternate names, best match first; multi-word phrases fall back to matching individual words.",
      "type": "string"
    },
    "country_code": {
      "description": "Optional. Lowercase ISO 3166-1 alpha-2 country code that limits results to one country, e.g. 'us' (United States), 'ca' (Canada), 'gb' (United Kingdom — use 'gb', not 'uk'), 'de' (Germany), 'au' (Australia), 'fr' (France). Pass it when the user names a country ('in Canada', 'UK cashback'); omit it to search all supported countries.",
      "type": [
        "string",
        "null"
      ],
      "default": null
    }
  },
  "required": [
    "category_name"
  ]
}

{
  "type": "object",
  "properties": {
    "matches": {
      "description": "Matched brands / categories (up to 5, best match first). Empty when nothing matched.",
      "type": "array",
      "items": {
        "description": "A matched brand or shopping category and the stores carrying it, ranked by best cashback rate, then best gift card discount.",
        "type": "object",
        "properties": {
          "name": {
            "description": "The matched brand or category name as GotCashback knows it. Several partial matches can be returned; pick the one that fits the user's request.",
            "type": "string"
          },
          "country_code": {
            "description": "Lowercase ISO 3166-1 alpha-2 code of the country this match belongs to.",
            "type": "string"
          },
          "stores": {
            "description": "Stores carrying the brand / in the category that currently have cashback or discounted gift cards, best cashback rate first. Empty when none qualify.",
            "type": "array",
            "items": {
              "description": "A store's current best money-saving options for the matched brand or category.",
              "type": "object",
              "properties": {
                "store_id": {
                  "description": "GotCashback's numeric store identifier.",
                  "type": "integer"
                },
                "name": {
                  "description": "Store (retailer) name.",
                  "type": "string"
                },
                "country_code": {
                  "description": "Lowercase ISO 3166-1 alpha-2 code of the store's country.",
                  "type": "string"
                },
                "url": {
                  "description": "GotCashback store page. Show it as a clickable link.",
                  "type": "string"
                },
                "best_cashback_rate": {
                  "description": "The store's best percentage cashback rate across all portals, with the portal name and the tracked 'url' that activates it. Null when the store has no percentage cashback.",
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "portal": {
                      "description": "Name of the cashback portal offering this rate, e.g. 'Rakuten', 'TopCashback'.",
                      "type": "string"
                    },
                    "type": {
                      "description": "How the rate is expressed: 'percent' (rate is a percentage of the purchase amount) or 'fixedamount' (rate is a fixed amount in the store's local currency).",
                      "type": "string"
                    },
                    "rate": {
                      "description": "The cashback rate value. A percentage when type is 'percent' (5 means 5%), otherwise a fixed amount of cashback per purchase.",
                      "type": "number"
                    },
                    "upto": {
                      "description": "True when the rate is a maximum ('up to X%') that varies by product category or terms; false when it applies to all qualifying purchases. Rank 'up to' rates below a guaranteed rate of the same value.",
                      "type": "boolean"
                    },
                    "location": {
                      "description": "Where the cashback applies: 'online' (shop on the store's website through the link) or 'in-store' (linked-card cashback at physical locations).",
                      "type": "string"
                    },
                    "url": {
                      "description": "Tracked GotCashback click-through link that activates this cashback offer at the portal. Always show it to the user as a clickable link; cashback is only credited when they shop through it.",
                      "type": "string"
                    }
                  }
                },
                "best_gift_card_discount_percent": {
                  "description": "The largest discount off face value (in percent) among the store's discounted gift cards. Null when no discounted gift cards are available.",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "gift_cards_url": {
                  "description": "GotCashback page listing the store's discounted gift cards. Present when best_gift_card_discount_percent is set; show it as a clickable link.",
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "description": "Brands or categories matching the query, each with its stores ranked by savings."
}