Whether you’re showing the latest product offering to your customers, or verifying constraints during your order process, you’ll want the latest catalog details.

​
Countries & currencies

To create a payout link, you’ll need to provide one or more products that are all redeemable in the same currency. See the currencies reference for a list of currency supported countries. You may also want to limit the products you return to only those that can be redeemed in a specific country. You can fetch a list of countries using the list countries endpoint. 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 recommend that you query the list endpoint to retrieve full catalog details periodically 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. You can also use the product update webhook to be notified of changes to products.

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

​
Filtering the catalog

You can filter by a number of fields in the list endpoint to reduce the number of products returned to only those that are relevant to your customers.
Query parameterDescription
is_orderableWhen set to true only returns products that can be ordered. If you’re presenting a list of products to your customers, you should only display products where this is true.
countries_redeemable_inOnly return products that can be redeemed in a specific country, see the countries reference for currently supported countries.
categoriesLimit the products to one or more categories, see the categories endpoint for a list of all current categories.

​
Important fields

A few of the key fields that should influence your implementation are detailed below. For details on all fields, see the product list endpoint reference.

​
Generic fields

​
code
string

A unique code identifying the product. Use this code when placing an order.
​
is_orderable
boolean

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
string

The currency of the product, represented by an ISO 4217 currency code. See currencies for a list of supported currencies. Orders can only be placed in one currency at a time, ensure you don’t mix currencies in the same order.
​
countries_redeemable_in
string[]

The countries in which the product can be redeemed. See the countries reference for a list of supported countries. You can filter by this field to only return products that can be redeemed in a specific country.

​
Type specific fields

There are three different payout types that you can order, each with their own specific object for details.
  • gift_card: A gift card is a payout that can be redeemed for a specific value.
  • subscription: A subscription is a payout that can be ordered for a specific duration.
  • payment: A payment is a payout that can be ordered for a specific value.
​
payout_type
string

You should use the payout_type field to determine which object to use to extract details for the product.We’ll be adding more payout types in the future, and your implementation should handle these additions gracefully.

​
Specific gift_card fields

The gift_card object will only be present when the payout_type is gift_card.
​
gift_card.denominations
object

Gift cards are either open or fixed denomination.
  • open products will include minimum_value and maximum_value fields. This means that you can order gift cards within the range of minimum_value and maximum_value.
  • fixed products will include a list of values in the available_list field. You can only order values contained in the list that is returned to you.
"denominations": {
    "type": "open",
    "minimum_value": "5.00",
    "maximum_value": "250.00",
    "available_list": null
}

​
Specific subscription fields

The subscription object will only be present when the payout_type is subscription.
​
subscription.subscription_plans
object[]

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 example
{
    "length_unit": "MONTHS",
    "length": 3,
    "name": "3 month subscription",
    "price": "10.00",
    "subscription_plan_code": "XYZ-US-SUB-1"
},
{
    "length_unit": "MONTHS",
    "length": 6,
    "name": "6 month subscription",
    "price": "20.00",
    "subscription_plan_code": "XYZ-US-SUB-2"
}
subscription_plan_code is returned as part of the subscription plan. You must use this code, not the top-level code as part of your order.

​
Specific payment fields

The payment object will only be present when the payout_type is payment.
​
payment.denominations
object

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.
Payment denomination example
"denominations": {
    "minimum_value": "5.00",
    "maximum_value": "250.00",
}

​
Paging through the catalog

The catalog is paginated, with a default page size of 500 products. You can use the after and limit query parameters to control the page size and the cursor to fetch the next page of products. 
GET /product?after={cursor}&limit=100
The response will include a pagination object with the following fields. You can use the after cursor to fetch the next page of products, and the before cursor to fetch the previous page of products. 
"pagination": {
    "cursors": {
        "after": "MMM-US",
        "before": "AAA-US"
    },
    "page": {
        "limit": 100
    }
}

Pagination reference

More details on how pagination works in the Runa API.

​
Keeping your catalog in sync

If you maintain a copy of the product catalog in your system you can use the product update webhook to keep it synchronized and avoid order failures.

How to implement real-time product updates

Next take a read of our guide to implement real-time product updates in your system.