> ## 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.
# API Updates
> Changelog of all major API updates, new features, removals, and improvements.
## Removed support for Bulgarian Lev (BGN)
Following Bulgaria's move to adopt the Euro **(1 January 2026)**, we have removed FX support for BGN. Please refer to the Currencies [API reference](/reference/currencies) to view our currency support for top ups and FX.
All affected customers were notified ahead of time and any remaining balance have been converted automatically to `EUR`.
## 2023-07-27 API version end-of-life
As of **14 November 2025** the **2023-07-27** version of the API is no longer available.
All affected customers were notified ahead of time. As of today requests for the specific version using the `X-Api-Version` header will respond with a `410 Gone` error code. Requests without this header will default to the current API version.
## New metadata field added to ordering endpoint
We've added a new `metadata` field to the ordering endpoint. You can use this field to attach additional, customer-specific data to the order. This is for your internal use, the information stored here will not be exposed to the end user.
When you query for an order we will return the metadata you have attached to the order.
We support up to 20 key-value pairs, keys have a maximum length of 40 characters, and values can be up to 200 characters long. Both keys and values must be strings.
Check out the [order create reference](/reference/2024-02-05/endpoint/orders/create#body-metadata) for more details.
### Example
Let's say you're placing orders for a campaign. You could attach several key-value pairs to the order to map the Runa order to your internal order ID, which department is running the campaign, and which campaign the order belongs to.
```json theme={null}
"metadata": {
"internal_id": "12345",
"department": "marketing",
"campaign": "summer_2024"
}
```
## Order Estimate now supports Embedded FX orders
We are glad to announce that you can use the `POST /v2/order/estimate` endpoint to get the price estimate for an Embedded FX order.
Please refer to the Order Estimate [API reference](/reference/2024-02-05/endpoint/orders/estimate) the request and response for details.
More examples can also be found in the [Embedded FX guide](/features/embedded-fx).
## Filtering the product catalog by category
We have introduced two new features to enhance how you work with product categories in the API.
### Filter products by category
The [List products](/reference/2024-02-05/endpoint/products/list) endpoint now supports a `categories` query string parameter. You can use this to filter the product catalog by one or more categories. To specify multiple categories, repeat the parameter for each category, e.g. `?categories=fashion&categories=department-stores`.
### List all available categories
Filtering needs knowledge of the available categories. You can now fetch the full list of product categories supported by the API using the [List categories](/reference/2024-02-05/endpoint/products/categories) endpoint making it easier to build dynamic category selectors or validate category names.
## New payment payout type added
To support the release of [Runa Push to Card](https://runa.io/products/push-to-card) a new payout type of `payment` has been added to the product catalog. This new type joins the existing types of `gift_card` and `subscription`. For `payment` type products the new `payment` key will contain specific details about the product.
[Runa Push to Card](https://runa.io/products/push-to-card) enables you to push funds to global cards and bank accounts instantly. Funds can be sent instantly to billions of users in 190 countries, powered by Visa Direct and Mastercard. Existing customers should contact their account manager for more details.
### Updated endpoints
* [Retrieve products](/reference/2024-02-05/endpoint/products/list)
* When `payout_type` is `payment` the `payment` key will contain specific details about the products assets, denominations and resources.
* [Retrieve a single product's details](/reference/2024-02-05/endpoint/products/get)
* When `payout_type` is `payment` the `payment` key will contain specific details about the products assets, denominations and resources.
## 2023-01-16 API version end-of-life
As of **31 January 2025** the **2023-01-16** version of the API is no longer available.
Our new API versions have improved reliability and performance, plus additional features such as embedded foreign exchange at time of ordering.
All affected customers were notified ahead of time. As of today requests for the specific version using the `X-Api-Version` header will respond with a `410 Gone` error code. Requests without this header will default to the current API version.
For more details on our versioning strategy see the [API versioning](/best-practices/api-versioning) page.
## Product orderable state now supported in the Product Update webhook
You can now receive programmatic real-time updates to the availability of products, the `is_orderable` field is now a supported field in the [Product Update webhook](/reference/2024-02-05/webhook/product.update).
### Use cases
* Updating a local replica or cache of product availability. If you keep a copy of your product catalog the availability of products could become out of sync. Using the product update webhook you can update this copy in real-time ensuring your customers don't face ordering issues for unavailable products.
* Getting live quicker with new products and products awaiting approval. The moment a product is ready for you to use the webhook will let you know.
* Notifying your customers of the availability of products in the Runa network.
### Example
The webhook sends you both the previous and the new state of the product so you can take action on what has changed. Note here the product has gone from unorderable to orderable.
```json theme={null}
{
"product_code": "PRCODE-GB",
"old_state": {
"price_multiplier": "0.9",
"is_orderable": false
},
"new_state": {
"price_multiplier": "0.8",
"is_orderable": true
},
"timestamp": "2024-04-10T17:11:26.601254"
}
```
Check the [Product Update webhook reference](/reference/2024-02-05/webhook/product.update) for full details.
### Getting started with webhooks
If you're not already using webhooks to receive real-time updates from Runa about the product catalog or the state of orders you can [read about getting started here](/reference/webhooks).
## Additional currencies supported for Embedded FX
We're happy to announce ten new currencies are now supported for embedded FX orders, bringing the total number to 31. You can use the [embedded FX](/features/embedded-fx) feature to seamlessly pay for orders across different countries all from your preferred currency balance.
Do note these new currencies only support orders where **USD** is the source of funds.
| ISO 4217 Code | Currency Name | Embedded FX Supported |
| ------------- | -------------------- | --------------------- |
| AED | Arab Emirates Dirham | ✅ *from USD only* |
| ARS | Argentine Peso | ✅ *from USD only* |
| BGN | Bulgarian Lev | ✅ *from USD only* |
| BRL | Brazilian Real | ✅ *from USD only* |
| CLP | Chielan Peso | ✅ *from USD only* |
| COP | Colombian Peso | ✅ *from USD only* |
| INR | Indian Rupee | ✅ *from USD only* |
| MYR | Malaysian Ringgit | ✅ *from USD only* |
| PEN | Peruvian Sol | ✅ *from USD only* |
| SAR | Saudi Riyal | ✅ *from USD only* |
For the full listing of what we support see the [currencies documentation page](/reference/currencies).
## Embedded FX is now available on Production
Introducing Embedded FX! It allows you to top up your balance in your preferred currency and seamlessly pay for orders across different countries.
You can view more on how to use this new feature in [our guide](/features/embedded-fx)
### Changes
* Relaxed rule: Payment method currency can now differ from the country/currency of the payout link.
* This change applies exclusively to single-item sync orders.
* Additional properties from `POST /v2/order` in sync mode and `GET /v2/order/{orderId}` will be returned for all orders (`order.items[n].currency` and `order.transaction_detail`)
## Embedded FX is now available on Playground
Introducing Embedded FX! This is currently a preview for playground only. It allows you to top up your balance in your preferred currency and seamlessly pay for orders across different countries.
You can view more on how to use this new feature in [our guide](/features/embedded-fx)
### Changes
* Relaxed rule: Payment method currency can now differ from the country/currency of the payout link.
* This change applies exclusively to single-item orders and currently only in playground.
* This addition allows for testing and development in preparation for embedded FX orders in production
* Additional properties from `POST /v2/order` in sync mode and `GET /v2/order/{orderId}` will be returned for all orders (`order.items[n].currency` and `order.subtotal`)
## API version 2024-02-05 released
* Changes to product listing: This version improves the product listing endpoint to return a more complete response, allowing for filtering by different parameter
* Addition of a new endpoint: This version includes a new endpoint you can use to return the currently supported countries.
We are excited about these updates and look forward to hearing your feedback. As always, please refer to the updated API documentation for detailed information and guidance on how to implement these changes in your applications.
### Impacted endpoints
* **GET /v2/product**
* **GET /v2/product/countries**
### Changes
* **New Request Structure for Product Listing retrieval**
* The following query parameters are now allowed:
* `is_orderable`: Only return products that can be ordered. So if a product has been disabled, it will not be returned
* `code`: Retrieve a single product's details
* `countries_redeemable_in`: Filter by all the countries that this product can be redeemed in
* Pagination has been added with:
* `after`: A cursor for use in pagination to return the next set of products. The before and after cursors are mutually exclusive (you can't use them at the same time).
* `before`: A cursor for use in pagination to return the previous set of products. The before and after cursors are mutually exclusive (you can't use them at the same time).
* `limit`: A limit on the number of items to be returned.
* You no longer need to pass in a mandatory country code
* **New Response structure for Product Listing retrieval**
* Only Returns products that have been Approved.
* Returns `categories` that the product belongs to
* Includes Expiry and Redemption instructions as sub-objects within each item
* Removal of `redemption_url` field in order responses, it is replaced by the `payout` field.
* This field was deprecated in 2023-07-27. It should now be treated as removed.
## API verion 2023-07-27 released
* Changes to request and response for Order operations: This version includes significant updates to the request and response mechanisms for creating, retrieving, and listing orders. Please refer to the updated API documentation for new structures and fields.
* Removal of Get Links operation: To streamline our API and improve efficiency, we have removed the 'get links' operation previously used to retrieve payout links of an order. This change reduces the required API calls to place and retrieve a payout link order from three to two.
* New Payment Method: As part of our ongoing effort to enhance user experience, we are now enabling payment with account balance on the Runa API. This new feature adds to our existing payment methods, providing more flexibility and convenience for our users.
* Product Selection Flexibility: We have modified our product selection feature to allow item-specific product selection. Previously, product selection applied to the entire order, but now it can be specified per item. This change provides you with greater flexibility and control over your orders.
We are excited about these updates and look forward to hearing your feedback. As always, please refer to the updated API documentation for detailed information and guidance on how to implement these changes in your applications.
### Impacted endpoints
* **POST /v2/order**
* **GET /v2/order/\{id}**
* **GET /v2/order**
* **GET /v2/order/\{id}/links**
### Changes
* **Added new fields to the create order API request**
* Payment method can be defined:
* `payment_method.type` which can be set to `CARD` or `ACCOUNT_BALANCE`
* `payment_method.card_id`
* `payment_method.currency` which supports `EUR`, `GBP`, `USD`, and `CAD`
* Distribution method can be defined in item level:
* `items.distribution_method.type` which can be set to `EMAIL` or `PAYOUT_LINK`
* `items.distribution_method.email_address`
* Products can be defined on item level, now every payout link in the order can contain different product selections:
* `items.products.type` which can be set to `SINGLE` or `MULTIPLE`
* `items.products.value`
* `items.products.values`
* **Removed fields from the create order API request**
* `products`
* `idempotency_key`
* `items.country`
* **Added new headers to the create order API**
* `x-api-version`
* `x-idempotency-key`
* **Added new fields from the create order API response**
* `status` which is either `COMPLETED`, `PROCESSING` or `FAILED`
* **Removed all order details fields from the create order API response**
* **Added new get order API response models**
* For a complete order the response will contain all the order details.
* `status`
* `completed_at`
* `redemption_url`
* `payment_method.type` which can be set to `CARD` or `ACCOUNT_BALANCE`
* `payment_method.card_id`
* `payment_method.currency` which supports `EUR`, `GBP`, `USD`, and `CAD`
* `items.distribution_method.type` which can be set to `EMAIL` or `PAYOUT_LINK`
* `items.distribution_method.email_address`
* `items.products.type` which can be set to `SINGLE` or `MULTIPLE`
* `items.products.value`
* `items.products.values`
* For an incomplete order the response will contain
* `status`
* `id`
* `message`
* **Added new headers to the get order API**
* `x-api-version`
* **Removed fields from get order API response**
* `is_complete`
* `countries`
* `initial_values` object
* `final_values` object
* `product_count`
* `items.order_id`
* `items.discount_multiplier`
* `items.delivery_email`
* `items.current_token`
* `tokens` object
* The above changes in the get order API response are also reflected in the list order API. The API is still paginated and contains query parameters to control the cursor:
* `limit`
* `before`
* `after`
* **Added new headers to the list order API**
* `x-api-version`
* **Removed the GET /v2/order/\{id}/links endpoint**
* This API is replaced by adding the `redemption_url` to the items in the response of `GET /v2/order/{id}`
* **Added new headers to the list products API**
* `x-api-version`