Tackle.io Disbursements API

openapi: 3.0.3
info:
  title: Tackle Public Contracts Authentication Disbursements API
  description: "Customer-facing read API for cloud marketplace contracts that Tackle has\ningested for your Tackle account.\n\nThe response shape is a stable projection of the underlying\ncontract document. It is intended to be safe to consume long-term: fields\nwill be added over time, but documented fields will not be removed without\ndeprecation notice.\n\n## Authentication\n\nEvery request must include a valid Tackle JWT in the `Authorization`\nheader (`Authorization: Bearer <token>`). Machine-to-machine (MTM) tokens\nissued for your Tackle account are accepted. The token scopes every\nresponse to the account it represents.\n\n## Pagination\n\n`GET /api/contracts` is the only paginated endpoint. Pagination uses an\nopaque `cursor` query parameter:\n\n1. The first request omits `cursor`.\n2. If more pages exist, the response includes a `next` field. Pass that\n   value verbatim back as `cursor` on the next request.\n3. The last page omits `next`.\n\nCursors are opaque tokens. Do not parse, modify, or persist them across\nschema changes — request a fresh page from the start instead.\n"
  version: 1.0.0
servers:
- url: https://contracts.tackle.io
  description: Production
security:
- tackleJwt: []
tags:
- name: Disbursements
paths:
  /v1/disbursements:
    get:
      summary: List Disbursements
      tags:
      - Disbursements
      operationId: v1-get-disbursements
      responses:
        '200':
          $ref: '#/components/responses/Reports_200-OK-Disbursements'
        '400':
          $ref: '#/components/responses/Reports_400-Bad-Request'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '422':
          $ref: '#/components/responses/Reports_422-Reports'
      parameters:
      - $ref: '#/components/parameters/start_date'
      - $ref: '#/components/parameters/end_date'
      - $ref: '#/components/parameters/Marketplace'
      description: List disbursements within a date range
      security:
      - BearerAuth: []
components:
  schemas:
    AwsProductId:
      type: string
      description: AWS Product Code
      example: 1test1a2b3c4d5e6f7g8h9ijk
      minLength: 0
    ReportingProduct:
      title: Product
      type: object
      properties:
        name:
          type: string
          default: Example Product
        id:
          default: example-product-code-12345
          anyOf:
          - $ref: '#/components/schemas/AwsProductId'
          - $ref: '#/components/schemas/GcpProductId'
        tackle_product_ref_id:
          type: string
          nullable: true
      required:
      - name
      - id
    SubscriptionChangeIds:
      type: array
      items:
        $ref: '#/components/schemas/SubscriptionChangeId'
    Metadata:
      title: Metadata
      type: object
      description: Metadata for a given request
      properties:
        link:
          type: string
          format: uri
          example: https://api.tackle.io
      required:
      - link
    Money:
      type: object
      properties:
        amount:
          type: number
        currency:
          type: string
          enum:
          - EUR
          - CAD
          - USD
          - GBP
      required:
      - amount
      - currency
    Error:
      title: ErrorResponse
      type: object
      properties:
        code:
          type: string
          description: Error code
          minLength: 0
        error:
          type: string
          description: Error response
          minLength: 0
        errors:
          description: Error details
          type: array
          items: {}
        error_type:
          type: string
          enum:
          - service_exception
          - client_exception
      required:
      - code
      - error
      - errors
    AwsCloud:
      type: string
      description: AWS Cloud
      default: aws
      enum:
      - aws
      example: aws
    Transaction:
      title: Transaction
      type: object
      properties:
        id:
          type: string
        seller_revenue:
          $ref: '#/components/schemas/Money'
        marketplace_fee:
          $ref: '#/components/schemas/Money'
        net_amount:
          $ref: '#/components/schemas/NetAmount'
      required:
      - id
      - seller_revenue
      - marketplace_fee
      - net_amount
    Disbursement:
      title: Disbursement
      type: object
      properties:
        invoice_id:
          $ref: '#/components/schemas/InvoiceId'
        disbursement_date:
          type: string
          pattern: (^[0-9]{4}-[0-9]{2}-[0-9]{2})([T][0-9]{2}:[0-9]{2}:[0-9]{2})
        product:
          $ref: '#/components/schemas/ReportingProduct'
        transaction:
          $ref: '#/components/schemas/Transaction'
        customer:
          $ref: '#/components/schemas/Customer'
        cloud_marketplace:
          anyOf:
          - $ref: '#/components/schemas/AwsCloud'
          - $ref: '#/components/schemas/GcpCloud'
        subscription_change_ids:
          $ref: '#/components/schemas/SubscriptionChangeIds'
      required:
      - invoice_id
      - disbursement_date
      - product
      - transaction
      - customer
      - cloud_marketplace
    InvoiceId:
      type: string
      example: 12345-abcde
    Address:
      type: object
      properties:
        country:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        zip_code:
          type: string
          nullable: true
        email_domain:
          type: string
          nullable: true
    422Reports:
      title: Reports-422-Response
      type: object
      properties:
        code:
          type: string
        error:
          type: string
        errors:
          type: array
          items: {}
      required:
      - code
      - error
      - errors
    NetAmount:
      allOf:
      - $ref: '#/components/schemas/Money'
      description: Amount to be disbursed by cloud provider after any marketplace fees have been assessed
    DisbursementsResponse:
      title: DisbursementsResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Disbursement'
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
      - data
      - metadata
    Customer:
      type: object
      properties:
        account_number:
          type: string
          nullable: true
          description: Marketplace Account Number
        address:
          $ref: '#/components/schemas/Address'
    GcpCloud:
      type: string
      description: GCP Cloud
      default: gcp
      enum:
      - gcp
      example: gcp
    SubscriptionChangeId:
      type: string
      example: a1bc2De_-F3
    GcpProductId:
      type: string
      description: GCP Solution ID
      example: tackle-for-gcp
      minLength: 0
  parameters:
    Marketplace:
      name: cloud
      in: query
      schema:
        type: string
        enum:
        - aws
        - gcp
        example: aws
      description: Cloud Marketplace
      required: true
    start_date:
      name: start_date
      description: Start date for a query
      in: query
      required: true
      schema:
        type: string
        format: date
        example: '2021-06-01'
    end_date:
      name: end_date
      description: End date for a query
      in: query
      required: true
      schema:
        type: string
        format: date
        example: '2021-07-01'
  responses:
    Reports_422-Reports:
      description: Example response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/422Reports'
          examples:
            example-422-invalid-fields:
              value:
                code: invalid_fields
                error: Validation Error
                errors:
                - ctx:
                    enum_values:
                    - aws
                    - gcp
                  loc:
                  - query
                  - marketplace
                  msg: 'value is not a valid enumeration member; permitted: ''aws'', ''gcp'''
                  type: type_error.enum
    Reports_200-OK-Disbursements:
      description: Example success response containing a list of Disbursement objects
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DisbursementsResponse'
          examples:
            disbursements-success:
              value:
                data:
                - invoice_id: '973453769353'
                  disbursement_date: '2021-01-26T23:49:41'
                  product:
                    name: Tackle Cloud Marketplace Platform
                    id: wfSjBibbsm79VdcjaG4hahXzv
                    tackle_product_ref_id: null
                  transaction:
                    id: yQEwXvKhm4PEzyNN2xbdNmWxLTGxWfM4H9ALdSU4CS2uXCUoDVuCYDH
                    seller_revenue:
                      amount: 14995
                      currency: USD
                    marketplace_fee:
                      amount: -1199.6
                      currency: USD
                    net_amount:
                      amount: 13795.4
                      currency: USD
                  customer:
                    account_number: '897487884275'
                    address:
                      country: null
                      city: null
                      zip_code: null
                      email_domain: null
                  cloud_marketplace: aws
                  subscription_change_ids:
                  - y3jg5Vl_-N0
                - invoice_id: '579270481'
                  disbursement_date: '2021-01-12T23:45:55'
                  product:
                    name: Tackle Cloud Marketplace Platform
                    id: rJ2fuuZVHXWPaTtfGBSD7d7ht
                    tackle_product_ref_id: null
                  transaction:
                    id: YqJ2DUU8VPAH7G6vE7WuQLB9heePw7DcHt2K2rqywz8rBEiTaGSqD3k
                    seller_revenue:
                      amount: 27995
                      currency: USD
                    marketplace_fee:
                      amount: -2239.6
                      currency: USD
                    net_amount:
                      amount: 25755.4
                      currency: USD
                  customer:
                    account_number: null
                    address:
                      country: null
                      city: null
                      zip_code: null
                      email_domain: null
                  cloud_marketplace: aws
                  subscription_change_ids:
                  - i8jg5Vl_-L5
                - invoice_id: '669572946747'
                  disbursement_date: '2021-01-24T14:16:04'
                  product:
                    name: Tackle SaaS Platform for AWS Marketplace
                    id: HXQTgE2MmTQyuDHJpSVsRsrqL
                    tackle_product_ref_id: null
                  transaction:
                    id: RAyQyNo4BLamAcquLXA9fkPMkHJKBke6WBPXKrTQ8iMFehUomVpSGyR
                    seller_revenue:
                      amount: 1100
                      currency: USD
                    marketplace_fee:
                      amount: -88
                      currency: USD
                    net_amount:
                      amount: 1012
                      currency: USD
                  customer:
                    account_number: null
                    address:
                      country: null
                      city: null
                      zip_code: null
                      email_domain: null
                  cloud_marketplace: aws
                  subscription_change_ids:
                  - 9jyg8Nl_-P5
                metadata:
                  link: https://api.tackle.io/v1/disbursements?start_date=2021-01-01&end_date=2021-02-01&cloud=aws
    Reports_400-Bad-Request:
      description: Example response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            example-bad-request:
              value:
                code: invalid_fields
                error: Validation Error
                errors:
                - loc:
                  - query
                  - cloud
                  msg: field required
                  type: value_error.missing
    401-Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unauthorized:
              value:
                code: unauthorized
                error: client_id and client_secret are invalid.
                error_type: service_exception
                errors: []
  securitySchemes:
    tackleJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Tackle-issued JWT (interactive user or MTM token).