Get product details

Returns a single product by its code, e.g. XYZ-US. This endpoint returns different payout types:

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.

You should use the payout_type field to determine which object to use to extract details for the product. The different payout types have different fields, so you should use the appropriate object to extract the details you need. This endpoint supports returning product content in different formats. See the content parameter for more details.

Need help with the product catalog?

We have a guide to help you get started with the product catalog, including how to filter the catalog and the different payout types.

Authorizations

X-Api-Key

string

header

required

Your API key. See the API key page on details of how to generate and store your keys.

Headers

X-Api-Version

string

The dated version of the API, if not specified a default is used. See API versioning for more information.

Path Parameters

product_code

string

required

The code of the product.

Query Parameters

content

enum<string>

default:url

Defines the format for product content resources.

url (default) for external URLs to markdown content
md for Markdown content in the response
html for rendered HTML in the response

Available options:

url,

md,

html

Response

Product details

name

string

required

The name of the product.

Example:

"Example Merchant"

code

string

required

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

For subscription products, this code identifies the top level product. You must use the subscription_plan_code instead when ordering.

Example:

"XYZ-US"

currency

string

required

The currency of the product, represented by an ISO 4217 currency code. See currencies for a list of supported currencies.

Example:

"USD"

state

enum<string>

required

The current state of the product.

Available options:

LIVE,

TEMPORARILY_DISABLED,

TEMPORARILY_DEGRADED

Example:

"LIVE"

is_orderable

boolean

required

Indicates whether or not you are able to order the product. You should use this detail to determine whether or not to display the product to your end users.

We recommend that you only display products to customers when this field is true - we will reject any orders placed for products where this is false. You can filter by is_orderable to only return products that can be ordered in the list endpoint.

payout_type

enum<string>

required

The type of payout - this field will tell you the key of the additional object details that correspond to each payout type. The types currently supported are gift_card, subscription, or payment. Your implementation should account for additional payout types being addedin the future.

Available options:

gift_card,

subscription,

payment

categories

string[]

required

List of the categories that the product belongs to. You can fetch the list of categories using the GET /product/categories endpoint.

Example:

["food-and-drink", "entertainment"]

countries_redeemable_in

string[]

required

Countries where the payout can be spent.

ISO 3166 ALPHA-2 country code

Example:

["US"]

customer_service

object

required

Contact information for customer service related to the product. Suitable for displaying to the customer.

Show child attributes

customer_service.phone_number

string | null

The customer service phone number.

Example:

"+1234567890"

customer_service.website_url

string<uri> | null

The customer service website URL.

Example:

"https://merchant.example.com/customer-service"

discount_multiplier

string

required

The discount multiplier used when ordering. 0 means no discount and 0.1 means 10% discount. The discount is applied on the price of the order item before any fees are applied.

Example:

"0.05"

availability

enum<string>

The availability type of the product.

Available options:

stocked,

realtime

Example:

"realtime"

gift_card

object

Specific details about the gift card product, only populated when the payout_type is gift_card.

Show child attributes

gift_card.assets

Product assets · object

Graphical assets for the product, including card image, icon image, and primary color.

Show child attributes

gift_card.assets.card_image_url

string<uri> | null

Example:

"https://gift.runa.io/static/product_assets/XYZ-US/XYZ-US-card.png"

gift_card.assets.icon_image_url

string<uri> | null

Example:

"https://gift.runa.io/static/product_assets/XYZ-US/XYZ-US-icon.png"

gift_card.assets.primary_color

string | null

Example:

"#000000"

gift_card.balance_check_url

string<uri> | null

URL to check the gift card balance. This will be a provider specific URL that a consumer can use to check the balance of the gift card.

Example:

"https://merchant.example.com/balance-check"

gift_card.content_resources

URL · object

Content resources provide additional information about the product, including:

Product description
Disclaimers
Refund policy
Reissuance policy
Terms and conditions
Redemption instructions

This content can be returned in different formats based on the content query parameter in the get product endpoint. The list endpoint only supports returning content as URLs.

Content fields will be present when content is available, and null when content has been removed. We update content periodically - if content has been removed, requests will return a 403 or 404 error. Your implementation should handle these errors gracefully.

URL
Markdown
HTML

Show child attributes

gift_card.content_resources.description_markdown_url

string<uri>

required

A URL pointing to a markdown file that contains the description of the resource.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/description.md"

gift_card.content_resources.disclaimer_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that contains the disclaimer information.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/disclaimer_markdown.md"

gift_card.content_resources.refund_policy_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that outlines the refund policy, if applicable.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/refund_policy_markdown.md"

gift_card.content_resources.reissuance_policy_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that details the reissuance policy for the resource.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/reissuance_policy_markdown.md"

gift_card.content_resources.terms_buyer_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that contains the terms and conditions applicable to buyers.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/terms_buyer.md"

gift_card.content_resources.terms_consumer_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that contains the terms and conditions applicable to consumers.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/terms_consumer.md"

gift_card.content_resources.redemption_instructions_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that provides instructions for redeeming the resource.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/redeem_markdown.md"

gift_card.content_resources.locale

string

required

What locale the content resources are in. This is an IETF language tag using an underscore to separate the language and country codes.

Example:

"en_US"

gift_card.expiry

object

Show child attributes

gift_card.expiry.date_policy

string | null

Text description of the policy, suitable for displaying to the customer.

Example:

"Expires 2 years from issue date"

gift_card.expiry.in_months

integer

Specifies the number of months until the gift expires.

Example:

12

gift_card.expiry.type

enum<string>

The type of expiry policy.

Type	Description
`from-last-use`	The expiration period starts after the gift is used for a purchase.
`from-last-balance-check`	The expiration period starts after the gift balance is checked using phone or online tools.
`from-issue-date`	The expiration period starts from the date the gift was purchased.
`indefinite`	The gift card does not expire and remains valid indefinitely.
`do-not-show`	No expiration information is displayed.

Available options:

from-last-use,

from-last-balance-check,

from-issue-date,

indefinite,

do-not-show

Example:

"from-issue-date"

gift_card.redeemable_at

enum<string>

Defines where the gift card can be redeemed. Options are all for both online and in-store, in-store for in-store only, and online for online only.

Available options:

all,

online,

in-store

Example:

"all"

gift_card.website_url

string<uri> | null

The URL of the website for the product. This is the URL that a consumer can use to either redeem the payout or view details about where they can redeem the payout.

Example:

"https://merchant.example.com"

gift_card.barcode_format

enum<string> | null

The barcode format of the product.

Available options:

code-128,

code-39,

QR,

ean-13,

pdf417,

ITF,

DATA_MATRIX,

other

Example:

"code-128"

gift_card.e_code_usage_type

enum<string>

The e-code usage type of the product.

Available options:

undefined,

url-recommended,

url-only

Example:

"url-only"

gift_card.denominations

object

Defines the denomination options available for the product, including ranges and types.

Show child attributes

gift_card.denominations.type

enum<string>

The type of denomination. Can be open or fixed. open is any amount between minimum and maximum value. Fixed is limited to those returned in the available_list.

Available options:

open,

fixed

Example:

"fixed"

gift_card.denominations.minimum_value

string<decimal>

The minimum denomination value available for the product.

Example:

"10.00"

gift_card.denominations.maximum_value

string<decimal>

The maximum denomination value available for the product.

Example:

"100.00"

gift_card.denominations.available_list

string<decimal>[] | null

A list of available denominations for the product. Will be null if the type is OPEN.

Example:

["10.00", "20.00", "50.00", "100.00"]

subscription

object

Details about the subscription product, only populated when the payout_type is subscription.

Show child attributes

subscription.assets

Product assets · object

Graphical assets for the product, including card image, icon image, and primary color.

Show child attributes

subscription.assets.card_image_url

string<uri> | null

Example:

"https://gift.runa.io/static/product_assets/XYZ-US/XYZ-US-card.png"

subscription.assets.icon_image_url

string<uri> | null

Example:

"https://gift.runa.io/static/product_assets/XYZ-US/XYZ-US-icon.png"

subscription.assets.primary_color

string | null

Example:

"#000000"

subscription.balance_check_url

string<uri> | null

URL to check the gift card balance. This will be a provider specific URL that a consumer can use to check the balance of the gift card.

Example:

"https://merchant.example.com/balance-check"

subscription.content_resources

URL · object

Content resources provide additional information about the product, including:

Product description
Disclaimers
Refund policy
Reissuance policy
Terms and conditions
Redemption instructions

This content can be returned in different formats based on the content query parameter in the get product endpoint. The list endpoint only supports returning content as URLs.

URL
Markdown
HTML

Show child attributes

subscription.content_resources.description_markdown_url

string<uri>

required

A URL pointing to a markdown file that contains the description of the resource.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/description.md"

subscription.content_resources.disclaimer_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that contains the disclaimer information.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/disclaimer_markdown.md"

subscription.content_resources.refund_policy_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that outlines the refund policy, if applicable.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/refund_policy_markdown.md"

subscription.content_resources.reissuance_policy_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that details the reissuance policy for the resource.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/reissuance_policy_markdown.md"

subscription.content_resources.terms_buyer_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that contains the terms and conditions applicable to buyers.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/terms_buyer.md"

subscription.content_resources.terms_consumer_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that contains the terms and conditions applicable to consumers.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/terms_consumer.md"

subscription.content_resources.redemption_instructions_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that provides instructions for redeeming the resource.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/redeem_markdown.md"

subscription.content_resources.locale

string

required

What locale the content resources are in. This is an IETF language tag using an underscore to separate the language and country codes.

Example:

"en_US"

subscription.expiry

object

Show child attributes

subscription.expiry.date_policy

string | null

Text description of the policy, suitable for displaying to the customer.

Example:

"Expires 2 years from issue date"

subscription.expiry.in_months

integer

Specifies the number of months until the gift expires.

Example:

12

subscription.expiry.type

enum<string>

The type of expiry policy.

Type	Description
`from-last-use`	The expiration period starts after the gift is used for a purchase.
`from-last-balance-check`	The expiration period starts after the gift balance is checked using phone or online tools.
`from-issue-date`	The expiration period starts from the date the gift was purchased.
`indefinite`	The gift card does not expire and remains valid indefinitely.
`do-not-show`	No expiration information is displayed.

Available options:

from-last-use,

from-last-balance-check,

from-issue-date,

indefinite,

do-not-show

Example:

"from-issue-date"

subscription.redeemable_at

enum<string>

Defines where the gift card can be redeemed. Options are all for both online and in-store, in-store for in-store only, and online for online only.

Available options:

all,

online,

in-store

Example:

"all"

subscription.website_url

string<uri> | null

The URL of the website for the product. This is the URL that a consumer can use to either redeem the payout or view details about where they can redeem the payout.

Example:

"https://merchant.example.com"

subscription.barcode_format

enum<string> | null

The barcode format of the product.

Available options:

code-128,

code-39,

QR,

ean-13,

pdf417,

ITF,

DATA_MATRIX,

other

Example:

"code-128"

subscription.e_code_usage_type

enum<string>

The e-code usage type of the product.

Available options:

undefined,

url-recommended,

url-only

Example:

"url-only"

subscription.subscription_plans

object[]

A list of subscription plans available for the product. You must use the subscription_plan_code when ordering a subscription plan, not the top-level code.

Show child attributes

subscription.subscription_plans.length_unit

enum<string>

The unit of time for the subscription plan. Currently DAYS and MONTHS are supported.

Available options:

DAYS,

MONTHS

Example:

"MONTHS"

subscription.subscription_plans.length

integer

The length of the subscription plan using the length_unit.

Example:

12

subscription.subscription_plans.name

string

The name of the subscription plan.

Example:

"3 month subscription"

subscription.subscription_plans.price

string<decimal>

The price of the subscription plan.

Example:

"10.00"

subscription.subscription_plans.subscription_plan_code

string

Use this code during order creation, rather than the top level code.

Example:

"XYZ-US-SUB-1"

payment

object

Details about the payment product, only populated when the payout_type is payment.

Show child attributes

payment.assets

object

required

Show child attributes

payment.assets.icon_image_url

string<uri>

required

The URL of the icon image for the product.

Example:

"https://gift.runa.io/static/product_assets/XYZ-US/XYZ-US-icon.png"

payment.assets.primary_color

string

required

The primary color of the product.

Example:

"#000000"

payment.denominations

object

required

Show child attributes

payment.denominations.minimum_value

string<decimal>

required

The minimum denomination value available for the product.

Example:

"10.00"

payment.denominations.maximum_value

string<decimal>

required

The maximum denomination value available for the product.

Example:

"100.00"

payment.content_resources

URL · object

Content resources provide additional information about the product, including:

Product description
Disclaimers
Refund policy
Reissuance policy
Terms and conditions
Redemption instructions

This content can be returned in different formats based on the content query parameter in the get product endpoint. The list endpoint only supports returning content as URLs.

URL
Markdown
HTML

Show child attributes

payment.content_resources.description_markdown_url

string<uri>

required

A URL pointing to a markdown file that contains the description of the resource.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/description.md"

payment.content_resources.disclaimer_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that contains the disclaimer information.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/disclaimer_markdown.md"

payment.content_resources.refund_policy_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that outlines the refund policy, if applicable.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/refund_policy_markdown.md"

payment.content_resources.reissuance_policy_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that details the reissuance policy for the resource.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/reissuance_policy_markdown.md"

payment.content_resources.terms_buyer_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that contains the terms and conditions applicable to buyers.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/terms_buyer.md"

payment.content_resources.terms_consumer_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that contains the terms and conditions applicable to consumers.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/terms_consumer.md"

payment.content_resources.redemption_instructions_markdown_url

string<uri> | null

required

A URL pointing to a markdown file that provides instructions for redeeming the resource.

Example:

"https://d2abcdef.cloudfront.net/resources/XYZ-US/redeem_markdown.md"

payment.content_resources.locale

string

required

What locale the content resources are in. This is an IETF language tag using an underscore to separate the language and country codes.

Example:

"en_US"

Reference

Orders

Products

Balance

Utility

Webhooks

Need help with the product catalog?

Authorizations

Headers

Path Parameters

Query Parameters

Response