OpenAPI Specification
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: {}