Getting a list of countries that you can order in
To create a payout link in the ordering process, you’ll need to provide a list of products that are all redeemable in the same country. The list of countries endpoint will provide you with a dynamic list with all of the countries in which you have available payout types. This will return a list of ISO3166 ALPHA-2 country codes. We’ll be modifying this list over time, so your implementation should handle the addition and removal of countries from this list. You can use this to aggregate products that belong to a country for ordering by using thecountries_redeemable_in query parameter, in the endpoint described below.
List all countries
Endpoint details for listing all supported countries
Retrieving your catalog
We’ve updated our catalog to provide you with even more details than before, with improved filtering, pagination, and performance across the board. We’ve added new levels of granularity to payout types - differentiating betweengift_card, subscription, and payment type products, and we’ll be looking to add to these in the future. At the bottom of this page, in the Example response section, there are examples of a few permutations of responses.
We recommend that you poll the list endpoint to retrieve full catalog details hourly and in any critical journeys where you fetch the details of an individual product by using the code query parameter to return the latest details of a product in a timely manner.
List all products
Endpoint details for listing all products, filterable by country
Get details of a specific product
Endpoint details for getting details of a specific product by its code
Field usage guidance
In this section, we’ll detail a few of the key fields that should influence your implementation.Generic fields
is_orderable
This field indicates whether you are currently able to order a product or not. We recommend that you only ever display products to people placing orders when this field is true - we will reject any orders placed for products where this is false . You can pass this as a query parameter as part of your request.
currency & countries_redeemable_in
As detailed in the Currencies section of this guide - we’re constantly expanding our network to increase the payouts we can offer you and your customers. Your implementation should handle additions to these fields in their respective ISO formats.
discount_multiplier
The discount is represented as a decimal between 0 & 1. e.g. a discount_multiplier of 0.10 would be a 10% discount.
payout_type
You’ll notice in the API specification that there are currently three fields, gift_card, subscription, and payment that are nullable and will not be present in certain responses. The payout_type field will indicate which of these fields is present, and your implementation should then use this key to extract the relevant required details.
We’ll be adding more payout types in the future, and your implementation should handle these additions gracefully.
categories
Used for categorizing the products.
Examples of values (not comprehensive): department-stores home-and-diy toys-and-games supermarkets booksellers experiences fashion electricals entertainment travel leisure-and-sports food-and-drink beauty-and-lifestyle jewellers prepaid-card.
content_resources
The URL fields in this response object will contain URL’s to markdown files containing their respective content. You can use this markdown and render it with your own styling as you wish.
The fields will be null when the text has been removed, and present when added. We’ll update this content semi-regularly; a 403 / 404 will be returned, should this content have been removed. Your implementation should handle this.
Gift card specific fields
denominations
This field will return you the constraints of values that you can order.
The example responses below contain the different responses that the API can return, whether the denominations are open or fixed :
openproducts will includeminimum_valueandmaximum_valuefields. This means that you can order gift cards within the range ofminimum_valueandmaximum_value.fixedproducts will include a list of values in theavailable_denominationsfield. You can only order values contained in the list that is returned to you.
Subscription specific fields
subscription_plans
Subscriptions each come with a list of subscription plans, detailing things such as the duration of the subscription and the price it costs to order each of the subscription plans - this is without your discount applied.
subscription_plan_code is returned as part of the subscription plan - use this code, not the top-level object code as part of your order. We’ll add more subscription plans for your customers to order over time.
Payment specific fields
denominations
Similar to gift cards, payments have denomination constraints with minimum_value and maximum_value fields that define the allowed payment ranges, but will always be open denomination. Therefore, we don’t have the list of available denominations here.
Example Response
JSON