Tango RaaS API

openapi: 3.1.0
info:
  title: Tango RaaS API
  description: >-
    The Tango Rewards-as-a-Service (RaaS) API v2 enables companies to automate
    digital reward and incentive delivery. Access a global catalog of 3,100+
    digital gift cards, prepaid cards, and charitable donations. Manage customer
    accounts, fund balances, place orders, configure email templates, and
    receive real-time webhook notifications.
  version: '2.0'
  termsOfService: https://www.tangocard.com/terms-of-service/
  contact:
    name: Tango Developer Support
    email: devsupport@tangocard.com
    url: https://developers.tangocard.com/
  license:
    name: Proprietary
    url: https://www.tangocard.com/terms-of-service/
servers:
  - url: https://api.tangocard.com/raas/v2
    description: Production
  - url: https://integration-api.tangocard.com/raas/v2
    description: Sandbox
security:
  - basicAuth: []
tags:
  - name: Customers
    description: Manage customer accounts within the Tango platform
  - name: Accounts
    description: Manage sub-accounts for customers including balances and funding
  - name: Low Balance Alerts
    description: Configure low balance alerts for accounts
  - name: Funding
    description: Fund accounts via credit card deposits and fund transfers
  - name: Catalog
    description: Browse the global digital reward catalog
  - name: Orders
    description: Place and manage reward orders
  - name: Line Items
    description: Manage individual order line items
  - name: Digital Templates
    description: Create and manage email delivery templates for rewards
  - name: Reference Data
    description: Exchange rates, reward countries, and credential types
paths:
  /customers:
    get:
      operationId: listCustomers
      summary: List Customers
      description: Retrieve a list of all customers in the platform.
      tags:
        - Customers
      responses:
        '200':
          description: List of customers
          content:
            application/json:
              schema:
                type: object
                properties:
                  customers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCustomer
      summary: Create Customer
      description: Create a new customer account in the platform.
      tags:
        - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
      responses:
        '201':
          description: Customer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{customerIdentifier}:
    get:
      operationId: getCustomer
      summary: Get Customer
      description: Retrieve details of a specific customer.
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
      responses:
        '200':
          description: Customer details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          $ref: '#/components/responses/NotFound'
  /accounts:
    get:
      operationId: listAccounts
      summary: List All Accounts
      description: Retrieve a list of all accounts across all customers.
      tags:
        - Accounts
      responses:
        '200':
          description: List of accounts
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
  /customers/{customerIdentifier}/accounts:
    get:
      operationId: listCustomerAccounts
      summary: List Customer Accounts
      description: Retrieve all accounts for a specific customer.
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
      responses:
        '200':
          description: List of accounts for the customer
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
    post:
      operationId: createAccount
      summary: Create Account
      description: Create a new account for a specific customer.
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccountRequest'
      responses:
        '201':
          description: Account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
  /customers/{customerIdentifier}/accounts/{accountIdentifier}:
    get:
      operationId: getAccount
      summary: Get Account
      description: Retrieve details of a specific account including current balance.
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/accountIdentifier'
      responses:
        '200':
          description: Account details with balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
    patch:
      operationId: updateAccount
      summary: Update Account
      description: Modify settings for an existing account.
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/accountIdentifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAccountRequest'
      responses:
        '200':
          description: Account updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
  /customers/{customerIdentifier}/accounts/{accountIdentifier}/lowbalance:
    post:
      operationId: createLowBalanceAlert
      summary: Create Low Balance Alert
      description: Set a low balance alert threshold for an account.
      tags:
        - Low Balance Alerts
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/accountIdentifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LowBalanceAlertRequest'
      responses:
        '201':
          description: Alert created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LowBalanceAlert'
    get:
      operationId: listLowBalanceAlerts
      summary: List Low Balance Alerts
      description: List all low balance alerts for a specific account.
      tags:
        - Low Balance Alerts
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/accountIdentifier'
      responses:
        '200':
          description: List of low balance alerts
          content:
            application/json:
              schema:
                type: object
                properties:
                  alerts:
                    type: array
                    items:
                      $ref: '#/components/schemas/LowBalanceAlert'
  /customers/{customerIdentifier}/accounts/{accountIdentifier}/lowbalance/{balanceAlertID}:
    get:
      operationId: getLowBalanceAlert
      summary: Get Low Balance Alert
      description: Retrieve a specific low balance alert.
      tags:
        - Low Balance Alerts
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/accountIdentifier'
        - $ref: '#/components/parameters/balanceAlertID'
      responses:
        '200':
          description: Low balance alert details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LowBalanceAlert'
    patch:
      operationId: updateLowBalanceAlert
      summary: Update Low Balance Alert
      description: Update an existing low balance alert threshold.
      tags:
        - Low Balance Alerts
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/accountIdentifier'
        - $ref: '#/components/parameters/balanceAlertID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LowBalanceAlertRequest'
      responses:
        '200':
          description: Alert updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LowBalanceAlert'
    delete:
      operationId: deleteLowBalanceAlert
      summary: Delete Low Balance Alert
      description: Remove a low balance alert from an account.
      tags:
        - Low Balance Alerts
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/accountIdentifier'
        - $ref: '#/components/parameters/balanceAlertID'
      responses:
        '204':
          description: Alert deleted
  /creditCardDeposits:
    post:
      operationId: createCreditCardDeposit
      summary: Create Credit Card Deposit
      description: Fund an account by processing a credit card deposit.
      tags:
        - Funding
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditCardDepositRequest'
      responses:
        '201':
          description: Deposit created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditCardDeposit'
  /creditCardDeposits/{depositId}:
    get:
      operationId: getCreditCardDeposit
      summary: Get Credit Card Deposit
      description: Retrieve details of a specific credit card deposit.
      tags:
        - Funding
      parameters:
        - name: depositId
          in: path
          required: true
          schema:
            type: string
          description: The deposit identifier
      responses:
        '200':
          description: Deposit details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditCardDeposit'
  /creditCards:
    get:
      operationId: listCreditCards
      summary: List Credit Cards
      description: List all registered credit cards on the account.
      tags:
        - Funding
      responses:
        '200':
          description: List of registered credit cards
          content:
            application/json:
              schema:
                type: object
                properties:
                  creditCards:
                    type: array
                    items:
                      $ref: '#/components/schemas/CreditCard'
    post:
      operationId: registerCreditCard
      summary: Register Credit Card
      description: Register a new credit card for funding.
      tags:
        - Funding
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterCreditCardRequest'
      responses:
        '201':
          description: Credit card registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditCard'
  /creditCards/{token}:
    get:
      operationId: getCreditCard
      summary: Get Credit Card
      description: Retrieve details of a specific registered credit card.
      tags:
        - Funding
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: The credit card token
      responses:
        '200':
          description: Credit card details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditCard'
  /transferFunds:
    get:
      operationId: listFundTransfers
      summary: List Fund Transfers
      description: List fund transfer history for the account.
      tags:
        - Funding
      responses:
        '200':
          description: List of fund transfers
          content:
            application/json:
              schema:
                type: object
                properties:
                  transfers:
                    type: array
                    items:
                      $ref: '#/components/schemas/FundTransfer'
  /catalogs:
    get:
      operationId: getCatalog
      summary: Get Catalog
      description: >-
        Retrieve the full digital reward catalog including all available
        brands and products accessible to the authenticated customer.
      tags:
        - Catalog
      responses:
        '200':
          description: Full reward catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  brands:
                    type: array
                    items:
                      $ref: '#/components/schemas/Brand'
  /brandCategories:
    get:
      operationId: listBrandCategories
      summary: List Brand Categories
      description: Retrieve all available brand categories for catalog filtering.
      tags:
        - Catalog
      responses:
        '200':
          description: List of brand categories
          content:
            application/json:
              schema:
                type: object
                properties:
                  brandCategories:
                    type: array
                    items:
                      $ref: '#/components/schemas/BrandCategory'
  /choiceProducts:
    get:
      operationId: listChoiceProducts
      summary: List Choice Products
      description: List all available Tango Choice products.
      tags:
        - Catalog
      responses:
        '200':
          description: List of Choice products
          content:
            application/json:
              schema:
                type: object
                properties:
                  choiceProducts:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChoiceProduct'
  /choiceProducts/{utid}:
    get:
      operationId: getChoiceProduct
      summary: Get Choice Product
      description: Retrieve details of a specific Choice product.
      tags:
        - Catalog
      parameters:
        - name: utid
          in: path
          required: true
          schema:
            type: string
          description: The unique product identifier (UTID)
      responses:
        '200':
          description: Choice product details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChoiceProduct'
  /orders:
    get:
      operationId: listOrders
      summary: List Orders
      description: Retrieve a list of orders placed by the account.
      tags:
        - Orders
      parameters:
        - name: startDate
          in: query
          schema:
            type: string
            format: date-time
          description: Filter orders from this date
        - name: endDate
          in: query
          schema:
            type: string
            format: date-time
          description: Filter orders up to this date
        - name: elements
          in: query
          schema:
            type: integer
            default: 100
          description: Number of results per page
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Pagination offset
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
    post:
      operationId: createOrder
      summary: Create Order
      description: >-
        Place a new reward order. This deducts the reward value from the
        specified account balance and delivers the digital reward to the
        recipient.
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order placed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/BadRequest'
  /orders/{referenceOrderID}:
    get:
      operationId: getOrder
      summary: Get Order
      description: Retrieve details of a specific order by reference ID.
      tags:
        - Orders
      parameters:
        - $ref: '#/components/parameters/referenceOrderID'
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /orders/{referenceOrderID}/resends:
    post:
      operationId: resendOrder
      summary: Resend Order
      description: Resend a fulfilled order to the recipient.
      tags:
        - Orders
      parameters:
        - $ref: '#/components/parameters/referenceOrderID'
      responses:
        '200':
          description: Order resent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /lineItems:
    get:
      operationId: listLineItems
      summary: List Line Items
      description: Retrieve a list of all order line items.
      tags:
        - Line Items
      parameters:
        - name: startDate
          in: query
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          schema:
            type: string
            format: date-time
        - name: elements
          in: query
          schema:
            type: integer
            default: 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of line items
          content:
            application/json:
              schema:
                type: object
                properties:
                  lineItems:
                    type: array
                    items:
                      $ref: '#/components/schemas/LineItem'
  /lineItems/reasonCodes:
    get:
      operationId: listLineItemReasonCodes
      summary: List Line Item Reason Codes
      description: Retrieve available reason codes for line item status changes.
      tags:
        - Line Items
      responses:
        '200':
          description: List of reason codes
          content:
            application/json:
              schema:
                type: object
                properties:
                  reasonCodes:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReasonCode'
  /lineItems/{referenceLineItemId}:
    get:
      operationId: getLineItem
      summary: Get Line Item
      description: Retrieve details of a specific order line item.
      tags:
        - Line Items
      parameters:
        - $ref: '#/components/parameters/referenceLineItemId'
      responses:
        '200':
          description: Line item details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineItem'
    patch:
      operationId: updateLineItem
      summary: Update Line Item
      description: Update metadata or status on a line item.
      tags:
        - Line Items
      parameters:
        - $ref: '#/components/parameters/referenceLineItemId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                notes:
                  type: string
      responses:
        '200':
          description: Line item updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineItem'
  /lineItems/{referenceLineItemId}/cancel:
    post:
      operationId: cancelLineItem
      summary: Cancel Line Item
      description: Cancel a pending line item before fulfillment.
      tags:
        - Line Items
      parameters:
        - $ref: '#/components/parameters/referenceLineItemId'
      responses:
        '200':
          description: Line item cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineItem'
  /lineItems/{referenceLineItemId}/freeze:
    post:
      operationId: freezeLineItem
      summary: Freeze Line Item
      description: Freeze a line item to temporarily suspend delivery.
      tags:
        - Line Items
      parameters:
        - $ref: '#/components/parameters/referenceLineItemId'
      responses:
        '200':
          description: Line item frozen
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineItem'
  /lineItems/{referenceLineItemId}/unfreeze:
    post:
      operationId: unfreezeLineItem
      summary: Unfreeze Line Item
      description: Unfreeze a previously frozen line item to resume delivery.
      tags:
        - Line Items
      parameters:
        - $ref: '#/components/parameters/referenceLineItemId'
      responses:
        '200':
          description: Line item unfrozen
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineItem'
  /lineItems/{referenceLineItemId}/reissue:
    post:
      operationId: reissueLineItem
      summary: Reissue Line Item
      description: Reissue a failed or expired line item.
      tags:
        - Line Items
      parameters:
        - $ref: '#/components/parameters/referenceLineItemId'
      responses:
        '200':
          description: Line item reissued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineItem'
  /lineItems/{referenceLineItemId}/resends:
    post:
      operationId: resendLineItem
      summary: Resend Line Item
      description: Resend a fulfilled line item to the recipient.
      tags:
        - Line Items
      parameters:
        - $ref: '#/components/parameters/referenceLineItemId'
      responses:
        '200':
          description: Line item resent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineItem'
  /digitalTemplates:
    get:
      operationId: listDigitalTemplates
      summary: List Digital Templates
      description: List all configured digital email delivery templates.
      tags:
        - Digital Templates
      responses:
        '200':
          description: List of digital templates
          content:
            application/json:
              schema:
                type: object
                properties:
                  templates:
                    type: array
                    items:
                      $ref: '#/components/schemas/DigitalTemplate'
    post:
      operationId: createDigitalTemplate
      summary: Create Digital Template
      description: Create a new email delivery template for reward notifications.
      tags:
        - Digital Templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDigitalTemplateRequest'
      responses:
        '201':
          description: Template created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DigitalTemplate'
  /digitalTemplates/{etid}:
    get:
      operationId: getDigitalTemplate
      summary: Get Digital Template
      description: Retrieve a specific digital email template by ID.
      tags:
        - Digital Templates
      parameters:
        - $ref: '#/components/parameters/etid'
      responses:
        '200':
          description: Template details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DigitalTemplate'
    patch:
      operationId: updateDigitalTemplate
      summary: Update Digital Template
      description: Update an existing digital email template.
      tags:
        - Digital Templates
      parameters:
        - $ref: '#/components/parameters/etid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDigitalTemplateRequest'
      responses:
        '200':
          description: Template updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DigitalTemplate'
    delete:
      operationId: deleteDigitalTemplate
      summary: Delete Digital Template
      description: Delete a digital email template.
      tags:
        - Digital Templates
      parameters:
        - $ref: '#/components/parameters/etid'
      responses:
        '204':
          description: Template deleted
  /exchangerates:
    get:
      operationId: getExchangeRates
      summary: Get Exchange Rates
      description: Retrieve current exchange rates for all supported currencies.
      tags:
        - Reference Data
      responses:
        '200':
          description: Current exchange rates
          content:
            application/json:
              schema:
                type: object
                properties:
                  exchangeRates:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExchangeRate'
  /rewardCountries:
    get:
      operationId: listRewardCountries
      summary: List Reward Countries
      description: List all countries where digital rewards can be delivered.
      tags:
        - Reference Data
      responses:
        '200':
          description: List of supported reward countries
          content:
            application/json:
              schema:
                type: object
                properties:
                  countries:
                    type: array
                    items:
                      $ref: '#/components/schemas/RewardCountry'
  /credentialtypes:
    get:
      operationId: listCredentialTypes
      summary: List Credential Types
      description: Retrieve available credential types for reward delivery.
      tags:
        - Reference Data
      responses:
        '200':
          description: List of credential types
          content:
            application/json:
              schema:
                type: object
                properties:
                  credentialTypes:
                    type: array
                    items:
                      $ref: '#/components/schemas/CredentialType'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth using platform credentials (username/password)
  parameters:
    customerIdentifier:
      name: customerIdentifier
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier for the customer
    accountIdentifier:
      name: accountIdentifier
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier for the account
    balanceAlertID:
      name: balanceAlertID
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier for the low balance alert
    referenceOrderID:
      name: referenceOrderID
      in: path
      required: true
      schema:
        type: string
      description: The reference order ID
    referenceLineItemId:
      name: referenceLineItemId
      in: path
      required: true
      schema:
        type: string
      description: The reference line item ID
    etid:
      name: etid
      in: path
      required: true
      schema:
        type: string
      description: Email template ID
  responses:
    BadRequest:
      description: Bad request - invalid parameters or missing required fields
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        requestId:
          type: string
        path:
          type: string
        httpStatusCode:
          type: integer
        httpStatus:
          type: string
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
    Customer:
      type: object
      properties:
        customerIdentifier:
          type: string
          description: Unique customer identifier
        displayName:
          type: string
          description: Customer display name
        status:
          type: string
          enum:
            - active
            - inactive
          description: Customer status
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateCustomerRequest:
      type: object
      required:
        - customerIdentifier
        - displayName
      properties:
        customerIdentifier:
          type: string
          description: Unique identifier for the new customer
        displayName:
          type: string
          description: Display name for the customer
    Account:
      type: object
      properties:
        accountIdentifier:
          type: string
          description: Unique account identifier
        customerIdentifier:
          type: string
          description: Parent customer identifier
        displayName:
          type: string
          description: Account display name
        currencyCode:
          type: string
          description: ISO 4217 currency code
        currentBalance:
          type: number
          format: double
          description: Current account balance
        status:
          type: string
          enum:
            - active
            - inactive
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateAccountRequest:
      type: object
      required:
        - accountIdentifier
        - displayName
      properties:
        accountIdentifier:
          type: string
        displayName:
          type: string
        currencyCode:
          type: string
          default: USD
    UpdateAccountRequest:
      type: object
      properties:
        displayName:
          type: string
        status:
          type: string
          enum:
            - active
            - inactive
    LowBalanceAlert:


# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tango/refs/heads/main/openapi/tango-raas-api-openapi.yml