Product Listing Guide
Whether you’re showing the latest product offering to your customers, or verifying constraints during your order process, you’ll want the latest payout details.
This guide will outline steps and recommendations from us to make your integration as smooth as possible.
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.
Previously, we have provided you with a static list of countries, our new countries API [List of Countries] 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 the countries_redeemable_in
query parameter, in the endpoint described below.
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 between gift_card
and subscription
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 Product Listing 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.
Field usage guidance
In this section, we’ll detail a few of the key fields that should influence your implementation.
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 two fields, gift_card
and subscription
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.
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
:
open
products will includeminimum_value
andmaximum_value
fields. This means that you can order gift cards within the range ofminimum_value
andmaximum_value
.fixed
products will include a list of values in theavailable_denominations
field. 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.
Example Response
{
"catalog":[
{
"approval_state":"APPROVED",
"categories":[
"experiences"
],
"code":"EXAMPLEFIXED-US",
"countries_redeemable_in":[
"US"
],
"currency":"USD",
"customer_service":{
"phone_number":"+1 (123) 456-7890",
"website_url":"https:/example.com/contact"
},
"discount_multiplier":"0.1000",
"is_orderable":true,
"name":"Example Fixed Denominations US",
"payout_type":"gift_card",
"state":"LIVE",
"gift_card":{
"assets":{
"card_image_url":"https:/gift.runa.io/static/product_assets/EXAMPLEFIXED-US/EXAMPLEFIXED-US-card.png",
"icon_image_url":"https:/gift.runa.io/static/product_assets/EXAMPLEFIXED-US/EXAMPLEFIXED-US-icon.png",
"primary_color":"#FFFFFF"
},
"balance_check_url":"https://example.com/balance-check-url",
"content_resources":{
"description_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/EXAMPLEFIXED-US/description.md",
"disclaimer_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/EXAMPLEFIXED-US/disclaimer.md",
"locale":"en_US",
"redemption_instructions_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/EXAMPLEFIXED-US/redemption_instructions.md",
"refund_policy_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/EXAMPLEFIXED-US/refund_policy.md",
"reissuance_policy_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/EXAMPLEFIXED-US/reissuance_policy.md",
"terms_buyer_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/EXAMPLEFIXED-US/terms_buyer.md",
"terms_consumer_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/EXAMPLEFIXED-US/terms_consumer.md"
},
"denominations":{
"available_list":[
"0.5",
"1",
"5",
"10",
"25",
"50",
"100"
],
"maximum_value":"100",
"minimum_value":"0.5",
"type":"fixed"
},
"expiry":{
"date_policy":"Does not expire",
"in_months":0,
"type":"indefinite"
},
"redeemable_at":"online",
"website_url":"https://example.com"
}
},
{
"approval_state":"APPROVED",
"categories":[
"electricals"
],
"code":"EXAMPLEOPEN-US",
"countries_redeemable_in":[
"US"
],
"currency":"USD",
"customer_service":{
"phone_number":"+1 (123) 456-7890",
"website_url":"https:/example.com/contact"
},
"discount_multiplier":"0.3",
"is_orderable":true,
"name":"Example Open Denominations US",
"payout_type":"gift_card",
"state":"TEMPORARILY_DISABLED",
"gift_card":{
"assets":{
"card_image_url":"https:/gift.runa.io/static/product_assets/EXAMPLEOPEN-US/EXAMPLEOPEN-US-card.png",
"icon_image_url":"https:/gift.runa.io/static/product_assets/EXAMPLEOPEN-US/EXAMPLEOPEN-US-icon.png",
"primary_color":"#FFFFFF"
},
"balance_check_url":"https://example.com/balance-check-url",
"content_resources":{
"description_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/EXAMPLEOPEN-US/description.md",
"disclaimer_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/EXAMPLEOPEN-US/disclaimer.md",
"locale":"en_US",
"redemption_instructions_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/EXAMPLEOPEN-US/redemption_instructions.md",
"refund_policy_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/EXAMPLEOPEN-US/refund_policy.md",
"reissuance_policy_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/EXAMPLEOPEN-US/reissuance_policy.md",
"terms_buyer_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/EXAMPLEOPEN-US/terms_buyer.md",
"terms_consumer_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/EXAMPLEOPEN-US/terms_consumer.md"
},
"denominations":{
"available_list":null,
"maximum_value":"500.00",
"minimum_value":"15",
"type":"open"
},
"expiry":{
"date_policy":"Does not expire",
"in_months":0,
"type":"indefinite"
},
"redeemable_at":"all",
"website_url":"https://example.com"
}
},
{
"approval_state":"APPROVED",
"categories":[
"beauty-and-fashion"
],
"code":"SUBSCRIPTION-GB",
"countries_redeemable_in":[
"GN"
],
"currency":"GBP",
"customer_service":{
"phone_number":"+4420 1234 5678",
"website_url":"https://example.com/subscription-customer-service"
},
"discount_multiplier":"0.1940",
"is_orderable":true,
"name":"Subscription Example GB",
"payout_type":"subscription",
"state":"LIVE",
"subscription":{
"assets":{
"card_image_url":"https:/gift.runa.io/static/product_assets/SUBSCRIPTION-GB/SUBSCRIPTION-GB-card.png",
"icon_image_url":"https:/gift.runa.io/static/product_assets/SUBSCRIPTION-GB/SUBSCRIPTION-GB-icon.png",
"primary_color":"#FFFFFF"
},
"balance_check_url":"https://example.com/subscription-balance-check-url",
"content_resources":{
"description_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/SUBSCRIPTION-GB/description.md",
"disclaimer_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/SUBSCRIPTION-GB/disclaimer.md",
"locale":"es_ES",
"redemption_instructions_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/SUBSCRIPTION-GB/redemption_instructions.md",
"refund_policy_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/SUBSCRIPTION-GB/refund_policy.md",
"reissuance_policy_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/SUBSCRIPTION-GB/reissuance_policy.md",
"terms_buyer_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/SUBSCRIPTION-GB/terms_buyer.md",
"terms_consumer_markdown_url":"https:/catalog-service-prod-content-resource-download-bucket.s3.eu-west-1.amazonaws.com/resources/SUBSCRIPTION-GB/terms_consumer.md"
},
"expiry":{
"date_policy":"Expires 1 year from issue date",
"in_months":12,
"type":"from-issue-date"
},
"redeemable_at":"online",
"subscription_plans":[
{
"length":6,
"length_unit":"MONTHS",
"name":"Subscription Example 6 months",
"price":107.94,
"subscription_plan_code":"SUBSCRIPTION-GB"
}
],
"website_url":"https://example.com/subscription-details"
}
}
],
"pagination":{
"cursors":{
"after":"After Cursor",
"before":"Before Cursor"
},
"page":{
"limit":500
}
}
}
Updated 5 months ago