openapi: 3.1.0
info:
  title: Partner Invoices API
  version: '16'
  description: "Invoices (or partner invoices) are statements of amounts owed to partners that are automatically generated by impact.com. \nThey contain information about payments due to partners, including individual line item(s) within an invoice.\n"
  contact:
    name: impact.com Developer Support
    url: https://app.impact.com/secure/help/contact-support.ihtml
servers:
- url: https://api.impact.com
tags:
- name: Invoices
  description: Endpoints for listing, retrieving, and downloading partner invoices.
paths:
  /Mediapartners/{AccountSID}/Invoices:
    get:
      operationId: listInvoices
      tags:
      - Invoices
      summary: List invoices
      description: "Returns a list of invoices. The transactions are returned in sorted order, with the most recent transactions appearing first. \nParameters can be used to create a date range to only list invoices that were created within the range.\n"
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the partner account.
      - name: StartDate
        in: query
        required: false
        description: ISO 8601 format that filters the list to only show invoices created on or after this date.
        schema:
          type: string
          format: date-time
      - name: EndDate
        in: query
        required: false
        description: ISO 8601 format that filters the list to only show invoices created on or before this date.
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  Invoices:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invoice'
      x-codeSamples:
      - lang: Shell
        label: curl
        source: |-
          curl -L \
            --url 'https://api.impact.com/Mediapartners/{AccountSID}/Invoices' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
  /Mediapartners/{AccountSID}/Invoices/{Id}:
    get:
      operationId: retrieveInvoice
      tags:
      - Invoices
      summary: Retrieve a specific invoice
      description: This request allows you to retrieve an invoice from both impact.com's invoicing methods.
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the partner account.
      - name: Id
        in: path
        required: true
        description: Unique identifier for the invoice object.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
      x-codeSamples:
      - lang: Shell
        label: curl
        source: |-
          curl -L \
            --url 'https://api.impact.com/Mediapartners/{AccountSID}/Invoices/{Id}' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
  /Mediapartners/{AccountSID}/Invoices/{Id}/Download:
    get:
      operationId: downloadInvoice
      tags:
      - Invoices
      summary: Download an invoice
      description: Returns the specified invoice as a downloaded file in PDF format.
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the partner account.
      - name: Id
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the invoice.
      responses:
        '200':
          description: PDF file of the invoice.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
      x-codeSamples:
      - lang: Shell
        label: curl
        source: |-
          curl -L \
            --url 'https://api.impact.com/Mediapartners/{AccountSID}/Invoices/{Id}/Download' \
            --user '{AccountSID}:{AuthToken}' \
            --header 'Accept: */*'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your AccountSID as the username and AuthToken as the password.
  schemas:
    Invoice:
      type: object
      properties:
        Id:
          type: string
          description: Unique identifier for the invoice object.
          example: 1924609-1
        CreatedDate:
          type: string
          format: date-time
          description: ISO 8601 format of the date and time when the invoice was created.
          example: '2024-09-02T07:37:12-07:00'
        RecipientId:
          type: integer
          description: Unique identifier of the recipient of the invoice.
          example: 1804207
        RecipientName:
          type: string
          description: The display name of the recipient of the invoice.
          example: Acme Corporation
        Currency:
          type: string
          description: Three-letter ISO 4217 currency code.
          example: USD
        TotalAmount:
          type: string
          format: decimal
          description: The total amount due to the partner in the invoice.
          example: '50.00'
        TotalVatAmount:
          type: string
          format: decimal
          description: Value-added tax applied to the invoice, if any exists.
          example: '0.00'
        LineItems:
          type: array
          description: List of line items summarising each payout component in the invoice.
          items:
            $ref: '#/components/schemas/LineItem'
        DetailedLineItems:
          type: array
          description: Detailed breakdown of payout amounts per program within the invoice.
          items:
            $ref: '#/components/schemas/DetailedLineItem'
        PDF:
          type: string
          description: API resource path to download the invoice as a PDF.
          example: /Mediapartners/<AccountSID>/Invoices/1924609-1/Download
        Uri:
          type: string
          description: Unique reference to this invoice in the impact.com API.
          example: /Mediapartners/<AccountSID>/Invoices/1924609-1
    LineItem:
      type: object
      properties:
        CampaignId:
          type: string
          description: Unique identifier for the program associated with this line item.
          example: '10306'
        CampaignName:
          type: string
          description: Display name of the program associated with this line item.
          example: Wayne Enterprises
        Description:
          type: string
          enum:
          - MEDIA_PAYOUT
          - BONUS
          description: The type of payout. MEDIA_PAYOUT is a standard commission payout; BONUS is for meeting program requirements.
          example: MEDIA_PAYOUT
        EventMonthYear:
          type: string
          description: Month (M or MM) and YYYY of when the events occurred (e.g., 42021).
          example: '12021'
        Actions:
          type: string
          description: The number of actions that relate to the payout. May be empty if not applicable.
          example: '5'
        NetItemAmount:
          type: string
          format: decimal
          description: Net payout amount for this line item before VAT.
          example: '50.00'
        VatItemAmount:
          type: string
          format: decimal
          description: VAT amount applied to this line item. May be empty if not applicable.
          example: '0.00'
        TotalItemAmount:
          type: string
          format: decimal
          description: Total payout amount for this line item including VAT.
          example: '50.00'
        Status:
          type: string
          enum:
          - PENDING
          - PAID
          - OVERDUE
          description: Payment status of this line item.
          example: OVERDUE
        DueDate:
          type: string
          format: date-time
          description: Date and time payment is due for this line item (ISO 8601).
          example: '2021-02-05T17:51:35-08:00'
        PaidDate:
          type: string
          format: date-time
          description: Date and time this line item was paid (ISO 8601). Empty if not yet paid.
          example: '2024-10-01T00:00:00-07:00'
    DetailedLineItem:
      type: object
      properties:
        AccountId:
          type: integer
          description: Unique identifier of the partner account associated with this payout.
          example: 1804207
        Name:
          type: string
          description: Display name of the partner account associated with this payout.
          example: Acme Corporation
        ProgramId:
          type: string
          description: Unique identifier for the program associated with this payout.
          example: '10306'
        ProgramName:
          type: string
          description: Display name of the program associated with this payout.
          example: Wayne Enterprises
        EventMonthYear:
          type: string
          description: Month (M or MM) and YYYY of when the events occurred (e.g., 42021).
          example: '12021'
        ActionAmount:
          type: string
          format: decimal
          description: Amount attributable to tracked actions. May be empty if not applicable.
          example: '48.00'
        OtherAmount:
          type: string
          format: decimal
          description: Amount attributable to non-action payouts such as bonuses.
          example: '2.00'
        TotalAmount:
          type: string
          format: decimal
          description: Total payout amount for this detailed line item.
          example: '50.00'
x-default-client: cURL
