Tackle Currencies API

openapi: 3.0.3
info:
  title: Tackle Authentication Currencies API
  description: Authenticated programmatic access to Tackle's webhooks, metering, private offers, and more.
  version: 1.0.0
  contact:
    name: Tackle Support
    email: support@tackle.io
    url: https://tackle.io
servers:
- url: https://api.tackle.io
tags:
- name: Currencies
  description: Microsoft marketplace currency and conversion helpers.
paths:
  /api/currencies:
    get:
      tags:
      - Currencies
      summary: Get Microsoft market currencies
      description: 'Returns accepted currencies and the Microsoft marketplace countries

        grouped by accepted currency.


        Required RBAC action: `offers:CreateDraftOffer`.

        '
      operationId: getMarketCurrencies
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/TackleOperationId'
      responses:
        '200':
          description: Market currencies found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketCurrenciesResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/currencies/convert:
    post:
      tags:
      - Currencies
      summary: Convert currencies
      description: 'Converts one or more amounts from a base currency to a target currency

        using cached Microsoft foreign exchange rates. Row-level conversion

        errors are returned in `results[].error` without failing the entire

        request.


        Required RBAC action: `offers:CreateDraftOffer`.

        '
      operationId: convertCurrencies
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/TackleOperationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CurrencyConversionRequest'
      responses:
        '200':
          description: Currency conversion results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrencyConversionResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    CurrencyConversionError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    CurrencyConversionRequest:
      type: object
      required:
      - conversions
      properties:
        as_of_date:
          type: string
          format: date
          description: Requested FX rate date. Defaults to the current UTC date.
          example: '2026-04-30'
        conversions:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CurrencyConversionPayload'
    CurrencyConversionResult:
      type: object
      properties:
        id:
          type: string
        base_currency:
          type: string
        target_currency:
          type: string
        original_amount:
          type: number
          format: double
        converted_amount:
          type: number
          format: double
        exchange_rate:
          type: number
          format: double
        rate_source_date:
          type: string
          format: date
        rate_as_of_date:
          type: string
          format: date
        error:
          oneOf:
          - $ref: '#/components/schemas/CurrencyConversionError'
          - type: 'null'
    CurrencyConversionResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/CurrencyConversionResult'
        success:
          type: boolean
          example: true
    MarketCurrency:
      type: object
      properties:
        country_name:
          type: string
        iso2:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: US
        currency:
          type: string
          description: ISO 4217 currency code.
          example: USD
        notes:
          type: string
        source:
          type: string
        source_revision:
          type: string
    MarketCurrenciesResponse:
      type: object
      properties:
        currency_options:
          type: array
          items:
            $ref: '#/components/schemas/CurrencyOption'
        currency_markets:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/MarketCurrency'
      example:
        currency_options:
        - value: USD
          display: United States Dollar | USD ($)
        currency_markets:
          USD:
          - country_name: United States
            iso2: US
            currency: USD
    ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Human-readable error message.
          example: missing id
    CurrencyConversionPayload:
      type: object
      required:
      - id
      - base_currency
      - target_currency
      - amount
      properties:
        id:
          type: string
          description: Caller-provided row ID echoed in the response.
        base_currency:
          type: string
          example: USD
        target_currency:
          type: string
          example: EUR
        amount:
          type: number
          format: double
          example: 100
    CurrencyOption:
      type: object
      properties:
        value:
          type: string
          description: ISO 4217 currency code.
          example: USD
        display:
          type: string
          example: United States Dollar | USD ($)
  parameters:
    TackleOperationId:
      name: tackle-operation-id
      in: header
      required: false
      description: Optional caller-provided operation ID for request tracing.
      schema:
        type: string
      example: 018f01ec-3f2b-7a70-b81e-4fc3d6a69f42
  responses:
    ForbiddenError:
      description: Caller is not allowed to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: forbidden
    BadRequestError:
      description: Invalid request or unsupported operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: missing id
    InternalServerError:
      description: Internal server error or upstream dependency failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnauthorizedError:
      description: Authentication failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: unauthorized
  securitySchemes:
    BearerAuth:
      description: The Tackle API requires a JWT for authentication. You can get this by [getting your API credentials](https://developers.tackle.io/docs/how-to-get-an-m2m-client-id-and-secret) from the Tackle Platform then [retrieving your Access Token](https://developers.tackle.io/docs/getting-an-access-token) using our Authentication endpoint.
      type: http
      scheme: bearer
      bearerFormat: JWT
    BasicAuthCallback:
      description: Use `basic` for [basic HTTP authentication](https://en.wikipedia.org/wiki/Basic_access_authentication); this is only used for `callbacks`
      type: http
      scheme: basic
    HeaderApiKeyAuthCallback:
      description: Use `header_api_key` to specify a custom HTTP request header for authentication. Requests from Tackle will use the specified HTTP header for outbound requests to your Webhook URL; this is only used for `callbacks`'
      type: apiKey
      name: subscription-key
      in: header
    Oauth2AuthCallback:
      description: This auth-type is for `oauth2` client credentials flow. We will use the client_id and client_secret to call the token_url to get an access token; this is only used for `callbacks`'
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
externalDocs:
  description: Tackle Developer Hub and API Documentation
  url: https://developers.tackle.io
x-readme:
  explorer-enabled: false
  proxy-enabled: true
  samples-enabled: true