Runa Developer Hub

https://github.com/wegift/api-docs
Admin
The Runa Developer Hub provides comprehensive API documentation, including OpenAPI specifications...
Tokens:45,743
Snippets:142
Trust Score:5.4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Dependencies and Run Local Server

Source: https://github.com/wegift/api-docs/blob/main/README.md

Installs JavaScript packages using `pnpm` and starts a local development server for viewing the documentation. Hot-reloading is supported.

```bash
pnpm install
pnpm dev
```

--------------------------------

### Install Sharp Package for ARM64

Source: https://github.com/wegift/api-docs/blob/main/README.md

Installs the pre-built ARM64 package for the `sharp` module if encountering build errors. This is a workaround for specific environments.

```bash
pnpm add @img/sharp-darwin-arm64 --force
```

--------------------------------

### Subscription Plan Example (JSON)

Source: https://github.com/wegift/api-docs/blob/main/features/product-catalog.mdx

Illustrates the structure of subscription plans, including duration, price, and a unique subscription plan code. This code is essential for ordering specific subscription plans.

```json
{
    "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"
}
```

--------------------------------

### Gift Card Denomination Examples (JSON)

Source: https://github.com/wegift/api-docs/blob/main/features/product-catalog.mdx

Provides examples for both 'open' and 'fixed' denomination types for gift cards. 'Open' denominations include minimum and maximum values, while 'fixed' denominations list available values.

```json
{
    "denominations": {
        "type": "open",
        "minimum_value": "5.00",
        "maximum_value": "250.00",
        "available_list": null
    }
}
```

```json
{
    "denominations": {
        "type": "fixed",
        "minimum_value": "10.00",
        "maximum_value": "100.00",
        "available_list": ["10.00", "20.00", "50.00", "100.00"]
    }
}
```

--------------------------------

### Catalog Pagination Request (HTTP)

Source: https://github.com/wegift/api-docs/blob/main/features/product-catalog.mdx

Demonstrates how to paginate through the product catalog using the 'after' and 'limit' query parameters in an HTTP GET request.

```http
GET /product?after={cursor}&limit=100
```

--------------------------------

### API Key Authentication

Source: https://github.com/wegift/api-docs/blob/main/best-practices/authentication.mdx

This section explains how to authenticate requests using API keys and provides an example.

```APIDOC
## API Key Authentication

### Description

The Runa API uses API keys to authenticate requests. API keys are sent via the `X-Api-Key` header in the request.

### Method

GET, POST, PUT, DELETE (all methods)

### Endpoint

All Runa API endpoints

### Parameters

#### Request Headers

- **X-Api-Key** (string) - Required - Your Runa API key.

### Request Example

```http
GET https://api.runa.io/v2/orders HTTP/2
X-Api-Key: YOUR_API_KEY
```

### Response

#### Success Response (200)

- **(response varies by endpoint)**

#### Response Example

```json
{
  "example": "response body"
}
```
```

--------------------------------

### Get Specific Product Details

Source: https://github.com/wegift/api-docs/blob/main/features/product-catalog.mdx

Fetch the details of an individual product using its unique code.

```APIDOC
## GET /reference/2024-02-05/endpoint/products/get

### Description
Retrieves the details for a specific product using its `code`.

### Method
GET

### Endpoint
/reference/2024-02-05/endpoint/products/get

### Parameters
#### Query Parameters
- **code** (string) - Required - The unique code identifying the product.

### Request Example
```json
{
  "query": {
    "code": "EXAMPLE-PRODUCT-1"
  }
}
```

### Response
#### Success Response (200)
- **code** (string) - A unique code identifying the product. Use this code when placing an order.
- **is_orderable** (boolean) - Indicates whether a product can be ordered.
- **currency** (string) - The currency of the product, represented by an ISO 4217 currency code.
- **countries_redeemable_in** (string[]) - The countries in which the product can be redeemed.

#### Response Example
```json
{
  "code": "EXAMPLE-PRODUCT-1",
  "is_orderable": true,
  "currency": "USD",
  "countries_redeemable_in": ["US", "CA"]
}
```
```

--------------------------------

### Order Estimation API

Source: https://github.com/wegift/api-docs/blob/main/features/embedded-fx.mdx

This section provides an example of how to get the estimate of an order with embedded FX. It includes a sample request body and the corresponding success response.

```APIDOC
## POST /orders/estimate

### Description
Estimates the cost of an order, including embedded foreign exchange rates and fees.

### Method
POST

### Endpoint
/orders/estimate

### Parameters
#### Request Body
- **payment_method** (object) - Required - The payment method details.
  - **type** (string) - Required - The type of payment method (e.g., "ACCOUNT_BALANCE").
  - **currency** (string) - Required - The currency of the payment method (e.g., "GBP").
- **items** (array) - Required - A list of items in the order.
  - **face_value** (number) - Required - The face value of the item.
  - **distribution_method** (object) - Required - The distribution method for the item.
    - **type** (string) - Required - The type of distribution method (e.g., "EMAIL").
    - **email_address** (string) - Required - The email address for distribution.
  - **products** (object) - Required - The product details.
    - **type** (string) - Required - The type of product (e.g., "MULTIPLE").
    - **values** (array) - Required - A list of product identifiers (e.g., ["AMZ-US", "AMC-US"]).

### Request Example
```json
{
  "payment_method": {
    "type": "ACCOUNT_BALANCE",
    "currency": "GBP"
  },
  "items": [
    {
      "face_value": 10,
      "distribution_method": {
        "type": "EMAIL",
        "email_address": "fred@bloggs.com"
      },
      "products": {
        "type": "MULTIPLE",
        "values": ["AMZ-US", "AMC-US"]
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- **payment_method** (object) - Details of the payment method used.
- **currency** (string) - The currency of the order.
- **total_discount** (string) - The total discount applied to the order.
- **total_price** (string) - The total price of the order.
- **items** (array) - Details of each item in the order.
  - **products** (object) - Product details.
  - **currency** (string) - The currency of the item.
  - **face_value** (string) - The face value of the item.
  - **price** (string) - The price of the item.
  - **discount_multiplier** (string) - The discount multiplier applied.
- **transaction_detail** (object) - Detailed transaction information, including FX rates and fees.
  - **[currency_code]** (object) - Transaction details for a specific currency.
    - **value** (string) - The transaction value.
    - **fx** (object) - Foreign exchange details.
      - **rate** (string) - The FX rate.
      - **rate_symbol** (string) - The FX rate symbol (e.g., "GBPUSD").
      - **fee** (object) - The FX fee details.
        - **value** (string) - The fee value.
        - **currency** (string) - The currency of the fee.

#### Response Example
```json
{
  "payment_method": {
    "type": "ACCOUNT_BALANCE",
    "currency": "GBP"
  },
  "currency": "GBP",
  "total_discount": "0.00",
  "total_price": "8.49",
  "items": [
    {
      "products": {
        "type": "MULTIPLE",
        "values": ["AMZ-US", "AMC-US"]
      },
      "currency": "USD",
      "face_value": "10.00",
      "price": "10.00",
      "discount_multiplier": "0.05"
    }
  ],
  "transaction_detail": {
    "USD": {
      "value": "10.00",
      "fx": {
        "rate": "1.2",
        "rate_symbol": "GBPUSD",
        "fee": {
          "value": "0.16",
          "currency": "GBP"
        }
      }
    }
  }
}
```
```

--------------------------------

### Example JSON for Payout Link Request

Source: https://github.com/wegift/api-docs/blob/main/snippets/getting-started-order-item.mdx

This JSON object represents a sample request for creating a payout link. It includes essential fields like face value, distribution method, and product selection.

```json
{
  "face_value": 10,
  "distribution_method": {
    ...
  },
  "products": {
    ...
  }
}
```

--------------------------------

### Example API Key Authentication Request

Source: https://github.com/wegift/api-docs/blob/main/best-practices/authentication.mdx

Demonstrates how to include an API key in the request header for authenticating with the Runa API. The API key is sent via the 'X-Api-Key' header.

```http
GET https://api.runa.io/v2/orders HTTP/2
X-Api-Key: YOUR_API_KEY
```

--------------------------------

### Payment Denomination Example (JSON)

Source: https://github.com/wegift/api-docs/blob/main/features/product-catalog.mdx

Shows the denomination constraints for payments, which are always 'open'. It includes minimum and maximum values for allowed payment amounts.

```json
{
    "denominations": {
        "minimum_value": "5.00",
        "maximum_value": "250.00"
    }
}
```

--------------------------------

### GET /v2/balance

Source: https://github.com/wegift/api-docs/blob/main/features/balances.mdx

Retrieve information on all balances associated with your account.

```APIDOC
## GET /v2/balance

### Description
Retrieve information on all balances associated with your account.

### Method
GET

### Endpoint
/v2/balance

### Parameters
#### Query Parameters
- **currency** (string) - Optional - The ISO4217 three-letter currency code to filter balances.

### Request Example
```json
{
  "example": "GET /v2/balance?currency=GBP"
}
```

### Response
#### Success Response (200)
- **balance** (string) - The current available funding for the specified currency.
- **currency** (string) - The ISO4217 three-letter currency code.

#### Response Example
```json
[
  {
    "balance": "1200.00",
    "currency": "CAD"
  },
  {
    "balance": "500.00",
    "currency": "EUR"
  },
  {
    "balance": "12500.00",
    "currency": "GBP"
  },
  {
    "balance": "45000",
    "currency": "JPY"
  },
  {
    "balance": "19.50",
    "currency": "USD"
  }
]
```
```

--------------------------------

### Get Product Details

Source: https://github.com/wegift/api-docs/blob/main/reference/2024-02-05/endpoint/products/get.mdx

Retrieves the details of a single product using its unique product code.

```APIDOC
## GET /product/{product_code}

### Description
Returns a single product by its code, e.g. `XYZ-US`.

This endpoint supports returning product content in different formats. See the [content](/reference/2024-02-05/endpoint/products/get#parameter-content) parameter for more details.

### Method
GET

### Endpoint
/product/{product_code}

### Parameters
#### Path Parameters
- **product_code** (string) - Required - The unique code of the product to retrieve.

#### Query Parameters
- **content** (string) - Optional - Specifies the desired format for product content. See documentation for available formats.

### Request Example
```json
{
  "example": "GET /product/XYZ-US?content=detailed"
}
```

### Response
#### Success Response (200)
- **product_code** (string) - The unique code of the product.
- **name** (string) - The name of the product.
- **description** (string) - A description of the product.
- **currency** (string) - The currency of the product.
- **price** (number) - The price of the product.
- **available_regions** (array) - A list of regions where the product is available.

#### Response Example
```json
{
  "product_code": "XYZ-US",
  "name": "Example Product",
  "description": "This is a sample product description.",
  "currency": "USD",
  "price": 10.00,
  "available_regions": ["US", "CA"]
}
```
```

--------------------------------

### GET /v2/products

Source: https://github.com/wegift/api-docs/blob/main/changelog/api.mdx

Retrieves a list of available products. Includes a new header requirement for specifying the API version.

```APIDOC
## GET /v2/products

### Description
Retrieves a list of available products. This endpoint now requires the `x-api-version` header.

### Method
GET

### Endpoint
/v2/products

### Parameters
#### Query Parameters
- **x-api-version** (string) - Required - The API version to use.

### Response
#### Success Response (200)
- **products** (array) - A list of product objects. (Details of product object structure are not provided in the input.)

#### Response Example
```json
{
  "products": [
    {
      "id": "product_1",
      "name": "Example Product 1",
      "price": 10.00
    },
    {
      "id": "product_2",
      "name": "Example Product 2",
      "price": 20.00
    }
  ]
}
```
```

--------------------------------

### Pagination Object Example

Source: https://github.com/wegift/api-docs/blob/main/reference/pagination.mdx

This JSON object illustrates the structure of the pagination information returned by paged API endpoints. It includes cursors for navigating between pages and the limit applied to the current page.

```json
{
    "pagination": {
        "cursors": {
            "after": "A-789",
            "before": "A-123"
        },
        "page": {
            "limit": 100
        }
    }
}
```

--------------------------------

### GET /v2/orders

Source: https://github.com/wegift/api-docs/blob/main/changelog/api.mdx

Retrieves a paginated list of orders. Supports cursor-based pagination and includes updated response fields consistent with the Get Order API.

```APIDOC
## GET /v2/orders

### Description
Retrieves a paginated list of orders. This endpoint uses cursor-based pagination and includes response fields that have been updated to align with the `GET /v2/order/{id}` response structure.

### Method
GET

### Endpoint
/v2/orders

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of orders to return per page.
- **before** (string) - Optional - Returns orders created before this cursor.
- **after** (string) - Optional - Returns orders created after this cursor.
- **x-api-version** (string) - Required - The API version to use.

### Response
#### Success Response (200)
- **data** (array) - A list of order objects.
  - **status** (string) - The status of the order. Enum: `COMPLETED`, `PROCESSING`, `FAILED`.
  - **completed_at** (string) - Timestamp when the order was completed.
  - **redemption_url** (string) - The URL for order redemption.
  - **payment_method** (object) - Details of the payment method used.
    - **type** (string) - The type of payment method. Enum: `CARD`, `ACCOUNT_BALANCE`.
    - **card_id** (string) - The ID of the card used.
    - **currency** (string) - The currency of the payment. Enum: `EUR`, `GBP`, `USD`, `CAD`.
  - **items** (array) - Details of the items in the order.
    - **distribution_method** (object) - Details of the distribution method.
      - **type** (string) - The distribution type. Enum: `EMAIL`, `PAYOUT_LINK`.
      - **email_address** (string) - The email address for distribution.
    - **products** (object) - Details of the products for the item.
      - **type** (string) - The product type. Enum: `SINGLE`, `MULTIPLE`.
      - **value** (string) - The value of the single product.
      - **values** (array of strings) - A list of values for multiple products.
- **pagination** (object) - Pagination details.
  - **next_cursor** (string) - The cursor for the next page of results.
  - **prev_cursor** (string) - The cursor for the previous page of results.

#### Response Example
```json
{
  "data": [
    {
      "status": "COMPLETED",
      "completed_at": "2023-10-27T10:00:00Z",
      "redemption_url": "https://wegift.com/r/order_abc123",
      "payment_method": {
        "type": "CARD",
        "card_id": "card_xyz789",
        "currency": "EUR"
      },
      "items": [
        {
          "distribution_method": {
            "type": "EMAIL",
            "email_address": "test@example.com"
          },
          "products": {
            "type": "SINGLE",
            "value": "product_id_123"
          }
        }
      ]
    }
  ],
  "pagination": {
    "next_cursor": "next_cursor_string",
    "prev_cursor": "prev_cursor_string"
  }
}
```
```

--------------------------------

### Environments

Source: https://github.com/wegift/api-docs/blob/main/reference/2024-02-05/introduction.mdx

The Runa API is available in two environments: Production for live transactions and Playground for testing.

```APIDOC
## Environments

### Production
- **Base URL**: `https://api.runa.io/v2`
- **Description**: Use this environment for processing real transactions.

### Playground
- **Base URL**: `https://playground.runa.io/v2`
- **Description**: A simulated environment for experimenting with the API without real transactions. Note that some endpoints and features may differ from production.
```

--------------------------------

### Order Placement API - Headers

Source: https://github.com/wegift/api-docs/blob/main/snippets/getting-started-common-headers.mdx

This section details the required and optional headers for placing an order.

```APIDOC
## Order Placement API - Headers

### Description
This endpoint requires specific headers to be included in the API request for successful order placement.

### Method
POST (Assumed for order placement)

### Endpoint
/orders (Assumed endpoint for placing orders)

### Parameters
#### Header Parameters
- **X-Api-Key** (string) - Required - The API key generated during the setup process.
- **X-Idempotency-Key** (string) - Required - A unique value to prevent duplicate purchases. A V4 UUID is recommended.
- **X-Api-Version** (string) - Optional - The API version to use. Defaults to `2024-02-05` if not provided.

### Request Example
```json
{
  "example": "Headers: \n X-Api-Key: YOUR_API_KEY\n X-Idempotency-Key: a1b2c3d4-e5f6-7890-1234-567890abcdef\n X-Api-Version: 2024-02-05"
}
```

### Response
#### Success Response (201 Created - typical for order creation)
- **orderId** (string) - The unique identifier for the created order.
- **status** (string) - The current status of the order.

#### Response Example
```json
{
  "orderId": "ord_12345abcde",
  "status": "PENDING"
}
```
```

--------------------------------

### GET /v2/balance?currency=[CURRENCY]

Source: https://github.com/wegift/api-docs/blob/main/features/balances.mdx

Retrieve the balance for a specific currency.

```APIDOC
## GET /v2/balance?currency=[CURRENCY]

### Description
Retrieve the balance for a specific currency by including the three-letter currency code in the GET request.

### Method
GET

### Endpoint
/v2/balance/?currency=[CURRENCY]

### Parameters
#### Query Parameters
- **currency** (string) - Required - The ISO4217 three-letter currency code for which to retrieve the balance.

### Request Example
```json
{
  "example": "GET /v2/balance/?currency=GBP"
}
```

### Response
#### Success Response (200)
- **balance** (string) - The current available funding for the specified currency.
- **currency** (string) - The ISO4217 three-letter currency code.

#### Response Example
```json
{
  "balance": "1200.00",
  "currency": "CAD"
}
```
```

--------------------------------

### Runa API Environments

Source: https://github.com/wegift/api-docs/blob/main/getting-started/environments.mdx

Details about the Production and Playground environments for the Runa API, including their base URLs and API key formats.

```APIDOC
## Runa API Environments

### Description

Provides information on the available environments for interacting with the Runa API: Production for live operations and Playground for testing.

### Environments

- **Production**
  - **Base URL**: `https://api.runa.io`
  - **API Key Prefix**: `wg`
  - **Description**: The default environment for live operations. Requests here create real-world transactions and incur charges.

- **Playground**
  - **Base URL**: `https://playground.runa.io`
  - **API Key Prefix**: `XX`
  - **Description**: A simulated environment where you can test without creating real transactions or expenses. Recommended for testing and development.

### Usage Recommendation

It is recommended to use the Playground environment for testing and development purposes before moving to the Production environment for processing real transactions.
```

--------------------------------

### Paging Through the Catalog

Source: https://github.com/wegift/api-docs/blob/main/features/product-catalog.mdx

How to paginate through the product catalog using `after` and `limit` query parameters.

```APIDOC
## 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.

### Method
GET

### Endpoint
`/product?after={cursor}&limit={limit_value}

### Query Parameters
- **after** (string) - Optional - A cursor for fetching the next page of products.
- **limit** (integer) - Optional - The number of products to return per page. Defaults to 500.

### Response
#### Success Response (200)
- **pagination** (object) - Contains cursor information for pagination.
  - **pagination.cursors** (object) - Cursor values for navigating between pages.
    - **pagination.cursors.after** (string) - Cursor for fetching the next page.
    - **pagination.cursors.before** (string) - Cursor for fetching the previous page.
  - **pagination.page** (object) - Information about the current page.
    - **pagination.page.limit** (integer) - The limit applied to the current page.

#### Response Example
```json
{
    "pagination": {
        "cursors": {
            "after": "MMM-US",
            "before": "AAA-US"
        },
        "page": {
            "limit": 100
        }
    }
}
```

For more details on pagination, refer to the [Pagination reference](/reference/pagination).
```

--------------------------------

### List Products

Source: https://github.com/wegift/api-docs/blob/main/reference/2024-02-05/playground.mdx

Retrieves a list of products available for creating orders. The catalog in the playground is static and represents the base product selection.

```APIDOC
## GET /reference/2024-02-05/endpoint/products/list

### Description
Retrieves a list of products available for creating orders in the Playground environment.

### Method
GET

### Endpoint
/reference/2024-02-05/endpoint/products/list

### Parameters
None

### Response
#### Success Response (200)
- **products** (array) - A list of available product objects.
  - **productId** (string) - The unique identifier of the product.
  - **name** (string) - The name of the product.
  - **currency** (string) - The currency in which the product is offered.

#### Response Example
```json
{
  "products": [
    {
      "productId": "prod_abc",
      "name": "Example Product",
      "currency": "USD"
    }
  ]
}
```
```

--------------------------------

### GET /v2/product/countries

Source: https://github.com/wegift/api-docs/blob/main/changelog/api.mdx

Retrieves a list of countries relevant to product availability or redemption.

```APIDOC
## GET /v2/product/countries

### Description
Retrieves a list of countries relevant to product availability or redemption.

### Method
GET

### Endpoint
/v2/product/countries

### Parameters
(No parameters documented for this endpoint)

### Response
#### Success Response (200)
(Response structure not detailed in provided text)

#### Response Example
(No example provided in the text)
```

--------------------------------

### Product Selection using Template

Source: https://github.com/wegift/api-docs/blob/main/snippets/getting-started-order-item.mdx

Configure product selection to use a pre-defined template. This is useful for scenarios where you want to offer a curated set of products or a randomized selection. The `template_id` specifies which template to use.

```json
"products": {
  "type": "TEMPLATE",
  "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK"
}
```

--------------------------------

### Get account balance

Source: https://github.com/wegift/api-docs/blob/main/reference/2024-02-05/endpoint/balance/get.mdx

Fetch the current balances for your account. This endpoint can retrieve a specific currency balance or all balances greater than 0.

```APIDOC
## GET /balance

### Description
Fetches the current balances for your account. If the `currency` parameter is provided, a single balance object for the requested currency is returned. If omitted, an array of balance objects for all currencies with a balance greater than 0 is returned.

### Method
GET

### Endpoint
/balance

### Parameters
#### Query Parameters
- **currency** (string) - Optional - The currency code for which to retrieve the balance (e.g., "USD", "EUR").

### Response
#### Success Response (200)
- **balances** (array of objects) - An array of balance objects, each containing:
  - **currency** (string) - The currency code.
  - **amount** (number) - The balance amount.

#### Response Example
```json
{
  "balances": [
    {
      "currency": "USD",
      "amount": 1500.75
    },
    {
      "currency": "EUR",
      "amount": 250.50
    }
  ]
}
```
```

--------------------------------

### List All Products

Source: https://github.com/wegift/api-docs/blob/main/features/product-catalog.mdx

Retrieve a list of all available products, with options to filter by country, category, and orderability.

```APIDOC
## GET /reference/2024-02-05/endpoint/products/list

### Description
Fetches a list of all available products. This endpoint supports filtering by orderability, countries of redemption, and categories.

### Method
GET

### Endpoint
/reference/2024-02-05/endpoint/products/list

### Parameters
#### Query Parameters
- **is_orderable** (boolean) - Optional - When set to `true` only returns products that can be ordered.
- **countries_redeemable_in** (string) - Optional - Only return products that can be redeemed in a specific country. Accepts ISO3166 ALPHA-2 country codes.
- **categories** (string) - Optional - Limit the products to one or more categories.

### Request Example
```json
{
  "query": {
    "is_orderable": true,
    "countries_redeemable_in": "US",
    "categories": "electronics"
  }
}
```

### Response
#### Success Response (200)
- **code** (string) - A unique code identifying the product. Use this code when placing an order.
- **is_orderable** (boolean) - Indicates whether a product can be ordered.
- **currency** (string) - The currency of the product, represented by an ISO 4217 currency code.
- **countries_redeemable_in** (string[]) - The countries in which the product can be redeemed.

#### Response Example
```json
{
  "products": [
    {
      "code": "EXAMPLE-PRODUCT-1",
      "is_orderable": true,
      "currency": "USD",
      "countries_redeemable_in": ["US", "CA"]
    }
  ]
}
```
```

--------------------------------

### Create an Order (Playground)

Source: https://github.com/wegift/api-docs/blob/main/reference/2024-02-05/playground.mdx

Lets you create playground orders. The behavior closely resembles the production API, with specific considerations for testing.

```APIDOC
## POST /v2/orders

### Description
Creates an order in the Playground environment. This endpoint simulates order creation with specific allowances for testing purposes, such as unlimited funding and controlled email distribution.

### Method
POST

### Endpoint
`https://playground.runa.io/v2/orders`

### Parameters
#### Query Parameters
- **X-Send-Email** (boolean) - Optional - Set to `true` to enable email sending for the first order item with an email distribution type. Defaults to `false`.

#### Request Body
- **distributionType** (string) - Required - The type of distribution for the order items (e.g., 'email', 'link').
- **recipient** (string) - Required if `distributionType` is 'email' - The email address of the recipient. Use `.invalid` or `.test` domains for safe testing.
- **fundings** (array) - Required - Details about how the order will be funded.
  - **type** (string) - Required - The funding type (e.g., 'account_balance').
- **items** (array) - Required - The items to be included in the order.
  - **sku** (string) - Required - The Stock Keeping Unit of the item.
  - **quantity** (integer) - Required - The number of units for the item.

### Request Example
```json
{
  "distributionType": "email",
  "recipient": "test@domain.invalid",
  "fundings": [
    {
      "type": "account_balance"
    }
  ],
  "items": [
    {
      "sku": "SAMPLE_SKU",
      "quantity": 1
    }
  ]
}
```

### Response
#### Success Response (200)
- **orderId** (string) - The unique identifier for the created order.
- **status** (string) - The current status of the order.
- **X-Send-Email** (boolean) - Indicates if the email sending was enabled for this request.

#### Response Example
```json
{
  "orderId": "ord_12345abcde",
  "status": "PENDING",
  "X-Send-Email": true
}
```

### Notes
- Account balance is always accepted for payment in the playground.
- There are no fund limits in the playground.
- For Embedded FX orders, exchange rates and fees are arbitrary and not reflective of production.
- Emails are only sent for the first order item with an email distribution type when `X-Send-Email: true` is set.
```

--------------------------------

### GET /v2/order

Source: https://github.com/wegift/api-docs/blob/main/changelog/api.mdx

Retrieves a list of orders. This endpoint's response structure has been updated as part of API version 2023-07-27.

```APIDOC
## GET /v2/order

### Description
Retrieves a list of orders. This endpoint's response structure has been updated as part of API version 2023-07-27.

### Method
GET

### Endpoint
/v2/order

### Parameters
(Query parameters and request body structure not detailed in provided text for this specific update)

### Response
#### Success Response (200)
(Response structure not detailed in provided text)

#### Response Example
(No example provided in the text)
```

--------------------------------

### API Authentication Header

Source: https://github.com/wegift/api-docs/blob/main/reference/2024-02-05/introduction.mdx

Demonstrates the required HTTP header for API authentication. All API endpoints require an API key to be included in the 'X-Api-Key' header for requests.

```http
X-Api-Key: YOUR_API_KEY
```

--------------------------------

### Get Order Details

Source: https://github.com/wegift/api-docs/blob/main/reference/2024-02-05/playground.mdx

Retrieves the details of a specific order created using the Playground API key. This includes redemption URLs for testing simulated gift card redemptions.

```APIDOC
## GET /reference/2024-02-05/endpoint/orders/get

### Description
Retrieves the details of a specific order.

### Method
GET

### Endpoint
/reference/2024-02-05/endpoint/orders/get

### Parameters
#### Query Parameters
- **orderId** (string) - Required - The unique identifier of the order to retrieve.

### Response
#### Success Response (200)
- **order** (object) - An object containing the order details.
  - **orderId** (string) - The unique identifier of the order.
  - **redemptionUrls** (array) - A list of URLs for gift card redemption.

#### Response Example
```json
{
  "orderId": "ord_12345",
  "redemptionUrls": [
    "https://example.com/redeem?id=abc"
  ]
}
```
```

--------------------------------

### Authentication

Source: https://github.com/wegift/api-docs/blob/main/reference/2024-02-05/introduction.mdx

All API endpoints require authentication using API keys. The API key must be provided in the 'X-Api-Key' header for every request.

```APIDOC
## Authentication

### Description
API endpoints are authenticated using API keys generated from the Runa web app. The API key must be included in the `X-Api-Key` header of each request.

### Header
- **X-Api-Key** (string) - Required - Your generated API key.
```

--------------------------------

### POST /v2/order (Synchronous)

Source: https://github.com/wegift/api-docs/blob/main/getting-started/first-order/sync.mdx

This endpoint allows you to place an order in synchronous mode. It returns the order details immediately upon successful completion.

```APIDOC
## POST /v2/order

### Description
Places an order in synchronous mode, returning immediate order details upon completion.

### Method
POST

### Endpoint
https://playground.runa.io/v2/order

### Headers
- **X-Api-Key** (string) - Required - Your API key.
- **X-Idempotency-Key** (string) - Required - Used to ensure requests are processed only once.
- **X-Api-Version** (string) - Required - The API version to use (e.g., `2024-02-05`).
- **X-Execution-Mode** (string) - Optional - Set to `sync` for synchronous execution. Defaults to `async`.
- **Content-Type** (string) - Required - Must be `application/json`.

### Request Body
- **payment_method** (object) - Required - Details about the payment method.
  - **type** (string) - Required - The type of payment method (e.g., `ACCOUNT_BALANCE`).
  - **currency** (string) - Required - The currency for the payment (e.g., `USD`).
- **items** (array) - Required - A list of items to order. For synchronous mode, this array should contain a single item.
  - **face_value** (number) - Required - The face value of the order item.
  - **distribution_method** (object) - Required - How the order should be distributed.
    - **type** (string) - Required - The distribution type (e.g., `PAYOUT_LINK`).
  - **products** (object) - Required - Details about the product.
    - **type** (string) - Required - The product type (e.g., `TEMPLATE`).
    - **template_id** (string) - Required - The ID of the product template.

### Request Example
```json
{
  "payment_method": {
    "type": "ACCOUNT_BALANCE",
    "currency": "USD"
  },
  "items": [
    {
      "face_value": 10,
      "distribution_method": {
        "type": "PAYOUT_LINK"
      },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK"
      }
    }
  ]
}
```

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier for the order.
- **status** (string) - The current status of the order (e.g., `COMPLETED`).
- **created_at** (string) - Timestamp when the order was created.
- **completed_at** (string) - Timestamp when the order was completed.
- **payment_method** (object) - Details of the payment method used.
- **currency** (string) - The currency of the order.
- **items** (array) - Details of the ordered items.
  - **id** (string) - The unique identifier for the item.
  - **distribution_method** (object) - Details of the distribution method.
  - **products** (object) - Details of the product ordered.
  - **face_value** (string) - The face value of the item.
  - **price** (string) - The price of the item.
  - **payout** (object) - Information about the payout, including the URL.
    - **url** (string) - The payout link URL.
  - **currency** (string) - The currency of the item.

#### Response Example
```json
{
  "id": "O-01234567890ABCDEFGHIJK",
  "status": "COMPLETED",
  "created_at": "2025-01-01T12:00:00+00:00",
  "completed_at": "2025-01-01T12:00:01+00:00",
  "description": null,
  "payment_method": {
    "type": "ACCOUNT_BALANCE"
  },
  "currency": "USD",
  "items": [
    {
      "id": "E-01234567890ABCDEFGHIJK",
      "distribution_method": {
        "type": "PAYOUT_LINK"
      },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK",
        "values": [ ... ]
      },
      "face_value": "10.00",
      "price": "10.00",
      "payout": {
        "status": "ACTIVE",
        "status_updated_at": "2025-01-01T12:00:01+00:00",
        "url": "https://payout.playground.runa.io/01234567-0000-4000-abcd-012345678900"
      },
      "currency": "USD"
    }
  ]
}
```
```

--------------------------------

### GET /reference/2024-02-05/endpoint/products/list - List Products

Source: https://github.com/wegift/api-docs/blob/main/changelog/api.mdx

The List products endpoint now supports filtering by category using the `categories` query parameter. You can filter by one or more categories.

```APIDOC
## GET /reference/2024-02-05/endpoint/products/list

### Description
Retrieves a list of products, now with the ability to filter by category.

### Method
GET

### Endpoint
/reference/2024-02-05/endpoint/products/list

### Parameters
#### Query Parameters
- **categories** (string) - Optional - Filters products by one or more categories. Repeat for multiple categories (e.g., `?categories=fashion&categories=department-stores`).

### Request Example
```json
{
  "example": "GET /reference/2024-02-05/endpoint/products/list?categories=fashion&categories=department-stores"
}
```

### Response
#### Success Response (200)
- **products** (array) - A list of product objects.
- **categories** (array) - A list of available category objects.

#### Response Example
```json
{
  "example": "Response body containing a list of products and categories"
}
```
```

--------------------------------

### GET /v2/order/{id}

Source: https://github.com/wegift/api-docs/blob/main/changelog/api.mdx

Retrieves details for a specific order, including its status and redemption information. The response structure varies based on whether the order is complete.

```APIDOC
## GET /v2/order/{id}

### Description
Retrieves the details of a specific order by its ID. The response structure differs for complete and incomplete orders, providing relevant information for each state.

### Method
GET

### Endpoint
/v2/order/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the order.

#### Query Parameters
- **x-api-version** (string) - Required - The API version to use.

### Response
#### Success Response (200)
**For a complete order:**
- **status** (string) - The status of the order. Enum: `COMPLETED`, `PROCESSING`, `FAILED`.
- **completed_at** (string) - Timestamp when the order was completed.
- **redemption_url** (string) - The URL for order redemption.
- **payment_method** (object) - Details of the payment method used.
  - **type** (string) - The type of payment method. Enum: `CARD`, `ACCOUNT_BALANCE`.
  - **card_id** (string) - The ID of the card used.
  - **currency** (string) - The currency of the payment. Enum: `EUR`, `GBP`, `USD`, `CAD`.
- **items** (array) - Details of the items in the order.
  - **distribution_method** (object) - Details of the distribution method.
    - **type** (string) - The distribution type. Enum: `EMAIL`, `PAYOUT_LINK`.
    - **email_address** (string) - The email address for distribution.
  - **products** (object) - Details of the products for the item.
    - **type** (string) - The product type. Enum: `SINGLE`, `MULTIPLE`.
    - **value** (string) - The value of the single product.
    - **values** (array of strings) - A list of values for multiple products.

**For an incomplete order:**
- **status** (string) - The status of the order. Enum: `COMPLETED`, `PROCESSING`, `FAILED`.
- **id** (string) - The unique identifier for the order.
- **message** (string) - A message indicating why the order is incomplete.

#### Response Example (Complete Order)
```json
{
  "status": "COMPLETED",
  "completed_at": "2023-10-27T10:00:00Z",
  "redemption_url": "https://wegift.com/r/order_abc123",
  "payment_method": {
    "type": "CARD",
    "card_id": "card_xyz789",
    "currency": "EUR"
  },
  "items": [
    {
      "distribution_method": {
        "type": "EMAIL",
        "email_address": "test@example.com"
      },
      "products": {
        "type": "SINGLE",
        "value": "product_id_123"
      }
    }
  ]
}
```

#### Response Example (Incomplete Order)
```json
{
  "status": "PROCESSING",
  "id": "order_abc123",
  "message": "Order is still being processed."
}
```
```

--------------------------------

### List Countries

Source: https://github.com/wegift/api-docs/blob/main/reference/2024-02-05/playground.mdx

Retrieves a list of countries where products are available. This list is static for the playground environment and corresponds to the base product selection.

```APIDOC
## GET /reference/2024-02-05/endpoint/products/countries

### Description
Retrieves a list of countries where products are available in the Playground environment.

### Method
GET

### Endpoint
/reference/2024-02-05/endpoint/products/countries

### Parameters
None

### Response
#### Success Response (200)
- **countries** (array) - A list of country codes where products are available.

#### Response Example
```json
{
  "countries": [
    "US",
    "GB",
    "DE"
  ]
}
```
```

--------------------------------

### GET /v2/order/{id}

Source: https://github.com/wegift/api-docs/blob/main/changelog/api.mdx

Retrieves details for a specific order using its ID. This endpoint's response structure has been updated as part of API version 2023-07-27.

```APIDOC
## GET /v2/order/{id}

### Description
Retrieves details for a specific order using its ID. This endpoint's response structure has been updated as part of API version 2023-07-27.

### Method
GET

### Endpoint
/v2/order/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the order.

### Response
#### Success Response (200)
(Response structure not detailed in provided text)

#### Response Example
(No example provided in the text)
```

--------------------------------

### GET /reference/2024-02-05/endpoint/products/categories - List Categories

Source: https://github.com/wegift/api-docs/blob/main/changelog/api.mdx

This new endpoint allows you to fetch the full list of product categories supported by the API, useful for dynamic category selectors or validation.

```APIDOC
## GET /reference/2024-02-05/endpoint/products/categories

### Description
Fetches the full list of product categories supported by the API.

### Method
GET

### Endpoint
/reference/2024-02-05/endpoint/products/categories

### Parameters
#### Query Parameters
- None

### Request Example
```json
{
  "example": "GET /reference/2024-02-05/endpoint/products/categories"
}
```

### Response
#### Success Response (200)
- **categories** (array) - A list of category objects.

#### Response Example
```json
{
  "example": "Response body containing a list of available product categories"
}
```
```
Tokens:
Raw