openapi: 3.1.0
info:
  title: Runa Payouts Balance Orders API
  description: The Runa Payouts API provides a single integration point for digital reward and gift card distribution across 190+ countries with access to over 5,000 gift cards and payout options. The API supports creating orders in both synchronous (instant) and asynchronous (polling) modes, balance management, product catalog browsing by category and country, order estimation, and event webhooks for order completion and product updates. Authentication uses the X-Api-Key header. Use X-Idempotency-Key on order creation to prevent duplicate orders.
  version: '2024-02-05'
  contact:
    name: Runa Developer Support
    url: https://developer.runa.io/
  termsOfService: https://runa.io/legal/
servers:
- url: https://api.runa.io/v2
  description: Runa Production API
- url: https://playground.runa.io/v2
  description: Runa Playground (sandbox)
tags:
- name: Orders
  description: Create, retrieve, list, and estimate digital reward orders.
paths:
  /order:
    post:
      operationId: createOrder
      summary: Create An Order
      description: Create a new digital reward order. Specify the payment method, distribution method, and product selection. Use X-Execution-Mode header set to 'sync' for synchronous fulfillment or 'async' for asynchronous processing. Include X-Idempotency-Key to prevent duplicate orders on retry.
      tags:
      - Orders
      parameters:
      - name: X-Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: A unique identifier (V4 UUID recommended) to ensure idempotent order creation on retries.
      - name: X-Execution-Mode
        in: header
        required: false
        schema:
          type: string
          enum:
          - sync
          - async
          default: sync
        description: Order execution mode. Use 'sync' for immediate fulfillment or 'async' for asynchronous processing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '200':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable entity - insufficient balance or invalid product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - apiKeyAuth: []
    get:
      operationId: listOrders
      summary: List Orders
      description: Retrieve a paginated list of orders created with the authenticated API key. Supports filtering and pagination.
      tags:
      - Orders
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        description: Page number for pagination
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Number of orders per page
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - apiKeyAuth: []
  /order/{orderId}:
    get:
      operationId: getOrder
      summary: Get Order
      description: Retrieve the details of a specific order by its ID. Use this endpoint to poll for order completion when using asynchronous mode.
      tags:
      - Orders
      parameters:
      - name: orderId
        in: path
        required: true
        schema:
          type: string
        description: The unique order identifier
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - apiKeyAuth: []
  /order/estimate:
    post:
      operationId: estimateOrder
      summary: Estimate Order
      description: Estimate the cost of an order before creating it. Returns the estimated face value, fees, and total cost in the account currency. Useful for presenting pricing to end users before checkout.
      tags:
      - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EstimateOrderRequest'
      responses:
        '200':
          description: Order estimate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderEstimate'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - apiKeyAuth: []
components:
  schemas:
    CreateOrderRequest:
      type: object
      required:
      - payment_method
      - items
      description: Request body for creating a digital reward order
      properties:
        payment_method:
          type: object
          required:
          - type
          - currency
          description: Payment source for the order
          properties:
            type:
              type: string
              description: Payment method type
              enum:
              - ACCOUNT_BALANCE
            currency:
              type: string
              description: ISO 4217 currency code (e.g., USD)
        items:
          type: array
          minItems: 1
          description: Array of order items to fulfill
          items:
            type: object
            required:
            - face_value
            - distribution_method
            - products
            properties:
              face_value:
                type: number
                description: Monetary value of the reward
              currency:
                type: string
                description: ISO 4217 currency code for item face value
              distribution_method:
                type: string
                description: How the reward link is delivered
                enum:
                - EMAIL
                - PAYOUT_LINK
                - RECIPIENT
              products:
                type: object
                description: Product selection configuration
                properties:
                  type:
                    type: string
                    description: Product selection type
                    enum:
                    - SINGLE
                    - MULTIPLE
                    - TEMPLATE
                  product_ids:
                    type: array
                    items:
                      type: string
                    description: Specific product IDs (for SINGLE or MULTIPLE type)
              recipient:
                type: object
                description: Recipient details (for EMAIL distribution)
                properties:
                  email:
                    type: string
                    format: email
                    description: Recipient email address
                  name:
                    type: string
                    description: Recipient display name
    OrderEstimate:
      type: object
      description: Cost estimate for a potential order
      properties:
        face_value:
          type: number
          description: Total face value of the order
        fees:
          type: number
          description: Platform fees for the order
        total:
          type: number
          description: Total cost including fees
        currency:
          type: string
          description: Currency for all values
    Pagination:
      type: object
      description: Pagination metadata
      properties:
        page:
          type: integer
          description: Current page number
        per_page:
          type: integer
          description: Items per page
        total:
          type: integer
          description: Total number of items
        total_pages:
          type: integer
          description: Total number of pages
    EstimateOrderRequest:
      type: object
      required:
      - payment_method
      - items
      description: Request body for estimating order cost
      properties:
        payment_method:
          type: object
          properties:
            type:
              type: string
              enum:
              - ACCOUNT_BALANCE
            currency:
              type: string
        items:
          type: array
          items:
            type: object
            properties:
              face_value:
                type: number
              currency:
                type: string
              products:
                type: object
    Error:
      type: object
      description: Standard error response
      properties:
        type:
          type: string
          description: Error type identifier
        message:
          type: string
          description: Human-readable error message
        help:
          type: string
          description: Link or additional help information
    Order:
      type: object
      description: A Runa digital reward order
      properties:
        id:
          type: string
          description: Unique order identifier
        status:
          type: string
          description: Order status
          enum:
          - PENDING
          - PROCESSING
          - COMPLETED
          - FAILED
          - CANCELLED
        created_at:
          type: string
          format: date-time
          description: Order creation timestamp
        completed_at:
          type: string
          format: date-time
          description: Order completion timestamp
        payment_method:
          type: object
          description: Payment method used for the order
          properties:
            type:
              type: string
            currency:
              type: string
        items:
          type: array
          description: Order items with fulfillment details
          items:
            type: object
            properties:
              id:
                type: string
                description: Item identifier
              face_value:
                type: number
                description: Item face value
              currency:
                type: string
                description: Item currency
              status:
                type: string
                description: Item fulfillment status
              payout:
                type: object
                description: Payout details for fulfilled item
                properties:
                  url:
                    type: string
                    format: uri
                    description: Payout redemption link for the recipient
                  expires_at:
                    type: string
                    format: date-time
                    description: Link expiration timestamp
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Runa API key. Generate your key at https://app.runa.io/api-keys. The key is only displayed at generation time for security.