openapi: 3.0.3
info:
  title: Guusto Gifts API
  description: >-
    The Guusto Gifts API lets you programmatically send digital gifts, track
    order status, retrieve reward budgets, and pull recognition activity and
    manager-insight reports from the Guusto employee recognition and rewards
    platform. API access is available on the Guusto Premium plan. All requests
    are authenticated with a Bearer API token and an X-Workspace-id header. This
    document models Guusto's publicly documented REST surface
    (docs.guusto.com); request and response schemas are summarized from the
    published API reference and may not capture every field.
  version: '1.0'
  contact:
    name: Guusto
    url: https://guusto.com
  termsOfService: https://guusto.com/terms
servers:
  - url: https://api.guusto.com/api/v1
    description: Production
  - url: https://api-demo.guusto.io/api/v1
    description: Demo / Test
security:
  - bearerAuth: []
tags:
  - name: Order Gift
    description: Order digital gifts and track order status.
  - name: Account Budget
    description: Retrieve available reward budget balances.
  - name: Reports
    description: Recognition activity and manager-insight reports.
paths:
  /orders:
    post:
      tags:
        - Order Gift
      summary: Order gifts
      description: >-
        Submit an order of one to twenty gift items. Each item carries a
        message, an amount, and a recipient identified by email or employee
        number (email takes precedence when both are present).
      operationId: createOrder
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CustomerRequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '201':
          description: Order accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Invalid request.
        '401':
          description: Missing or invalid authentication.
  /orders/status/{requestId}:
    get:
      tags:
        - Order Gift
      summary: Get order status
      description: Retrieve the processing status of a previously submitted order.
      operationId: getOrderStatus
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: requestId
          in: path
          required: true
          description: The order tracking ID returned when the order was created.
          schema:
            type: string
      responses:
        '200':
          description: Order status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '404':
          description: Order not found.
  /orders/{requestId}:
    get:
      tags:
        - Order Gift
      summary: Get order
      description: Retrieve the full details of a previously submitted order.
      operationId: getOrder
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: requestId
          in: path
          required: true
          description: The order tracking ID returned when the order was created.
          schema:
            type: string
      responses:
        '200':
          description: Order details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '404':
          description: Order not found.
  /balances/workspaces/currencies/{currency}:
    get:
      tags:
        - Account Budget
      summary: Get workspace budget
      description: Retrieve the available reward budget balance for the workspace.
      operationId: getWorkspaceBudget
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/Currency'
      responses:
        '200':
          description: Available workspace budget.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
  /balances/members/{employeeNumber}/currencies/{currency}:
    get:
      tags:
        - Account Budget
      summary: Get member budget
      description: Retrieve the available reward budget balance for a single member.
      operationId: getMemberBudget
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: employeeNumber
          in: path
          required: true
          description: The member's employee number.
          schema:
            type: string
        - $ref: '#/components/parameters/Currency'
      responses:
        '200':
          description: Available member budget.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
  /balances/members/currencies/{currency}:
    get:
      tags:
        - Account Budget
      summary: Get all member budgets
      description: Retrieve paginated available reward budget balances for all members.
      operationId: listMemberBudgets
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/Currency'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: Paginated member budgets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberBalancePage'
  /reports/teams/activity:
    get:
      tags:
        - Reports
      summary: Get team activity
      description: >-
        Retrieve a paginated list of workspace recognition activities including
        sender, receiver, status, description, reason, and timestamps.
      operationId: getTeamActivity
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: Paginated activity list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
  /reports/members/last-recognized:
    get:
      tags:
        - Reports
      summary: Get last recognized by manager
      description: >-
        Retrieve a paginated list of team members with the last time they were
        recognized by their managers. This manager-insight resource is rate
        limited.
      operationId: getLastRecognized
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: Paginated last-recognized list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '429':
          description: Request limit reached for the manager-insight resource.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer API token issued from the Guusto workspace (Premium plan).
  parameters:
    WorkspaceId:
      name: X-Workspace-id
      in: header
      required: true
      description: The workspace the request is scoped to.
      schema:
        type: string
    CustomerRequestId:
      name: X-Customer-Request-Id
      in: header
      required: false
      description: Optional idempotency / correlation identifier supplied by the caller.
      schema:
        type: string
    Currency:
      name: currency
      in: path
      required: true
      description: ISO currency code supported by Guusto.
      schema:
        type: string
        enum:
          - CAD
          - USD
    Page:
      name: page
      in: query
      required: false
      description: Zero-based page index.
      schema:
        type: integer
        default: 0
    Size:
      name: size
      in: query
      required: false
      description: Page size.
      schema:
        type: integer
        default: 20
  schemas:
    OrderRequest:
      type: object
      required:
        - orderItems
        - currency
      properties:
        orderItems:
          type: array
          minItems: 1
          maxItems: 20
          items:
            $ref: '#/components/schemas/OrderItem'
        currency:
          type: string
          enum:
            - CAD
            - USD
        language:
          type: string
          enum:
            - ES_MX
            - FR_CA
            - EN_CA
          description: Optional language for the gift experience.
    OrderItem:
      type: object
      required:
        - message
        - amount
        - recipient
      properties:
        message:
          type: string
          description: Message shown to the recipient.
        amount:
          type: number
          minimum: 1
          maximum: 10000
          description: Gift amount.
        recipient:
          $ref: '#/components/schemas/Recipient'
    Recipient:
      type: object
      description: >-
        The gift recipient, identified by employeeNumber or email (email takes
        precedence when both are supplied).
      properties:
        firstName:
          type: string
        lastName:
          type: string
        employeeNumber:
          type: string
        email:
          type: string
          format: email
    OrderResponse:
      type: object
      properties:
        requestId:
          type: string
          description: Order tracking ID.
        requestStatus:
          type: string
          enum:
            - ACCEPTED
            - WAITING_PROCESSING
            - PROCESSING_IN_PROGRESS
            - COMPLETED
            - FAILED
        orderStep:
          type: string
          description: Current processing step, e.g. PENDING, PRECHECK_ORDER, COMPLETED.
        orderId:
          type: integer
        customerRequestId:
          type: string
    Balance:
      type: object
      properties:
        amount:
          type: number
          description: Available budget amount.
        currency:
          type: string
          enum:
            - CAD
            - USD
    MemberBalancePage:
      allOf:
        - $ref: '#/components/schemas/Page'
        - type: object
          properties:
            memberBalanceResponses:
              type: array
              items:
                type: object
                properties:
                  amount:
                    type: number
                  employeeNumber:
                    type: string
                  user:
                    type: object
    Page:
      type: object
      properties:
        page:
          type: integer
        size:
          type: integer
        totalElements:
          type: integer
        totalPages:
          type: integer