Payabli Invoice API
The Invoice API from Payabli — 8 operation(s) for invoice.
The Invoice API from Payabli — 8 operation(s) for invoice.
openapi: 3.1.0
info:
title: API reference Bill Invoice API
version: 1.0.0
servers:
- url: https://api-sandbox.payabli.com/api
description: Sandbox
- url: https://api.payabli.com/api
description: Production
tags:
- name: Invoice
paths:
/Invoice/{entry}:
post:
operationId: AddInvoice
summary: Add invoice
description: Creates an invoice in an entrypoint.
tags:
- Invoice
parameters:
- name: entry
in: path
description: The paypoint's entrypoint identifier. [Learn more](/developers/api-reference/api-overview#entrypoint-vs-entry)
required: true
schema:
type: string
- name: forceCustomerCreation
in: query
description: When `true`, the request creates a new customer record, regardless of whether customer identifiers match an existing customer. Defaults to `false`.
required: false
schema:
$ref: '#/components/schemas/ForceCustomerCreation'
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
- name: idempotencyKey
in: header
description: _Optional but recommended_ A unique ID that you can include to prevent duplicating objects or transactions in the case that a request is sent more than once. This key isn't generated in Payabli, you must generate it yourself. This key persists for 2 minutes. After 2 minutes, you can reuse the key if needed.
required: false
schema:
$ref: '#/components/schemas/IdempotencyKey'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceResponseWithoutData'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceDataRequest'
/Invoice/{idInvoice}:
get:
operationId: GetInvoice
summary: Get invoice
description: Retrieves a single invoice by ID.
tags:
- Invoice
parameters:
- name: idInvoice
in: path
description: Invoice ID
required: true
schema:
type: integer
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: Success. Fields marked optional may return `null` if not set.
content:
application/json:
schema:
$ref: '#/components/schemas/GetInvoiceRecord'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
put:
operationId: EditInvoice
summary: Update invoice
description: Updates details for a single invoice in an entrypoint.
tags:
- Invoice
parameters:
- name: idInvoice
in: path
description: Invoice ID
required: true
schema:
type: integer
- name: forceCustomerCreation
in: query
description: When `true`, the request creates a new customer record, regardless of whether customer identifiers match an existing customer.
required: false
schema:
type: boolean
default: false
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceResponseWithoutData'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceDataRequest'
delete:
operationId: DeleteInvoice
summary: Delete invoice
description: Deletes a single invoice from an entrypoint.
tags:
- Invoice
parameters:
- name: idInvoice
in: path
description: Invoice ID
required: true
schema:
type: integer
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceResponseWithoutData'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
/Invoice/send/{idInvoice}:
get:
operationId: SendInvoice
summary: Send invoice via email
description: Sends an invoice from an entrypoint via email.
tags:
- Invoice
parameters:
- name: idInvoice
in: path
description: Invoice ID
required: true
schema:
type: integer
- name: attachfile
in: query
description: When `true`, attaches a PDF version of invoice to the email.
required: false
schema:
type: boolean
default: false
- name: mail2
in: query
description: Email address where the invoice will be sent to. If this parameter isn't included, Payabli uses the email address on file for the customer owner of the invoice.
required: false
schema:
type: string
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SendInvoiceResponse'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
/Invoice/attachedFileFromInvoice/{idInvoice}/{filename}:
get:
operationId: GetAttachedFileFromInvoice
summary: Get attached file from an invoice
description: Retrieves a file attached to an invoice.
tags:
- Invoice
parameters:
- name: filename
in: path
description: 'The filename in Payabli. Get this from the `zipName` field
in the `DocumentsRef.filelist` array returned by
`/api/Invoice/{idInvoice}`. Example: `0_Bill.pdf`.'
required: true
schema:
type: string
- name: idInvoice
in: path
description: Invoice ID
required: true
schema:
type: integer
- name: returnObject
in: query
description: When `true`, the request returns the file content as a Base64-encoded string.
required: false
schema:
type: boolean
default: false
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: A successful response returns a binary file when `returnObject` is `false`. When `returnObject` is `true`, the response contains the file content as a Base64-encoded string in an object. Due to technical limitations, only the object response is documented here.
content:
application/json:
schema:
$ref: '#/components/schemas/FileContent'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
delete:
operationId: deleteAttachedFromInvoice
summary: Delete attached file from invoice
description: Deletes a file attached to an invoice.
tags:
- Invoice
parameters:
- name: filename
in: path
description: 'The filename in Payabli. Get this from the `zipName` field
in the `DocumentsRef.filelist` array returned by
`/api/Invoice/{idInvoice}`. Example: `0_Bill.pdf`.'
required: true
schema:
type: string
- name: idInvoice
in: path
description: Invoice ID
required: true
schema:
type: integer
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceResponseWithoutData'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
/Invoice/getNumber/{entry}:
get:
operationId: GetInvoiceNumber
summary: Get next InvoiceNumber for entrypoint
description: Retrieves the next available invoice number for a paypoint.
tags:
- Invoice
parameters:
- name: entry
in: path
description: The paypoint's entrypoint identifier. [Learn more](/developers/api-reference/api-overview#entrypoint-vs-entry)
required: true
schema:
type: string
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceNumberResponse'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
/Query/invoices/{entry}:
get:
operationId: ListInvoices
summary: Get list of invoices for an entrypoint
description: Returns a list of invoices for an entrypoint. Use filters to limit results. Include the `exportFormat` query parameter to return the results as a file instead of a JSON response.
tags:
- Invoice
parameters:
- name: entry
in: path
description: The paypoint's entrypoint identifier. [Learn more](/developers/api-reference/api-overview#entrypoint-vs-entry)
required: true
schema:
type: string
- name: exportFormat
in: query
description: Export format for file downloads. When specified, returns data as a file instead of JSON.
required: false
schema:
$ref: '#/components/schemas/ExportFormat'
- name: fromRecord
in: query
description: The number of records to skip before starting to collect the result set.
required: false
schema:
type: integer
default: 0
- name: limitRecord
in: query
description: Max number of records to return for the query. Use `0` or negative value to return all records.
required: false
schema:
type: integer
default: 20
- name: parameters
in: query
description: 'Collection of field names, conditions, and values used to filter the query
See [Filters and Conditions Reference](/developers/developer-guides/pay-ops-reporting-engine-overview#filters-and-conditions-reference) for help.
List of field names accepted:
- `invoiceDate` (gt, ge, lt, le, eq, ne)
- `dueDate` (gt, ge, lt, le, eq, ne)
- `sentDate` (gt, ge, lt, le, eq, ne)
- `frequency` (in, nin,ne, eq)
- `invoiceType` (eq, ne)
- `payTerms` (in, nin, eq, ne)
- `paypointId` (ne, eq)
- `totalAmount` (gt, ge, lt, le, eq, ne)
- `paidAmount` (gt, ge, lt, le, eq, ne)
- `status` (in, nin, eq, ne)
- `invoiceNumber` (ct, nct, eq, ne)
- `purchaseOrder` (ct, nct, eq, ne)
- `itemProductCode` (ct, nct)
- `itemDescription` (ct, nct)
- `customerFirstname` (ct, nct, eq, ne)
- `customerLastname` (ct, nct, eq, ne)
- `customerName` (ct, nct)
- `customerId` (eq, ne)
- `customerNumber` (ct, nct, eq, ne)
- `customerCompanyname` (ct, nct, eq, ne)
- `customerAddress` (ct, nct, eq, ne)
- `customerCity` (ct, nct, eq, ne)
- `customerZip` (ct, nct, eq, ne)
- `customerState` (ct, nct, eq, ne)
- `customerCountry` (ct, nct, eq, ne)
- `customerPhone` (ct, nct, eq, ne)
- `customerEmail` (ct, nct, eq, ne)
- `customerShippingAddress` (ct, nct, eq, ne)
- `customerShippingCity` (ct, nct, eq, ne)
- `customerShippingZip` (ct, nct, eq, ne)
- `customerShippingState` (ct, nct, eq, ne)
- `customerShippingCountry` (ct, nct, eq, ne)
- `orgId` (eq)
- `paylinkId` (ne, eq)
- `paypointLegal` (ne, eq, ct, nct)
- `paypointDba` (ne, eq, ct, nct)
- `orgName` (ne, eq, ct, nct)
- `additional-xxx` (ne, eq, ct, nct) where xxx is the additional field name
List of comparison accepted - enclosed between parentheses:
- eq or empty => equal
- gt => greater than
- ge => greater or equal
- lt => less than
- le => less or equal
- ne => not equal
- ct => contains
- nct => not contains
- in => inside array
- nin => not inside array
List of parameters accepted:
- limitRecord : max number of records for query (default="20", "0" or negative value for all)
- fromRecord : initial record in query
Example: totalAmount(gt)=20 return all records with totalAmount greater than 20.00'
required: false
schema:
type: object
additionalProperties:
type:
- string
- 'null'
- name: sortBy
in: query
description: The field name to use for sorting results. Use `desc(field_name)` to sort descending by `field_name`, and use `asc(field_name)` to sort ascending by `field_name`.
required: false
schema:
type: string
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: Success. Fields marked optional may return `null` if not set.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryInvoiceResponse'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
/Query/invoices/org/{orgId}:
get:
operationId: ListInvoicesOrg
summary: Get list of invoices for an organization
description: Returns a list of invoices for an org. Use filters to limit results. Include the `exportFormat` query parameter to return the results as a file instead of a JSON response.
tags:
- Invoice
parameters:
- name: orgId
in: path
description: The numeric identifier for organization, assigned by Payabli.
required: true
schema:
type: integer
- name: exportFormat
in: query
description: Export format for file downloads. When specified, returns data as a file instead of JSON.
required: false
schema:
$ref: '#/components/schemas/ExportFormat'
- name: fromRecord
in: query
description: The number of records to skip before starting to collect the result set.
required: false
schema:
type: integer
default: 0
- name: limitRecord
in: query
description: Max number of records to return for the query. Use `0` or negative value to return all records.
required: false
schema:
type: integer
default: 20
- name: parameters
in: query
description: 'Collection of field names, conditions, and values used to filter the query
See [Filters and Conditions Reference](/developers/developer-guides/pay-ops-reporting-engine-overview#filters-and-conditions-reference) for help.
List of field names accepted:
- `invoiceDate` (gt, ge, lt, le, eq, ne)
- `dueDate` (gt, ge, lt, le, eq, ne)
- `sentDate` (gt, ge, lt, le, eq, ne)
- `frequency` (in, nin,ne, eq)
- `invoiceType` (eq, ne)
- `payTerms` (in, nin, eq, ne)
- `paypointId` (ne, eq)
- `totalAmount` (gt, ge, lt, le, eq, ne)
- `paidAmount` (gt, ge, lt, le, eq, ne)
- `status` (in, nin, eq, ne)
- `invoiceNumber` (ct, nct, eq, ne)
- `purchaseOrder` (ct, nct, eq, ne)
- `itemProductCode` (ct, nct)
- `itemDescription` (ct, nct)
- `customerFirstname` (ct, nct, eq, ne)
- `customerLastname` (ct, nct, eq, ne)
- `customerName` (ct, nct)
- `customerId` (eq, ne)
- `customerNumber` (ct, nct, eq, ne)
- `customerCompanyname` (ct, nct, eq, ne)
- `customerAddress` (ct, nct, eq, ne)
- `customerCity` (ct, nct, eq, ne)
- `customerZip` (ct, nct, eq, ne)
- `customerState` (ct, nct, eq, ne)
- `customerCountry` (ct, nct, eq, ne)
- `customerPhone` (ct, nct, eq, ne)
- `customerEmail` (ct, nct, eq, ne)
- `customerShippingAddress` (ct, nct, eq, ne)
- `customerShippingCity` (ct, nct, eq, ne)
- `customerShippingZip` (ct, nct, eq, ne)
- `customerShippingState` (ct, nct, eq, ne)
- `customerShippingCountry` (ct, nct, eq, ne)
- `orgId` (eq)
- `paylinkId` (ne, eq)
- `paypointLegal` (ne, eq, ct, nct)
- `paypointDba` (ne, eq, ct, nct)
- `orgName` (ne, eq, ct, nct)
- `additional-xxx` (ne, eq, ct, nct) where xxx is the additional field name
List of comparison accepted - enclosed between parentheses:
- eq or empty => equal
- gt => greater than
- ge => greater or equal
- lt => less than
- le => less or equal
- ne => not equal
- ct => contains
- nct => not contains
- in => inside array
- nin => not inside array
List of parameters accepted:
- limitRecord : max number of records for query (default="20", "0" or negative value for all)
- fromRecord : initial record in query
Example: totalAmount(gt)=20 return all records with totalAmount greater than 20.00'
required: false
schema:
type: object
additionalProperties:
type:
- string
- 'null'
- name: sortBy
in: query
description: The field name to use for sorting results. Use `desc(field_name)` to sort descending by `field_name`, and use `asc(field_name)` to sort ascending by `field_name`.
required: false
schema:
type: string
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: Success. Fields marked optional may return `null` if not set.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryInvoiceResponse'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
/Export/invoicePdf/{idInvoice}:
get:
operationId: GetInvoicePDF
summary: Export Invoice PDF
description: Export a single invoice in PDF format.
tags:
- Invoice
parameters:
- name: idInvoice
in: path
description: Invoice ID
required: true
schema:
type: integer
- name: Authorization
in: header
description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).
'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/File'
'400':
description: Bad request / invalid data.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'401':
description: Unauthorized request.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
'503':
description: Database connection error.
content:
application/json:
schema:
$ref: '#/components/schemas/PayabliErrorBody'
components:
schemas:
File:
type: object
additionalProperties:
description: Any type
description: A file containing the response data, in the format specified in the request.
title: File
QuerySummary:
type: object
properties:
pageIdentifier:
$ref: '#/components/schemas/PageIdentifier'
pageSize:
$ref: '#/components/schemas/Pagesize'
totalAmount:
type: number
format: double
description: Total amount for the records.
totalNetAmount:
type: number
format: double
description: Total net amount for the records.
totalPages:
$ref: '#/components/schemas/Totalrecords'
totalRecords:
$ref: '#/components/schemas/Totalrecords'
title: QuerySummary
Shippingaddress:
type: string
description: The shipping address.
title: Shippingaddress
InvoiceId:
type: integer
format: int64
description: Identifier of invoice.
title: InvoiceId
FreightAmount:
type: number
format: double
description: Freight/shipping amount.
title: FreightAmount
PayabliErrorBodyResponseData:
type: object
properties:
explanation:
type: string
description: Human-readable explanation of what happened.
todoAction:
type: string
description: Suggested resolution.
description: Object with detailed error context.
title: PayabliErrorBodyResponseData
BillDataPaymentTerms:
type: string
enum:
- PIA
- CIA
- UR
- NET10
- NET20
- NET30
- NET45
- NET60
- NET90
- EOM
- MFI
- 5MFI
- 10MFI
- 15MFI
- 20MFI
- 2/10NET30
- UF
- 10UF
- 20UF
- 25UF
- 50UF
description: 'Payment terms for invoice. If no terms are defined, then response data for
this field defaults to `NET30`. Mirrors the values in
[`Terms`](#schema-terms).
'
title: BillDataPaymentTerms
Email:
type: string
format: email
description: Email address.
title: Email
BillingStateNullable:
type: string
description: Billing state. Must be a 2-letter state code for addresses in the US.
title: BillingStateNullable
BillingCountryNullable:
type: string
description: Billing address country.
title: BillingCountryNullable
CustomerStatus:
type: integer
description: 'Customer Status. Possible values:
- `-99` Deleted
- `0` Inactive
- `1` Active
- `85` Locked (typically due to multiple failed login attempts)
'
title: CustomerStatus
RoomIdNotInUse:
type: integer
format: int64
description: Field not in use on this endpoint. It always returns `0`.
title: RoomIdNotInUse
SummaryCommodityCode:
type: string
description: Commodity code.
title: SummaryCommodityCode
ItemUnitofMeasure:
type: string
description: Unit of measurement. Max length of 100 charact
# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/payabli/refs/heads/main/openapi/payabli-invoice-api-openapi.yml