openapi: 3.1.0
info:
  title: Tango RaaS Accounts Orders API
  description: 'The Tango Rewards as a Service (RaaS) REST API enables businesses to programmatically send gift cards, manage reward orders, fund accounts, access the global reward catalog, configure webhooks, and track delivery status for digital rewards and incentive programs.

    '
  version: v2
  contact:
    name: Tango Card 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 / Integration
security:
- basicAuth: []
tags:
- name: Orders
  description: Reward order creation and management
paths:
  /orders:
    get:
      operationId: listOrders
      summary: List orders
      description: Retrieve a list of reward orders.
      tags:
      - Orders
      parameters:
      - name: accountIdentifier
        in: query
        schema:
          type: string
        description: Filter by account identifier
      - name: startDate
        in: query
        schema:
          type: string
          format: date-time
        description: Filter orders created after this date
      - name: endDate
        in: query
        schema:
          type: string
          format: date-time
        description: Filter orders created before this date
      - name: elementsPerBlock
        in: query
        schema:
          type: integer
        description: Number of results per page
      - name: page
        in: query
        schema:
          type: integer
        description: Page number for pagination
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  totalCount:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createOrder
      summary: Create an order
      description: Place a new reward order to send a gift card or incentive.
      tags:
      - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /orders/{referenceOrderID}:
    get:
      operationId: getOrder
      summary: Get an order
      description: Retrieve a specific order by reference order ID.
      tags:
      - Orders
      parameters:
      - name: referenceOrderID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /orders/{referenceOrderID}/resends:
    post:
      operationId: resendOrder
      summary: Resend an order
      description: Resend the reward delivery for a specific order.
      tags:
      - Orders
      parameters:
      - name: referenceOrderID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: Override email address for resend
      responses:
        '200':
          description: Order resent
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    LineItem:
      type: object
      description: Represents a line item within an order
      properties:
        referenceLineItemId:
          type: string
          description: Unique reference identifier for the line item
        referenceOrderID:
          type: string
          description: Parent order reference identifier
        status:
          type: string
          enum:
          - PENDING
          - FULFILLED
          - CANCELLED
          - FROZEN
          - FAILED
          description: Current status of the line item
        amount:
          type: number
          format: double
          description: Line item amount
        currencyCode:
          type: string
          description: ISO 4217 currency code
        utid:
          type: string
          description: Universal Token ID of the reward item
        createdAt:
          type: string
          format: date-time
    RecipientInfo:
      type: object
      properties:
        firstName:
          type: string
          description: Recipient first name
        lastName:
          type: string
          description: Recipient last name
        email:
          type: string
          format: email
          description: Recipient email address
    Error:
      type: object
      description: API error response
      properties:
        timestamp:
          type: string
          format: date-time
        status:
          type: integer
          description: HTTP status code
        error:
          type: string
          description: Short error description
        message:
          type: string
          description: Detailed error message
        path:
          type: string
          description: Request path that caused the error
    OrderCreate:
      type: object
      required:
      - customerIdentifier
      - accountIdentifier
      - amount
      - utid
      properties:
        customerIdentifier:
          type: string
          description: Customer placing the order
        accountIdentifier:
          type: string
          description: Account to charge for the order
        amount:
          type: number
          format: double
          description: Reward amount
        currencyCode:
          type: string
          description: ISO 4217 currency code (default USD)
        utid:
          type: string
          description: Universal Token ID of the reward item
        recipientInfo:
          $ref: '#/components/schemas/RecipientInfo'
        sendEmail:
          type: boolean
          description: Whether to send the reward via email
        notes:
          type: string
          description: Internal notes for the order
        externalRefID:
          type: string
          description: External reference identifier
    Order:
      type: object
      description: Represents a reward order
      properties:
        referenceOrderID:
          type: string
          description: Unique reference identifier for the order
        orderStatus:
          type: string
          enum:
          - PENDING
          - FULFILLED
          - FAILED
          - CANCELLED
          description: Current status of the order
        customerIdentifier:
          type: string
          description: Customer who placed the order
        accountIdentifier:
          type: string
          description: Account charged for the order
        amount:
          type: number
          format: double
          description: Total order amount
        currencyCode:
          type: string
          description: ISO 4217 currency code
        utid:
          type: string
          description: Universal Token ID for the reward item
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the order was created
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth using platform name and API key
    oAuth2:
      type: oauth2
      description: OAuth 2.0 client credentials flow for more secure integrations
      flows:
        clientCredentials:
          tokenUrl: https://auth.tangocard.com/oauth/token
          scopes: {}
externalDocs:
  description: Tango Developer Portal
  url: https://developers.tangocard.com/docs/api-endpoint-overview