catalogapi

Check whether CatalogAPI can supply rewards in one or more countries, and which product categories are available there. Call this when someone asks if rewards, gift cards, or incentives can be offered in a particular country, when they have recipients in several countries, or when they ask which countries are supported. This is the authoritative answer about what a country supports.

{
  "type": "object",
  "properties": {
    "countries": {
      "description": "ISO-2 country codes, for example [\"US\", \"PL\"]. Omit to list every covered country.",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  }
}

Get detail for a single catalog item. Call this after search_rewards when someone asks about a specific item.

{
  "type": "object",
  "properties": {
    "country": {
      "description": "ISO-2 country code the item came from.",
      "type": "string"
    },
    "item_id": {
      "description": "The item id returned by search_rewards.",
      "type": "string"
    }
  },
  "required": [
    "country",
    "item_id"
  ]
}

Answer questions about CatalogAPI itself: what it is, how rewards are delivered to recipients, how currencies and billing work, whether the catalog can be customized or extended with your own products, how the API integration works, and how to get started. Call this for any question about the service, the company, or the product model rather than about specific catalog items.

{
  "type": "object",
  "properties": {
    "topic": {
      "description": "Which question to answer. overview: What CatalogAPI is and the two ways to use it. coverage: Which countries are covered and what a catalog contains. custom_catalogs: Sourcing items on request, and putting your own products in your catalog as a supplier. fulfillment: How each kind of reward reaches a recipient, and who supports it. pricing_and_billing: What catalog prices mean, what you charge your own users, how tax and shipping are handled (which depends on whether the program is points-based or a store where people spend their own money), and how billing and currency conversion work. integration: What integrating looks like, including the fulfillment-only path. getting_started: How to get sandbox access and what production involves.",
      "enum": [
        "overview",
        "coverage",
        "custom_catalogs",
        "fulfillment",
        "pricing_and_billing",
        "integration",
        "getting_started"
      ]
    }
  },
  "required": [
    "topic"
  ]
}

Show example rewards available in one country. Call this when someone asks what kind of thing is on offer, or wants to see the catalog for a country. Returns items from a demonstration catalog: these are examples rather than the full inventory, and no pricing is returned. Use check_coverage for the definitive answer about what a country supports.

{
  "type": "object",
  "properties": {
    "country": {
      "description": "ISO-2 country code, for example \"PL\".",
      "type": "string"
    },
    "query": {
      "description": "Optional search term, for example \"headphones\".",
      "type": "string"
    }
  },
  "required": [
    "country"
  ]
}