openapi: 3.0.0
info:
  title: Billing API
  contact:
    name: API Integration Support
    email: integration@dintero.com
  description: |
    # Changelog
    All notable changes to the API.

    ## 2025-12-15

    > **new** Add new endpoint to trigger generating settlement report in test.
    > - [POST /v1/accounts/{aid}/settlements/reports/generate-test-report](/api-reference/settlements/aid_settlement_generate_test_report)

    ## 2025-10-01

    > Extend billing subscription price definition with optional `price_model`
    > field. The field can be used to define how the price is applied
    > - [GET /v1/accounts/{aid}/billing/subscriptions](/billing-api/subscriptions/aid_billing_subscriptions_get)

    > Add support for filtering subscriptions by dimensions
    > - [GET /v1/accounts/{aid}/billing/subscriptions](/billing-api/subscriptions/aid_billing_subscriptions_get)

    ## 2024-12-20

    > Add support for filtering settlements by `item_created_at.gte`
    > and `item_created_at.lte`. The new filter enables getting list of settlement
    > by when they was created, the existing support for `created_at.gte`/`created_at.lte`
    > filters by when they was settled (`settled_at`)
    > - [GET /v1/accounts/{aid}/settlements](/api-reference/settlements/aid_settlements_list)

    ## 2024-06-01
    > Add pagination to report configuration listing
    > - [GET /v1/accounts/{aid}/settlements/reports/configuration](/api-reference/settlementsconfiguration/aid_settlement_report_config_list)

    ## 2023-04-01
    > **new** Add filter on `namespace` and `currency`
    > - [GET /v1/accounts/{aid}/billing/subscriptions](/billing-api/subscriptions/aid_billing_subscriptions_get)

    ## 2022-06-01

    > **new** Add filter on `payout_destination_id`
    > - [GET /v1/accounts/{aid}/settlements](/api-reference/settlements/aid_settlements_list)

    ## 2022-04-01

    > **new** Add possibility to delete report configurations
    > - [DELETE /v1/accounts/{aid}/settlements/reports/configuration/{configuration_id}](/api-reference/settlementsconfiguration/aid_settlement_report_config_delete)

    > **new** Add `destination_type: email` and support filter on `payout_destination_id` on settlement report configs
    > - [POST /v1/accounts/{aid}/settlements/reports/configuration](/api-reference/settlementsconfiguration/aid_settlement_report_config_create)
    > - [GET /v1/accounts/{aid}/settlements/reports/configuration](/api-reference/settlementsconfiguration/aid_settlement_report_config_list)
    > - [PUT /v1/accounts/{aid}/settlements/reports/configuration/{configuration_id}](/api-reference/settlementsconfiguration/aid_settlement_report_config_list)

    ## 2020-12-01

    > **new** Support filter user payout rules with `include_deleted` query parameter.
    > - [GET /v1/accounts/{aid}/billing/payout-rules?include_deleted=false](/billing-api/payoutrules/aid_billing_payout_rules_get)

    ## 2020-05-01

    > **[Payout Rules](#tag/payout.rules)**
    > Add new endpoint for managing Payout rules.
  version: LATEST
  license:
    name: UNLICENSED
    url: https://dintero.com
  x-logo:
    url: https://docs.dintero.com/img/dintero-dark-padded.svg
    altText: Dintero Logo
security:
  - JWT: []
tags:
  - name: payout.rules
    x-displayName: Rules
    description: Manage payout rules
  - name: reports
    x-displayName: Reports
    description: Get billing reports
  - name: subscriptions
    x-displayName: Plans
    description: Get subscription plans
  - name: settlements
    x-displayName: Reports
    description: Get settlement reports
  - name: settlements.configuration
    x-displayName: Configuration
    description: Configure settlement reports
paths:
  /accounts/{aid}/billing/costs:
    get:
      operationId: aid_billing_cost_get
      summary: aid_billing_cost_get
      description: |
        Get the costs aggregated by periode

        *scopes*:
          - admin:billing
          - read:billing
      x-scopes:
        - admin:billing
        - read:billing
      tags:
        - reports
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/limit1k'
        - $ref: '#/components/parameters/startingAfter'
        - name: year
          in: query
          required: true
          description: |
            filter result by year
          example: 2019
          schema:
            type: integer
        - name: month
          in: query
          required: true
          description: |
            filter result by month
          example: 8
          schema:
            type: integer
            minimum: 1
            maximum: 12
        - name: type
          in: query
          description: |
            filter result by cost type
          example: checkout/capture
          schema:
            type: string
        - name: date
          in: query
          description: |
            filter result by date, requires to be combined with type parameter
          schema:
            type: string
            format: date
      responses:
        '200':
          $ref: '#/components/responses/BillingCostList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: List costs
          sidebarTitle: List costs
  /accounts/{aid}/billing/payout-rules:
    get:
      operationId: aid_billing_payout_rules_get
      summary: aid_billing_payout_rules_get
      description: |
        Get payout rules

        *scopes*:
          - admin:billing
          - read:billing
      x-scopes:
        - admin:billing
        - read:billing
      tags:
        - payout.rules
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/limit1k'
        - $ref: '#/components/parameters/startingAfter'
        - name: rule_type
          in: query
          description: |
            Filter payment rules by rule_type
          schema:
            type: string
        - name: rule_id
          in: query
          description: |
            Filter payment rules by rule_id. Must be used together
            with `rule_type`.
          schema:
            type: string
        - name: include_deleted
          description: |
            include deleted payout rules in the response
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          $ref: '#/components/responses/PayoutRulesList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: List payout rules
          sidebarTitle: List payout rules
    post:
      operationId: aid_billing_payout_rules_post
      summary: aid_billing_payout_rules_post
      description: |
        Create payout rules

        *scopes*:
          - admin:billing
          - write:billing
      x-scopes:
        - admin:billing
        - write:billing
      tags:
        - payout.rules
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        $ref: '#/components/requestBodies/BillingPayoutRule'
      responses:
        '200':
          $ref: '#/components/responses/PayoutRule'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: Create payout rule
          sidebarTitle: Create payout rule
  /accounts/{aid}/billing/payout-rules/{id}:
    put:
      operationId: aid_billing_payout_rules_id_put
      summary: aid_billing_payout_rules_id_put
      description: |
        Update payout with new destinations
      x-scopes:
        - admin:billing
        - write:billing
      tags:
        - payout.rules
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/ruleId'
      requestBody:
        $ref: '#/components/requestBodies/BillingPayoutRule'
      responses:
        '200':
          $ref: '#/components/responses/PayoutRule'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: Update payout rule
          sidebarTitle: Update payout rule
    delete:
      operationId: aid_billing_payout_rules_id_delete
      summary: aid_billing_payout_rules_id_delete
      description: |
        Remove payout rule
      x-scopes:
        - admin:billing
        - write:billing
      tags:
        - payout.rules
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/ruleId'
      responses:
        '200':
          $ref: '#/components/responses/PayoutRule'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: Remove payout rule
          sidebarTitle: Remove payout rule
  /accounts/{aid}/billing/reports:
    get:
      operationId: aid_billing_reports_get
      summary: aid_billing_reports_get
      description: |
        Get billing reports

        *scopes*:
          - admin:billing
          - read:billing
      x-scopes:
        - admin:billing
        - read:billing
      tags:
        - reports
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/limit1k'
        - $ref: '#/components/parameters/startingAfter'
      responses:
        '200':
          $ref: '#/components/responses/BillingReportsList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: List reports
          sidebarTitle: List reports
  /accounts/{aid}/billing/subscriptions:
    get:
      operationId: aid_billing_subscriptions_get
      summary: aid_billing_subscriptions_get
      description: |
        Get subscriptions

        - Supports filtering by dynamic `dimensions`.

        **filter by dimensions syntax:**
        - `dimension.{name}={value}` to filter by a specific value
        - `dimension.{name}=prefix:{value}` to filter by a specific value prefix
        - `dimension.{name}=val1,val2` comma separated value for OR logic
        - `dimension.{name}` (no value) to filter by presence of the dimension
      x-scopes:
        - admin:billing
        - read:billing
      tags:
        - subscriptions
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/namespace'
        - $ref: '#/components/parameters/currency'
        - $ref: '#/components/parameters/limit1k'
        - $ref: '#/components/parameters/startingAfter'
        - name: dimension.{name}
          in: query
          description: |
            Dynamic query parameters prefixed with `dimension.`.

            **Operators supported:**
            - `=value` → exact match (default)
            - `=prefix:value` → matches if the dimension starts with `value`
            - multiple comma-separated values → OR logic (e.g. `dimension.country=NO,SE`)
            - no value matches any value (`dimension.country=`)

            **Examples:**
            - `?dimension.payment_product_type=dintero_psp.vipps`
            - `?dimension.payment_product_type=prefix:dintero_psp,prefix:bambora.vipps,klarna.klaran`
          explode: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          $ref: '#/components/responses/SubscriptionsList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      x-mint:
        metadata:
          title: List subscription plans
          sidebarTitle: List subscription plans
  /accounts/{aid}/settlements:
    get:
      operationId: aid_settlements_list
      summary: aid_settlements_list
      description: |
        List settlements

        *scopes*:
          - admin:billing
          - read:billing
          - admin:reports
          - read:reports
          - admin:settlements
          - read:settlements
      x-scopes:
        - admin:billing
        - read:billing
        - admin:reports
        - read:reports
        - admin:settlements
        - read:settlements
      tags:
        - settlements
      parameters:
        - $ref: '#/components/parameters/accountId'
        - name: limit
          in: query
          description: |
            A limit on the number of objects to be returned. Limit can range
            between 1 and 1000 items, and the default is 10 items.
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 10
        - name: starting_after_id
          in: query
          description: |
            cursor for use in pagination. starting_after_id is an object ID
            that defines your place in the list, included in the `last_evaluated_key`.

            For instance, if you make a list request and receive 100 objects,
            ending with `obj_foo` and `settled_at=2021-02-02`, your subsequent call
            can include `starting_after_id=obj_foo&starting_after_date=2021-02-02` in
            order to fetch the next page of the list.

            > Note that you need to use the `created_at` as value for `starting_after_date`
            > if used in combination with `item_created_at.gte` or `item_created_at.lte`

            Must be used together with `starting_after_date`
          required: false
          schema:
            type: string
        - name: starting_after_date
          in: query
          description: |
            cursor for use in pagination.
            starting_after_date is the `settled_at` or `created_at` from the
            `last_evaluated_key` that defines your place in the list.
            For instance, if you make a list request and receive 100 objects,
            ending with `obj_foo` and `settled_at=2021-02-02`, your subsequent
            call can include `starting_after_id=obj_foo&starting_after_date=2021-02-02`
            in order to fetch the next page of the list.

            Must be used together with `starting_after_id`
          required: false
          schema:
            type: string
        - name: created_at.gte
          in: query
          description: Settlement created after, the `settled_at` value
          schema:
            type: string
            format: date
        - name: created_at.lte
          in: query
          description: Settlement created before a date, the `settled_at` value
          schema:
            type: string
            format: date
        - name: item_created_at.gte
          in: query
          description: |
            Filter by Settlement `created_at` value, cannot be combined
            with `created_at.gte` query parameter
          schema:
            type: string
            format: date
        - name: item_created_at.lte
          in: query
          description: |
            Filter by Settlement `created_at` value, cannot be combined
            with `created_at.lte` query parameter
          schema:
            type: string
            format: date
        - name: payment_provider
          in: query
          description: The payment provider
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: payout_destination_id
          in: query
          description: The seller id to filter on
          schema:
            type: string
        - name: search
          in: query
          description: Will try to match the search to settlement_id.
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/SettlementsList'
        '400':
          description: |
            Bad request - invalid filters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      servers:
        - url: https://api.dintero.com/v1
      x-mint:
        metadata:
          title: List settlements
          sidebarTitle: List settlements
  /accounts/{aid}/settlements/reports/configuration:
    get:
      operationId: aid_settlement_report_config_list
      summary: aid_settlement_report_config_list
      description: |
        List settlement report configurations

        *scopes*:
          - admin:billing
          - read:billing
          - admin:reports
          - read:reports
          - admin:settlements
          - read:settlements
      x-scopes:
        - admin:billing
        - read:billing
        - admin:reports
        - read:reports
        - admin:settlements
        - read:settlements
      tags:
        - settlements.configuration
      parameters:
        - $ref: '#/components/parameters/accountId'
        - name: starting_after
          in: query
          description: cursor for use in pagination
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/limit1k'
      responses:
        '200':
          $ref: '#/components/responses/SettlementReportConfigList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      servers:
        - url: https://api.dintero.com/v1
      x-mint:
        metadata:
          title: List settlement report configurations
          sidebarTitle: List settlement report configurations
    post:
      operationId: aid_settlement_report_config_create
      summary: aid_settlement_report_config_create
      description: |
        Create settlement report configurations

        *scopes*:
          - admin:billing
          - admin:reports
          - admin:settlements
          - write:settlements
      x-scopes:
        - admin:billing
        - admin:reports
        - admin:settlements
        - write:settlements
      tags:
        - settlements.configuration
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettlementReportConfigItem'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/SettlementReportConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      servers:
        - url: https://api.dintero.com/v1
      x-mint:
        metadata:
          title: Create settlement report configurations
          sidebarTitle: Create settlement report configurations
  /accounts/{aid}/settlements/reports/configuration/{id}:
    get:
      operationId: aid_settlement_report_config_details
      summary: aid_settlement_report_config_details
      description: |
        Get settlement report configuration

        *scopes*:
          - admin:billing
          - read:billing
          - admin:reports
          - read:reports
          - admin:settlements
          - read:settlements
      x-scopes:
        - admin:billing
        - read:billing
        - admin:reports
        - read:reports
        - admin:settlements
        - read:settlements
      tags:
        - settlements.configuration
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/reportConfigId'
      responses:
        '200':
          $ref: '#/components/responses/SettlementReportConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      servers:
        - url: https://api.dintero.com/v1
      x-mint:
        metadata:
          title: Get settlement report configuration
          sidebarTitle: Get settlement report configuration
    put:
      operationId: aid_settlement_report_config_update
      summary: aid_settlement_report_config_update
      description: |
        Update settlement report configuration

        *scopes*:
          - admin:billing
          - write:billing
          - admin:settlements
          - write:settlements
      x-scopes:
        - admin:billing
        - write:billing
        - admin:settlements
        - write:settlements
      tags:
        - settlements.configuration
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/reportConfigId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSettlementReportConfigItem'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/SettlementReportConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      servers:
        - url: https://api.dintero.com/v1
      x-mint:
        metadata:
          title: Update settlement report configuration
          sidebarTitle: Update settlement report configuration
    delete:
      operationId: aid_settlement_report_config_delete
      summary: aid_settlement_report_config_delete
      description: |
        Delete settlement report configuration

        *scopes*:
          - admin:billing
          - write:billing
          - admin:settlements
          - write:settlements
      x-scopes:
        - admin:billing
        - write:billing
        - admin:settlements
        - write:settlements
      tags:
        - settlements.configuration
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/reportConfigId'
      responses:
        '200':
          $ref: '#/components/responses/SettlementReportConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      servers:
        - url: https://api.dintero.com/v1
      x-mint:
        metadata:
          title: Delete settlement report configuration
          sidebarTitle: Delete settlement report configuration
  /accounts/{aid}/settlements/{settlementid}/attachments/{attachmentid}:
    get:
      operationId: settlement_attachment_download
      summary: settlement_attachment_download
      description: |
        Download a settlement attachment

        *scopes*:
          - admin:billing
          - read:billing
          - admin:reports
          - read:reports
          - admin:settlements
          - read:settlements
      x-scopes:
        - admin:billing
        - read:billing
        - admin:reports
        - read:reports
        - admin:settlements
        - read:settlements
      tags:
        - settlements
      parameters:
        - $ref: '#/components/parameters/accountId'
        - name: settlementid
          description: |
            An id that uniquely identifies the settlement.
          in: path
          required: true
          schema:
            type: string
        - name: attachmentid
          description: |
            An id that uniquely identifies the attachment.
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      servers:
        - url: https://api.dintero.com/v1
      x-mint:
        metadata:
          title: Download attachment
          sidebarTitle: Download attachment
  /accounts/{aid}/settlements/reports/generate-test-report:
    post:
      operationId: aid_settlement_generate_test_report
      summary: aid_settlement_generate_test_report
      description: |
        Generate a test settlement report. Only available in test.

        *scopes*:
          - admin:billing
          - admin:reports
      x-scopes:
        - admin:billing
        - admin:reports
      tags:
        - settlements
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestReportOptions'
      responses:
        '200':
          description: |
            No transactions to generate report. This can be if there are
            no new transaction events to generate report for.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestReportResponse'
        '201':
          description: Settlement report created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestReportResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      servers:
        - url: https://api.dintero.com/v1
      x-mint:
        metadata:
          title: Generate a test settlement report
          sidebarTitle: Generate a test settlement report
x-tagGroups:
  - name: Billing
    tags:
      - reports
  - name: Payouts
    tags:
      - payout.rules
  - name: Subscriptions
    tags:
      - subscriptions
  - name: Settlements
    tags:
      - settlements
      - settlements.configuration
servers:
  - url: https://api.dintero.com/v1
components:
  parameters:
    accountId:
      name: aid
      description: |
        An id that uniquely identifies the account.
      in: path
      required: true
      schema:
        type: string
        format: ^[PT]{1}\d{8}$
        minLength: 9
        maxLength: 9
    limit1k:
      name: limit
      in: query
      description: |
        A limit on the number of objects to be returned. Limit can range
        between 1 and 1000 items, and the default is 100 items.
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 100
    startingAfter:
      name: starting_after
      in: query
      description: |
        cursor for use in pagination. starting_after is an object ID
        that defines your place in the list. For instance, if you make
        a list request and receive 100 objects, end the result contains
          `paging_token=pt1`, your subsequent call can include
        `starting_after=pt1` in order to fetch the next page of the list.
      required: false
      schema:
        type: string
    ruleId:
      name: id
      in: path
      required: true
      description: |
        payout rule id
      schema:
        type: string
        format: uuid
    namespace:
      name: namespace
      in: query
      description: Filter subscriptions by namespace
      schema:
        type: string
    currency:
      name: currency
      in: query
      description: |
        Filter subscriptions by prices currency
      example: NOK
      schema:
        type: string
        format: iso-4217
    reportConfigId:
      name: id
      in: path
      required: true
      description: report config id
      schema:
        type: string
        format: uuid
  responses:
    BillingCostList:
      description: Billing Costs List
      headers:
        page-count:
          description: |
            count object in response
          schema:
            type: integer
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/BillingCost'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Unexpected Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PayoutRulesList:
      description: Payout rules
      headers:
        page-count:
          description: |
            count object in response
          schema:
            type: integer
      content:
        application/json:
          schema:
            type: object
            required:
              - payout_rules
            properties:
              starting_after:
                type: string
              payout_rules:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/Object'
                    - $ref: '#/components/schemas/Deleted'
                    - $ref: '#/components/schemas/BillingPayoutRule'
    BadRequest:
      description: Bad / Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PayoutRule:
      description: Payout rule
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Object'
              - $ref: '#/components/schemas/Deleted'
              - $ref: '#/components/schemas/BillingPayoutRule'
    BillingReportsList:
      description: Billing Reports List
      headers:
        page-count:
          description: |
            count object in response
          schema:
            type: integer
      content:
        application/json:
          schema:
            type: object
            required:
              - reports
            properties:
              starting_after:
                type: string
              reports:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/Object'
                    - $ref: '#/components/schemas/BillingReport'
    SubscriptionsList:
      description: Billing Subscriptions List
      headers:
        page-count:
          description: |
            count object in response
          schema:
            type: integer
      content:
        application/json:
          schema:
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/Object'
                - $ref: '#/components/schemas/BillingSubscription'
    SettlementsList:
      description: Settlements List
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SettlementResponse'
    SettlementReportConfigList:
      description: Settlement report configurations list
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SettlementReportConfigResponse'
    SettlementReportConfig:
      description: Settlement report configuration
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SettlementReportConfigItem'
  requestBodies:
    BillingPayoutRule:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BillingPayoutRule'
      required: true
  securitySchemes:
    JWT:
      type: http
      description: |
        Bearer authentication (token authentication) should be used for accessing the API.

        Use [Get Token](/api-reference/authenticate/aid_auths_oauth_token_post) to get an access token for client credentials.
        Pass the token in the request header:

            Authorization: Bearer {access_token}

        where the **access_token** is JSON Web Tokens (JWT).
      scheme: bearer
      bearerFormat: JWT
  schemas:
    BillingDimension:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
          example: payment_product_type
        value:
          type: string
          example: vipps
    BillingPrice:
      type: object
      required:
        - type
        - currency
        - amount
      properties:
        currency:
          type: string
          format: iso4217-code
          example: NOK
          description: |
            The three-character ISO-4217 currency.
            https://en.wikipedia.org/wiki/ISO_4217
        type:
          type: string
          enum:
            - unit_amount
            - flat_amount
        amount:
          type: number
          format: double
          example: 0.0125
          description: |
            The flat / pr unit amount price
        up_to:
          type: integer
          description: |
            unit-amount upper limit, only applicable for `unit_amount` type
        price_model:
          type: string
          enum:
            - blend
            - ic++
          description: |
            High level price model
          default: blend
    BillingCost:
      type: object
      description: |
        Cost aggregated by date
      required:
        - id
        - plan
        - total_count
        - total_amount
        - total_metric_value
        - currency
        - start_at
        - end_at
        - type
        - namespace
        - metric_name
        - dimensions
      properties:
        id:
          type: string
        start_at:
          type: string
          format: date-time
        end_at:
          type: string
          format: date-time
        total_count:
          type: integer
          description: |
            number of usages where the cost was updated
        total_amount:
          type: number
          format: double
          description: |
            the total cost in smallest unit for the currency
        total_metric_value:
          type: integer
          description: |
            the total metric value the cost is calculated from
        currency:
          type: string
          format: iso4217-code
          example: NOK
          description: |
            The three-character ISO-4217 currency.
            https://en.wikipedia.org/wiki/ISO_4217
        namespace:
          type: string
          example: checkout
        metric_name:
          type: string
          example: capture
        type:
          type: string
          example: checkout/capture
          description: the cost type
        dimensions:
          type: array
          items:
            $ref: '#/components/schemas/BillingDimension'
        plan:
          type: object
          properties:
            id:
              type: string
            prices:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/BillingPrice'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
          properties:
            code:
              type: string
              description: The code used to identify the error/warning
            errors:
              type: array
              description: The nested error(s) encountered during validation
              items:
                type: object
            message:
              type: string
              description: The human readable description of the error/warning
    Object:
      type: object
      properties:
        id:
          type: string
          description: |
            An id that uniquely identifies the resource
          readOnly: true
        created_at:
          type: string
          format: date-time
          description: |
            The date-time when the resource was created
          readOnly: true
        created_by:
          type: string
          description: |
            The ID of the user/client created the resource
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: |
            The date-time when the resource was last updated
          readOnly: true
    Deleted:
      type: object
      properties:
        deleted_by:
          type: string
          example: 1c92f7e1-2897-4d46-bdcc-c127a914fb4e
          description: |
            The ID of the user/client deleted the resource
          readOnly: true
        deleted_at:
          type: string
          format: date-time
          readOnly: true
    BillingPayoutRuleDestinationNested:
      type: object
      description: |
        Destination for a split.

        - A destination must have `destination` or `destinations` set, not both.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - percentage
            - flat_amount
            - remaining_amount
        value:
          description: |
            The value that will be used for the payout to the destination or destinations.
          type: string
          format: numeric
        destination:
          type: string
          example: account-123
        destinations:
          type: array
          description: |
            Array of sub destinations.
          minItems: 1
          items:
            type: object
        amount:
          readOnly: true
          description: |
            The split payout calculated for this destination or list of destinations.
          type: integer
    BillingPayoutRuleDestination:
      type: object
      description: |
        Destination for a split.

        - A destination must have `destination` or `destinations` set, not both.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - percentage
            - flat_amount
            - remaining_amount
        value:
          description: |
            The value that will be used for the payout to the destination or destinations.
          type: string
          format: numeric
        destination:
          type: string
          example: account-123
        destinations:
          type: array
          description: |
            Array of sub destinations.
          minItems: 1
          items:
            $ref: '#/components/schemas/BillingPayoutRuleDestinationNested'
        amount:
          readOnly: true
          type: integer
    BillingPayoutRule:
      type: object
      description: |
        A Payout rule describes how a payout should be
        splitted between multiple destinations.
      required:
        - rule_id
        - rule_type
        - destinations
      properties:
        account_id:
          type: string
          description: |
            An id that uniquely identifies the account.
          format: ^[PT]{1}\d{8}$
          readOnly: true
        rule_type:
          type: string
          example: order.items.store.id
        rule_id:
          type: string
          description: |
            Unique ID given the rule type.
          example: sc029
        rule_version:
          readOnly: true
          type: number
          format: integer
          example: 1
        destinations:
          description: |
            Destinations for the payout splits tree. The splitting is done
            in the order of the destinations.

            - A destination must include a `destination` or `destinations`.
            - The destination `value` is required for destinations with type `percentage` and `flat_amount`
          type: array
          items:
            $ref: '#/components/schemas/BillingPayoutRuleDestination'
          example:
            - type: percentage
              value: 10
              destinations:
                - type: flat_amount
                  value: '500'
                  destination: account-a
                - type: remaining_amount
                  destinations:
                    - type: percentage
                      value: '5.0'
                      destination: account-b
            - type: flat_amount
              value: '500'
              destination: account-a
            - type: remaining_amount
              destinations:
                - type: percentage
                  value: '5'
                  destination: account-b
                - type: percentage
                  value: '95.0'
                  destination: account-c
        metadata:
          type: object
          maxProperties: 10
          description: |
            Additional metadata about the payout rule
    BillingReport:
      type: object
      description: |
        Billing Report
      properties:
        start_at:
          description: |
            the start for the report periode
          type: string
          format: date-time
        end_at:
          description: |
            the end for the report periode
          type: string
          format: date-time
        links:
          type: array
          description: |
            links to report resources
          items:
            type: object
            properties:
              href:
                type: string
                format: uri
              rel:
                type: string
                description: |
                  - `csv`: link to download CSV report
                  - `pdf`: link to download PDF report
                enum:
                  - csv
                  - pdf
              content-type:
                type: string
                enum:
                  - text/csv
                  - application/pdf
    BillingSubscription:
      type: object
      description: |
        Subscription
      required:
        - id
        - description
        - namespace
        - metric_name
        - prices
        - dimensions
      properties:
        id:
          type: string
        description:
          type: string
          example: checkout/capture
        namespace:
          type: string
          example: checkout
        metric_name:
          type: string
          example: capture
        dimensions:
          type: array
          items:
            $ref: '#/components/schemas/BillingDimension'
        prices:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/BillingPrice'
    SettlementItem:
      type: object
      properties:
        id:
          type: string
          description: |
            Unique identifier for the settlement
        start_at:
          type: string
          format: datetime
          description: Time of first payment event in this settlement
        end_at:
          type: string
          format: datetime
          description: Time of last payment event in this settlement
        created_at:
          type: string
          format: datetime
        updated_at:
          type: string
          format: datetime
        settled_at:
          type: string
          format: datetime
          description: Settlement date
        email_received_at:
          type: string
          description: Time of email received in Dintero's system
        provider:
          type: string
          description: Name of payment provider.
        provider_reference:
          type: string
          description: The provider's unique id of the settlement
        attachments:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Unique id of the attachment
              key:
                type: string
                description: Attachment path
              content_type:
                type: string
                example: application/xml
              extension:
                type: string
              created_by:
                type: string
                description: |
                  Where the attachment was created. Might be created by dintero,
                  or might be created by the providers, e.g. payex, vipps, collector
                example: payex
        amounts:
          type: array
          items:
            type: object
            properties:
              amount:
                type: number
                description: |
                  The amount paid out, unless payment_status is postponed.

                  `amount = capture - refund - fee`
              capture:
                type: number
                description: |
                  The amount captured on the orders in the settlement period.
              refund:
                type: number
                description: |
                  The amount refunded on the orders in the settlement period.
              fee:
                type: number
                description: |
                  The sum of fees on the orders in the settlement period.
              currency:
                type: string
                format: iso4217-code
                example: NOK
        payment_status:
          type: string
          description: |
            Whether the amount in the report has actually been paid or not.
            The payment might be postponed for later.
          enum:
            - paid
            - postponed
        store_id:
          type: string
          description: |
            The sales location this report is for. Will only be set if all
            transactions share the same store_id.
        payout_destination_id:
          type: string
          description: |
            The seller id this report is for. Will only be set if all
            transactions share the same payout_destination_id.
    SettlementResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SettlementItem'
        last_evaluated_key:
          type: object
          description: |
            Details included for use in pagination. Use the value of `settled_at`|
            or `created_at` and `id` as `starting_after_id` and `starting_after_date`
            parameter to retrieve the next page of settlements.
          properties:
            id:
              type: string
            account_id:
              type: string
            settled_at:
              type: string
              format: datetime
            created_at:
              type: string
              format: datetime
              description: |
                Included when filtering by `item_created_at.gte` and/or
                `item_created_at.lte`, the value to use for `starting_after_date`
    UpdateSettlementReportConfigItem:
      type: object
      required:
        - filetypes
        - destinations
        - providers
      properties:
        send_every:
          description: |
            **Deprecated** report configuration is not used for controlling when to create and send report

            Value in milliseconds describing how often reports should be sent.
          type: number
          example: 86400000
        filetypes:
          type: array
          items:
            type: string
          description: The filetypes that should be sent
        destinations:
          type: array
          description: List of destinations. If empty, the report is just stored and visible from the backoffice.
          items:
            type: object
            required:
              - destination_type
            properties:
              id:
                type: string
              destination_type:
                type: string
                description: |
                  Specifies the type of destination.

                  - account_email: Send email to the billing email address registered on the account
                  - email: Send email to the email address specified in `destination_value`
                enum:
                  - account_email
                  - email
              destination_value:
                type: string
                description: |
                  If destination_type is email, the email address goes here
        providers:
          type: array
          description: List of providers to send report for. If empty, send for all.
          items:
            type: string
        filters:
          description: |
            The report will only be sent to the provided destinations if it satisfies these criterias.
          type: array
          items:
            type: object
            properties:
              filter:
                type: string
                enum:
                  - payout_destination_id
                description: |
                  The "field/column" the data will be filtered on
              value:
                type: string
                description: The value the records must contain for the provided filter (field/column)
    SettlementReportConfigItem:
      type: object
      allOf:
        - $ref: '#/components/schemas/UpdateSettlementReportConfigItem'
        - properties:
            id:
              type: string
            last_send_at:
              description: |
                **Deprecated** report configuration is not used for controlling when to create and send report

                Value in milliseconds (Unix epoch) describing when last time reports was sent.
              type: number
              readOnly: true
            last_modified_at:
              description: |
                **Deprecated** report configuration is not used for controlling when to create and send report

                Value in milliseconds (Unix epoch) describing when last time reports was modified.
              type: number
              readOnly: true
            created_at:
              type: string
              format: date-time
              description: |
                The date-time when the resource was created
              readOnly: true
            updated_at:
              type: string
              format: date-time
              description: |
                The date-time when the resource was last updated
              readOnly: true
            account_id:
              type: string
              readOnly: true
    SettlementReportConfigResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SettlementReportConfigItem'
        starting_after:
          type: string
          description: cursor for use in pagination
    TestReportOptions:
      type: object
      description: |
        Options to determine which transactions to include. If no options are included
        transactions from the last 7 days will be included.

        Only operations for a transaction that has not already been settled
        will be included.
      properties:
        transaction_ids:
          description: |
            Array of transaction IDs to include in the report. If a transaction has already been
            settled earlier it will be ignored. An empty array will be ignored.
            Should not be combined with `number_of_transactions` or `date_range`.
          type: array
          maxItems: 1000
          example:
            - T12345678.aaaabbbbccccddddeeee01
            - T12345678.aaaabbbbccccddddeeee02
          items:
            type: string
        number_of_transactions:
          description: |
            Number of transactions to include. Can be combined with `date_range`, but
            should not be combined with `transaction_ids`. Must be a positive integer.
          type: integer
          minimum: 1
          maximum: 10000
          example: 10
        date_range:
          description: |
            A date range to limit which transactions to include. Can be combined with
            `number_of_transactions`, but should not be combined with `transaction_ids`.

            `start_date` must be before `end_date`.
          type: object
          required:
            - start_date
            - end_date
          properties:
            start_date:
              type: string
              format: date
              example: '2025-12-01'
            end_date:
              type: string
              format: date
              example: '2025-12-07'
    TestReportResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string