> ## Documentation Index > Fetch the complete documentation index at: https://developer.runa.io/llms.txt > Use this file to discover all available pages before exploring further. # List products > List all products in your catalog Lists all products available for ordering in a paginated response. You can filter the products by country and category. 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. We have a guide to help you get started with the product catalog, including how to filter the catalog and the different payout types. ## OpenAPI ````yaml reference/2024-02-05/openapi.json GET /product openapi: 3.1.1 info: title: Runa version: '2.0' description: The public Runa API license: name: Ⓒ Runa url: https://runa.io/terms-of-use contact: name: Runa url: https://runa.io email: info@runa.io servers: - url: https://playground.runa.io/v2 description: Playground - url: https://api.runa.io/v2 description: Production security: - ApiKeyAuth: [] tags: - name: utility description: Utility endpoints. - name: balance description: Operations related to account balance. - name: products description: Operations related to products. - name: orders description: Operations related to ordering and orders. externalDocs: url: https://developer.runa.com/reference description: Runa API Reference paths: /product: get: tags: - products summary: List products description: List all products in your catalog operationId: getProducts parameters: - $ref: '#/components/parameters/X-Api-Version' - in: query name: is_orderable description: >- Filter by products which can be ordered. If `true`, returns only those which can be ordered, if `false`, returns all products. schema: type: boolean - in: query name: countries_redeemable_in schema: type: array items: type: string pattern: ^[A-Z]{2}$ description: ISO 3166 ALPHA-2 country code description: >- Filter by countries where a product can be redeemed in. To specify multiple countries repeat the parameter for each country, e.g. `?countries_redeemable_in=US&countries_redeemable_in=GB`. You can pull the list of supported countries from the [list countries](/reference/2024-02-05/endpoint/products/countries) endpoint. - in: query name: categories schema: type: array items: type: string description: Product category name description: >- Filter by product categories. To specify multiple categories repeat the parameter for each category, e.g. `?categories=fashion&categories=department-stores`. You can pull the list of categories from the [list categories](/reference/2024-02-05/endpoint/products/categories) endpoint. - $ref: '#/components/parameters/BeforeCursor' - $ref: '#/components/parameters/AfterCursor' - in: query name: limit description: >- A limit on the number of items to be returned. See [pagination](/reference/pagination) for more information on how to use this parameter. schema: type: integer default: 500 minimum: 1 maximum: 500 responses: '200': description: List of products in your catalog content: application/json: schema: type: object properties: catalog: type: array items: $ref: '#/components/schemas/Product' pagination: $ref: '#/components/schemas/PageableMeta' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: parameters: X-Api-Version: name: X-Api-Version description: >- The dated version of the API, if not specified a default is used. See [API versioning](/best-practices/api-versioning) for more information. in: header required: false schema: type: string BeforeCursor: name: before description: >- A cursor for use in pagination to return the previous set of results. The before and after cursors are mutually exclusive (you can't use them at the same time). You can get a value from the `pagination.cursors.before` field in the response. See [pagination](/reference/pagination) for more information. in: query schema: type: string example: A-123 AfterCursor: name: after description: >- A cursor for use in pagination to return the next set of results. The before and after cursors are mutually exclusive (you can't use them at the same time). You can get a value from the `pagination.cursors.after` field in the response. See [pagination](/reference/pagination) for more information. in: query schema: type: string example: A-789 schemas: Product: type: object description: Product details properties: name: type: string description: The name of the product. example: Example Merchant code: type: string description: >- 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: type: string pattern: ^[A-Z]{3}$ description: >- The currency of the product, represented by an ISO 4217 currency code. See [currencies](/reference/currencies) for a list of supported currencies. example: USD state: type: string enum: - LIVE - TEMPORARILY_DISABLED - TEMPORARILY_DEGRADED description: The current state of the product. example: LIVE is_orderable: $ref: '#/components/schemas/ProductIsOrderable' payout_type: type: string enum: - gift_card - subscription - payment description: >- 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. categories: type: array items: type: string description: >- List of the categories that the product belongs to. You can fetch the list of categories using the [`GET /product/categories` endpoint](/reference/2024-02-05/endpoint/products/categories). example: - food-and-drink - entertainment countries_redeemable_in: type: array items: type: string pattern: ^[A-Z]{2}$ description: ISO 3166 ALPHA-2 country code description: Countries where the payout can be spent. example: - US customer_service: $ref: '#/components/schemas/ProductCustomerService' discount_multiplier: $ref: '#/components/schemas/ProductDiscountMultiplier' availability: type: string enum: - stocked - realtime description: The availability type of the product. example: realtime gift_card: description: >- Specific details about the gift card product, only populated when the `payout_type` is `gift_card`. allOf: - $ref: '#/components/schemas/PayoutTypeDetailsBase' - type: object properties: denominations: $ref: '#/components/schemas/ProductDenominations' subscription: description: >- Details about the subscription product, only populated when the `payout_type` is `subscription`. allOf: - $ref: '#/components/schemas/PayoutTypeDetailsBase' - type: object properties: subscription_plans: description: >- 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`. type: array items: $ref: '#/components/schemas/ProductSubscriptionPlan' payment: description: >- Details about the payment product, only populated when the `payout_type` is `payment`. allOf: - $ref: '#/components/schemas/ProductPayment' required: - categories - code - countries_redeemable_in - currency - customer_service - discount_multiplier - name - state - is_orderable - payout_type PageableMeta: title: PageableMeta required: - cursors - page type: object description: >- Information about the page of results returned. See [pagination](/reference/pagination) for more information on how to page through results. properties: cursors: title: Cursors description: >- Pagination cursors, use the `after` cursor to page forward and the `before` cursor to page backward. allOf: - $ref: '#/components/schemas/PageCursors' page: title: Page description: Extra information about the current page. allOf: - $ref: '#/components/schemas/Page' ProductIsOrderable: type: boolean description: >- 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. ProductCustomerService: type: object description: >- Contact information for customer service related to the product. Suitable for displaying to the customer. properties: phone_number: type: string nullable: true description: The customer service phone number. example: '+1234567890' website_url: type: string nullable: true format: uri description: The customer service website URL. example: https://merchant.example.com/customer-service ProductDiscountMultiplier: type: string pattern: ^[0-9]+\.[0-9]{2}$ description: >- 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' PayoutTypeDetailsBase: type: object properties: assets: $ref: '#/components/schemas/ProductAssets' balance_check_url: type: string nullable: true format: uri description: >- 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 content_resources: $ref: '#/components/schemas/ContentResources' expiry: $ref: '#/components/schemas/ProductExpiry' redeemable_at: description: >- 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. type: string enum: - all - online - in-store example: all website_url: description: >- 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. type: string format: uri nullable: true example: https://merchant.example.com barcode_format: type: string enum: - code-128 - code-39 - QR - ean-13 - pdf417 - ITF - DATA_MATRIX - other nullable: true description: The barcode format of the product. example: code-128 e_code_usage_type: type: string enum: - undefined - url-recommended - url-only description: The e-code usage type of the product. example: url-only ProductDenominations: type: object description: >- Defines the denomination options available for the product, including ranges and types. properties: type: type: string enum: - open - fixed description: >- 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`. example: fixed minimum_value: $ref: '#/components/schemas/ProductMinimumValue' maximum_value: $ref: '#/components/schemas/ProductMaximumValue' available_list: type: array items: type: string format: decimal nullable: true description: >- 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' ProductSubscriptionPlan: type: object properties: length_unit: description: >- The unit of time for the subscription plan. Currently `DAYS` and `MONTHS` are supported. type: string enum: - DAYS - MONTHS example: MONTHS length: type: integer description: The length of the subscription plan using the `length_unit`. example: 12 name: type: string description: The name of the subscription plan. example: 3 month subscription price: type: string format: decimal description: The price of the subscription plan. example: '10.00' subscription_plan_code: description: >- Use this code during order creation, rather than the top level `code`. type: string example: XYZ-US-SUB-1 ProductPayment: type: object properties: assets: type: object required: - icon_image_url - primary_color properties: icon_image_url: $ref: '#/components/schemas/ProductIconImageUrl' primary_color: $ref: '#/components/schemas/ProductPrimaryColor' denominations: type: object required: - minimum_value - maximum_value properties: minimum_value: $ref: '#/components/schemas/ProductMinimumValue' maximum_value: $ref: '#/components/schemas/ProductMaximumValue' content_resources: $ref: '#/components/schemas/ContentResources' required: - assets - denominations PageCursors: title: PageCursors type: object properties: after: title: After description: Cursor to query the next page. example: A-789 type: string before: title: Before description: Cursor to query the previous page. example: A-123 type: string Page: title: Page type: object properties: limit: title: Limit description: How many records the current page is limited to. example: 100 type: integer APIErrorResponse: title: APIErrorResponse required: - type - message type: object properties: type: title: Type description: An error code or type. type: string example: not-found message: title: Message description: A human readable summary of the error. type: string example: The requested resource was not found help: title: Help description: Additional information that pertains to the error. type: string example: Please check the resource ID and try again. description: Generic Runa API error response. ProductAssets: title: Product assets description: >- Graphical assets for the product, including card image, icon image, and primary color. type: object properties: card_image_url: type: string format: uri nullable: true example: https://gift.runa.io/static/product_assets/XYZ-US/XYZ-US-card.png icon_image_url: type: string format: uri nullable: true example: https://gift.runa.io/static/product_assets/XYZ-US/XYZ-US-icon.png primary_color: type: string pattern: ^#[0-9A-Fa-f]{6}$ nullable: true example: '#000000' ContentResources: title: Content resources description: >- 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](/reference/2024-02-05/endpoint/products/get#parameter-content). 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. oneOf: - $ref: '#/components/schemas/ContentResourcesUrl' - $ref: '#/components/schemas/ContentResourcesMarkdown' - $ref: '#/components/schemas/ContentResourcesHTML' ProductExpiry: type: object properties: date_policy: type: string nullable: true description: >- Text description of the policy, suitable for displaying to the customer. example: Expires 2 years from issue date in_months: type: integer description: Specifies the number of months until the gift expires. example: 12 type: type: string description: |- 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. | enum: - from-last-use - from-last-balance-check - from-issue-date - indefinite - do-not-show example: from-issue-date ProductMinimumValue: type: string format: decimal description: The minimum denomination value available for the product. example: '10.00' ProductMaximumValue: type: string format: decimal description: The maximum denomination value available for the product. example: '100.00' ProductIconImageUrl: type: string format: uri description: The URL of the icon image for the product. example: https://gift.runa.io/static/product_assets/XYZ-US/XYZ-US-icon.png ProductPrimaryColor: type: string pattern: ^#[0-9A-Fa-f]{6}$ description: The primary color of the product. example: '#000000' ContentResourcesUrl: title: URL description: Content resources in URL format. type: object required: - description_markdown_url - disclaimer_markdown_url - refund_policy_markdown_url - reissuance_policy_markdown_url - terms_buyer_markdown_url - terms_consumer_markdown_url - redemption_instructions_markdown_url - locale properties: description_markdown_url: type: string format: uri nullable: false description: >- A URL pointing to a markdown file that contains the description of the resource. example: https://d2abcdef.cloudfront.net/resources/XYZ-US/description.md disclaimer_markdown_url: type: string format: uri nullable: true description: >- A URL pointing to a markdown file that contains the disclaimer information. example: >- https://d2abcdef.cloudfront.net/resources/XYZ-US/disclaimer_markdown.md refund_policy_markdown_url: type: string format: uri nullable: true description: >- 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 reissuance_policy_markdown_url: type: string format: uri nullable: true description: >- 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 terms_buyer_markdown_url: type: string format: uri nullable: true description: >- 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 terms_consumer_markdown_url: type: string format: uri nullable: true description: >- 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 redemption_instructions_markdown_url: type: string format: uri nullable: true description: >- 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 locale: $ref: '#/components/schemas/ContentResourcesLocale' ContentResourcesMarkdown: title: Markdown description: Content resources in Markdown format. type: object required: - description_md - disclaimer_md - refund_policy_md - reissuance_policy_md - terms_buyer_md - terms_consumer_md - redemption_instructions_md - locale properties: description_md: type: string description: Markdown content for the resource description. nullable: false disclaimer_md: type: string nullable: true description: Markdown content for the disclaimer information. refund_policy_md: type: string nullable: true description: Markdown content outlining the refund policy, if applicable. reissuance_policy_md: type: string nullable: true description: Markdown content detailing the reissuance policy for the resource. terms_buyer_md: type: string nullable: true description: >- Markdown content containing terms and conditions applicable to buyers. terms_consumer_md: type: string nullable: true description: >- Markdown content containing terms and conditions applicable to consumers. redemption_instructions_md: type: string nullable: true description: Markdown instructions for redeeming the resource. locale: $ref: '#/components/schemas/ContentResourcesLocale' ContentResourcesHTML: title: HTML description: Content resources in HTML format. type: object required: - description_html - disclaimer_html - refund_policy_html - reissuance_policy_html - terms_buyer_html - terms_consumer_html - redemption_instructions_html - locale properties: description_html: type: string format: html nullable: false description: HTML content for the resource description. disclaimer_html: type: string format: html nullable: true description: HTML content for the disclaimer information. refund_policy_html: type: string format: html nullable: true description: HTML content outlining the refund policy, if applicable. reissuance_policy_html: type: string format: html nullable: true description: HTML content detailing the reissuance policy for the resource. terms_buyer_html: type: string format: html nullable: true description: HTML content containing terms and conditions applicable to buyers. terms_consumer_html: type: string format: html nullable: true description: >- HTML content containing terms and conditions applicable to consumers. redemption_instructions_html: type: string format: html nullable: true description: HTML instructions for redeeming the resource. locale: $ref: '#/components/schemas/ContentResourcesLocale' ContentResourcesLocale: type: string description: >- What locale the content resources are in. This is an [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) using an underscore to separate the language and country codes. pattern: ^[a-z]{2}_[A-Z]{2}$ example: en_US responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' NotFound: description: Not found content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key description: >- Your API key. See the [API key](/getting-started/api-key) page on details of how to generate and store your keys. ````