openapi: 3.0.0
info:
  title: Paigo Customers Invoices API
  description: "\nFor developer documentation of the platform, please visit https://docs.paigo.tech.\n\n## Authentication\nPaigo API supports **bearer token** as the authentication method.\nSteps to set up authentication:\n1. Sign up with Paigo platform and get **client id** and **client secret**.\n2. Make a POST request to the auth endpoint `https://auth.paigo.tech/oauth/token` with the following body:\n```json\n{\n        audience: 'https://qnonyh1pc7.execute-api.us-east-1.amazonaws.com',\n        grant_type: 'client_credentials',\n        client_id: <your client id>,\n        client_secret: <your client secret>\n}\n```\nAdditionally verify that the following headers are set by the client you are using: \n```json\n{\n    \"Content-Type\": \"application/json\"\n}\n```\n\n3. Use the access token in the response to make requests to the Paigo API. Here is an example of the response:  \n```json   \n{\n            access_token: <your access token>,\n            expires_in: 86400,\n            token_type: 'Bearer'  \n}\n```\n4. To use Paigo API, add in the header of your request:\n```json\n{\n        Authorization: \"Bearer <your access token>\"\n}\n```\n\n## API Endpoints\nPaigo API has the following endpoint:\n- Production Environment API: `https://api.prod.paigo.tech`\n        "
  version: v1.10
  contact: {}
servers:
- url: https://api.prod.paigo.tech
  description: Product Environment API
tags:
- name: Invoices
  description: Manage invoices in Paigo.
paths:
  /invoices/{invoiceId}:
    get:
      operationId: Get an Invoice by ID
      summary: ''
      description: 'Find an Invoice

        <br><br> Download links for invoices are valid for 7 days.'
      parameters:
      - name: invoiceId
        required: true
        in: path
        description: The invoice ID assigned by Paigo
        example: 7c71590b-3368-4d53-b9cb-5203605b4946
        schema:
          type: string
      - name: download
        required: false
        in: query
        description: Get a download link for the invoice in the response
        example: 'true'
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadInvoicesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicResponseDTO'
        '404':
          description: Invoice Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The error message
                    example: 'Invoice with ID: 7c71590b-3368-4d53-b9cb-5203605b4946 not found'
                  error:
                    type: string
                    description: The error name
                    example: Not Found
                  statusCode:
                    type: number
                    description: The HTTP status code
                    example: 404
                    externalDocs:
                      description: MDN Documentation Reference
                      url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
                example:
                  message: 'Invoice with ID: 7c71590b-3368-4d53-b9cb-5203605b4946 not found'
                  error: Not Found
                  statusCode: 404
                required:
                - message
                - error
                - statusCode
      tags:
      - Invoices
      security:
      - bearer: []
  /invoices:
    post:
      operationId: Create
      summary: ''
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvoicesDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
      tags:
      - Invoices
      security:
      - bearer: []
components:
  schemas:
    ReadInvoicesResponse:
      type: object
      properties:
        message:
          type: string
          description: A human readable message describing the outcome of the operation
          example: This is a sample API message. The exact message may vary based on the API behavior
        data:
          type: array
          items:
            $ref: '#/components/schemas/ReadInvoicesDto'
      required:
      - message
      - data
    BasicResponseDTO:
      type: object
      properties:
        message:
          type: string
          description: A human readable message describing the outcome of the operation
          example: This is a sample API message. The exact message may vary based on the API behavior
      required:
      - message
    ReadInvoicesDto:
      type: object
      properties:
        invoiceStatus:
          description: 'The invoice status

            <br><br>


            Example: `"Draft"`'
          example: Draft
          enum:
          - Draft
          - Open
          - Paid
          - Voided
          type: string
          externalDocs:
            url: https://docs.paigo.tech/invoice-and-process-payment/issue-invoice
            description: See Invoice Life Cycle section for more details
        invoicePaymentTerm:
          description: 'The payment term for the invoice

            <br><br>

            Example: `"30"`'
          example: 30
          enum:
          - '30'
          - '60'
          - ''
          type: string
        invoiceDate:
          type: string
          description: 'The date the invoice was issued

            <br><br>

            Example: `"2021-01-01T00:00:00.000Z"`'
          example: '2021-01-01T00:00:00.000Z'
        customerId:
          type: string
          description: 'The unique identifier assigned by Paigo for the customer

            <br><br>

            Example: `"e962aefe-6134-4f28-8967-a11cfe7f0bf2"`'
          example: e962aefe-6134-4f28-8967-a11cfe7f0bf2
        totalAmountWithoutTax:
          type: number
          description: 'The total amount of the invoice without tax

            <br><br>

            Example: `100.00`'
          example: 100
        taxAmount:
          type: number
          description: 'The total amount of tax on the invoice

            <br><br>

            Example: `10.00`'
          example: 10
        amountPaid:
          type: number
          description: 'The total amount paid by the customer so far for the invoice

            <br><br>

            Example: `110.00`'
          example: 110
        invoiceUrl:
          type: string
          description: 'The URL to download the invoice. URLs are self signed and valid for 7 days after the link is generated.

            <br><br>

            Example: `"https://my-cool-bucket.s3.amazonaws.com/invoices/123MyCoolCorp980/2021-01-01/123MyCoolCorp980-2021-01-01-1234567890.pdf"`'
          example: https://my-cool-bucket.s3.amazonaws.com/invoices/123MyCoolCorp980/2021-01-01/123MyCoolCorp980-2021-01-01-1234567890.pdf
        currency:
          description: 'The currency of the invoice. Defaults to USD

            <br><br>

            Example: `"USD"`'
          example: USD
          enum:
          - USD
          - EUR
          - CNY
          type: string
        paymentLink:
          type: string
          description: 'The payment link for the invoice. Only used for invoices in the `Draft` or `Open` status. Otherwise this field will not be present.

            <br><br>

            Example: `"https://example.com/redirect"`'
          example: https://example.com/redirect
        invoiceType:
          description: 'The type of invoice. This is used to indicate how the invoice was created, whether it was created manually, via a topup event, roccuring event, etc.

            <br><br>

            Example: `"TOPUP"`'
          example: TOPUP
          enum:
          - TOPUP
          - MANUAL
          - RECURRING
          type: string
        invoiceCommunicationHistory:
          type: array
          items:
            required: false
            description: 'The communication history of the invoice. This is used to track the communication between Paigo and the customer.

              <br><br>

              Example: `[]`'
            example: []
            type: array
            items:
              $ref: '#/components/schemas/InvoiceCommunicationHistory'
        lineItems:
          description: The line items on the invoice
          type: array
          items:
            $ref: '#/components/schemas/InvoiceLineItem'
        refunds:
          description: The refunds associated with the invoice
          type: array
          items:
            $ref: '#/components/schemas/StripeRefundResponseDto'
        payments:
          description: The payments associated with the invoice
          type: array
          items:
            $ref: '#/components/schemas/ReadPaymentDto'
      required:
      - invoiceStatus
      - invoicePaymentTerm
      - invoiceDate
      - totalAmountWithoutTax
      - currency
      - invoiceCommunicationHistory
      - lineItems
      - refunds
      - payments
    ReadPaymentDto:
      type: object
      properties:
        type:
          type: string
          description: 'The type of payment. Currently only `Credit` and `Stripe` are supported.

            <br><br>

            Example: `"Credit"`'
          example: Credit
          enum:
          - Stripe
          - Credit
        transactionAmount:
          type: string
          description: 'The amount associated with a specific credit transaction

            <br><br>

            Example: `"100.00"`'
          example: '100.00'
        timestamp:
          type: string
          description: 'The timestamp associated with a specific credit transaction. RFC3339 format.

            <br><br>

            Example: `"2021-01-01T00:00:00.000Z"`'
          example: '2021-01-01T00:00:00.000Z'
        metadata:
          type: object
          description: 'The metadata associated with a specific transaction. For `stripe` type responses, paymentIntentsId, currency, and status are included.

            <br><br>

            Example: `{"key": "value"}`'
      required:
      - type
      - transactionAmount
      - timestamp
      - metadata
    InvoiceLineItem:
      type: object
      properties:
        name:
          type: string
          description: 'The name of the line item as it appears on the invoice.

            <br><br>

            Example: `"Paigo Pro"`'
          example: Paigo Pro
        quantity:
          type: number
          description: 'The quantity of the line item.

            <br><br>

            Example: `1`'
          example: 1
          minimum: 0
        unitCost:
          type: number
          description: 'The unit cost of the line item.

            <br><br>

            Example: `100.00`'
          example: 100
        description:
          type: string
          description: 'The description of the line item.

            <br><br>

            Example: `"Paigo Pro subscription"`'
          example: Paigo Pro subscription
      required:
      - name
      - quantity
      - unitCost
    CreateInvoicesDto:
      type: object
      properties:
        customerId:
          type: string
          description: 'The client ID assocaited with the Business Entity, this is the name for the business which will be used in the invoce

            <br><br>

            Example: `"Khols"`'
          example: Khols
        items:
          description: 'The Itemized collection of elements to be billed. These could be instance compute hours, or number of users

            <br><br>

            Example: `[{ "name": "MyService", "quantity": 1, "unitCost": 100.09 }]`'
          example:
          - name: Paigo Pro
            quantity: 1
            unitCost: 100.09
          type: array
          items:
            type: object
        invoiceDate:
          type: string
          description: 'The date the invoice is to be generated for

            <br><br>

            Example: `"2020-09-18T17:34:02.666Z"`'
          example: '2020-09-18T17:34:02.666Z'
        currency:
          description: 'The currency the invoice is to be generated in. If no Currency is passed in the currency used by the customer will be used.

            <br><br>

            Example: `"EUR"`'
          example: EUR
          enum:
          - USD
          - EUR
          - CNY
          type: string
        invoicePaymentTerm:
          description: 'The Payment Term for the invoice. This is the number of days until the invoice is considered past due. Default is "none". String `""` represents "none".

            <br><br>

            Example: `"30"`'
          example: '30'
          enum:
          - '30'
          - '60'
          - ''
          type: string
        storePaymentAsCredit:
          type: boolean
          description: 'If storePaymentAsCredit is `true` then the payment on the invoice will ADD to the customers credit balance. By default it is false, meaning that the payment of an invoice inside of paigo will first, deduct from the credit balance and then charge the payment method on file.

            <br><br>

            Example: `true`'
          example: true
      required:
      - customerId
      - items
    InvoiceCommunicationHistory:
      type: object
      properties:
        time:
          type: string
          description: 'The RFC 3339 time of communication that was sent to the customer.

            <br><br>

            Example: `"2022-01-01T00:00:00.000Z"`'
          example: '2022-01-01T00:00:00.000Z'
        type:
          type: string
          description: 'The type of communication that was sent to the customer.

            <br><br>

            Example: `INVOICE_EMAIL`'
          example: INVOICE_EMAIL
          enum:
          - REMINDER_EMAIL
          - INVOICE_EMAIL
        metadata:
          type: object
          description: 'The metadata of the communication that was sent to the customer.

            <br><br>

            Example: `{"subject": "Invoice for January 2022"}`'
    StripeRefundResponseDto:
      type: object
      properties:
        amountRefunded:
          type: string
          description: 'The amount of the payment that was refunded. Derived from the stripe "amount_refunded" field.

            <br><br>

            Example: `"100.00"`'
          example: '100.00'
          externalDocs:
            url: https://stripe.com/docs/api/refunds/retrieve
            description: 'Stripe API Reference: Retrieve a Refund'
        amount:
          type: string
          description: 'The amount of the original charge. Derived from the stripe "amount" field.

            <br><br>

            Example: `"100.00"`'
          example: '100.00'
          externalDocs:
            url: https://stripe.com/docs/api/refunds/retrieve
            description: 'Stripe API Reference: Retrieve a Refund'
        chargeId:
          type: string
          description: 'The id of the charge that was refunded. Pass through from Stripe API.

            <br><br>

            Example: `"ch_1J5J1n2eZvKYlo2C0q2Q2Q2Q2"`'
          example: ch_1J5J1n2eZvKYlo2C0q2Q2Q2Q2
          externalDocs:
            url: https://stripe.com/docs/api/refunds/retrieve
            description: 'Stripe API Reference: Retrieve a Refund'
        metadata:
          type: object
          description: 'The metadata associated with the refund. Pass through from Stripe API. Metadata is an object of key value pairs.

            <br><br>

            Example: `{ "key": "value" }`'
          externalDocs:
            url: https://stripe.com/docs/api/refunds/retrieve
            description: 'Stripe API Reference: Retrieve a Refund'
        currency:
          type: string
          description: 'The currency associated with the refund. Pass through from Stripe API.

            <br><br>

            Example: `"usd"`'
          example: usd
          externalDocs:
            url: https://stripe.com/docs/api/refunds/retrieve
            description: 'Stripe API Reference: Retrieve a Refund'
        status:
          type: string
          description: 'The status of the refund. Pass through from Stripe API.

            <br><br>

            Example: `"succeeded"`'
          example: succeeded
          externalDocs:
            url: https://stripe.com/docs/api/refunds/retrieve
            description: 'Stripe API Reference: Retrieve a Refund'
        created:
          type: string
          description: 'The ISO representation of the date the refund was created. Derived from the Stripe APIs unix time.

            <br><br>

            Example: `"2021-08-02T20:00:00.000Z"`'
          example: '2021-08-02T20:00:00.000Z'
      required:
      - amountRefunded
      - amount
      - chargeId
      - metadata
      - currency
      - status
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: oauth2
      in: Header
      description: Use bearer token to authenticate `Bearer <your access token>`
      flows:
        clientCredentials:
          tokenUrl: https://auth.paigo.tech/oauth/token
          scopes: {}