openapi: 3.2.0
info:
  title: Weel Open Budget Topups API
  version: v1
  termsOfService: https://letsweel.com/terms/
  contact:
    name: Contact our support
    email: help@letsweel.com
    url: https://help.letsweel.com
  description: 'The Weel OpenAPI empowers businesses with seamless expense management and real-time insights. Our platform makes it easy to integrate and automate expense workflows, manage receipts, and keep track of spending across your organization.

    '
servers:
- url: https://public.letsweel.com
security:
- BearerAuth: []
tags:
- name: Budget Topups
  description: "This group of endpoints allows you to retrieve and create budget topups. Topups are used to increase or decrease the available amount of a budget or budget member.\n\nTopups will be automatically approved, unless a Workflow or Policy has been configured in Weel for that requires approval for budget topups.\n\nThere are two types of topups:\n  - Budget topups are used to increase or decrease the available amount of a budget. This is only permitted when `has_member_limits` is `false` for the budget.\n  - Budget member topups are used to increase or decrease the available amount of a budget member. This is only permitted when `has_member_limits` is `true` for the budget.\n\n`has_member_limits` is set to `true` when this toggle is enabled in the budget creation form.\n  ![Has Member Limits is true](assets/has-member-limits-true.png)\n"
paths:
  /v1/businesses/{client_id}/budgets/{budget_id}/topups:
    get:
      operationId: listBudgetTopups
      tags:
      - Budget Topups
      summary: List budget topups
      description: List the topups for a budget.
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/BudgetId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetTopupListResponse'
    post:
      operationId: createBudgetTopup
      tags:
      - Budget Topups
      summary: Create budget topup
      description: Increase or decrease the available amount of a budget. Only permitted when `has_member_limits` is `false` for the budget.
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/BudgetId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BudgetTopupCreate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetTopup'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  non_field_errors:
                    type: array
                    items:
                      type: string
                      example: Cannot topup budget with member limits
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - BearerAuth: []
  /v1/businesses/{client_id}/budgets/{budget_id}/members/{budget_member_id}/topups:
    get:
      operationId: listBudgetMemberTopups
      tags:
      - Budget Topups
      summary: List budget member topups
      description: List the topups for a budget member.
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/BudgetId'
      - $ref: '#/components/parameters/BudgetMemberId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetTopupListResponse'
    post:
      operationId: createBudgetMemberTopup
      tags:
      - Budget Topups
      summary: Create budget member topup
      description: Increase or decrease the available amount of a budget member. Only permitted when `has_member_limits` is `true` for the budget.
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/BudgetId'
      - $ref: '#/components/parameters/BudgetMemberId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BudgetTopupCreate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetTopup'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  non_field_errors:
                    type: array
                    items:
                      type: string
                      example: Cannot topup budget member when budget does not have member limits
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - BearerAuth: []
components:
  parameters:
    BudgetId:
      name: budget_id
      in: path
      description: The ID of the budget.
      required: true
      schema:
        type: string
    ClientId:
      name: client_id
      in: path
      description: The ID of the business.
      required: true
      schema:
        type: integer
        example: 123
    BudgetMemberId:
      name: budget_member_id
      in: path
      description: The ID of the budget member.
      required: true
      schema:
        type: integer
  schemas:
    SubUser:
      type:
      - object
      - 'null'
      properties:
        id:
          type: integer
          description: The ID of the user.
          example: 123
        first_name:
          type: string
          description: The first name of the user.
          example: John
        last_name:
          type: string
          description: The last name of the user.
          example: Doe
        name:
          type: string
          description: The full name of the user or the display name if the user has set one.
          example: John Doe
    BudgetTopupListResponse:
      type: object
      properties:
        count:
          type: integer
          description: The total number of topups that match the query.
          example: 100
        next:
          type: string
          description: The URL to the next page of topups.
          example: offset=50&limit=50
        previous:
          type: string
          description: The URL to the previous page of topups.
          example: offset=0&limit=50
        results:
          type: array
          items:
            $ref: '#/components/schemas/BudgetTopup'
    BudgetTopup:
      type: object
      properties:
        id:
          type: string
          description: The ID of the topup.
          example: e33b7c61-5124-4ba0-b238-e4c573133715
        amount:
          type: number
          description: Positive values increase the available amount, negative values decrease it.
          example: 100
        description:
          type: string
          description: The description of the topup.
          example: Additional funds for travel
        status:
          type: string
          description: The status of the topup.
          enum:
          - APPROVED
          - CANCELLED
          - DECLINED
          - PENDING
          example: APPROVED
        requested_by:
          description: The user who requested the topup.
          $ref: '#/components/schemas/SubUser'
        actioned_by:
          description: The user who actioned an approval or decline of the topup.
          $ref: '#/components/schemas/SubUser'
        actioned_on:
          type: string
          format: date-time
          description: The date and time when the topup was actioned in UTC.
          example: '2024-01-01T00:00:00Z'
        created:
          type: string
          format: date-time
          description: The date and time when the topup was created in UTC.
          example: '2024-01-01T00:00:00Z'
        updated:
          type: string
          format: date-time
          description: The date and time when the topup was last updated in UTC.
          example: '2024-01-01T00:00:00Z'
    BudgetTopupCreate:
      type: object
      required:
      - amount
      - description
      properties:
        amount:
          type: number
          description: Positive values increase the available amount, negative values decrease it.
          example: 100
        description:
          type: string
          description: The description of the topup.
          example: Additional funds for travel
        auto_approve:
          type: boolean
          description: By default, topups require approval before being added to the budget. Set this to `true` to automatically add the topup to the budget.
          example: true
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
x-tagGroups:
- name: Users
  tags:
  - Invites
  - Users
  - Roles
- name: Transactions
  tags:
  - Transactions
- name: Budgets
  tags:
  - Budgets
  - Budget Members
  - Budget Owners
  - Budget Topups
- name: Statements
  tags:
  - Statements
- name: Custom Fields
  tags:
  - Custom Fields
  - Custom Field Options
  - Custom Field Budgets
- name: Chart of Accounts
  tags:
  - Accounting Codes
  - Categories