/api/p/v{version}/invoices

The Invoices endpoint allows you to retrieve detailed information about a specific invoice using its unique ID and version. To ensure compatibility and stability, it is essential to include the correct version number in the URL path when making a request. For more information on versioning, refer to the Versioning page.

Request Parameters

The following parameters are required in the URL path:

Parameter	Type	Required	Description
id	String	Conditionally	The unique Alvys identifier of the invoice. This field is required if the other conditionally required fields are left empty.
invoice_number	String	Conditionally	The invoice number to retrieve details. This field is required if the other conditionally required fields are left empty.
version	String	Yes	The API version to interact with.

Example CURL request

CURL Example using Invoice ID:

curl --location 'https://integrations.alvys.com/api/p/v{version}/invoices?id={invoiceId}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

CURL Example using Invoice Number:

curl --location 'https://integrations.alvys.com/api/p/v{version}/invoices?invoiceNumber={invoiceNumber}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Replace {version} with the API version number, {invoiceNumber} with the actual invoice number, and YOUR_ACCESS_TOKEN with your actual Bearer token:

Using Invoice ID:

curl --location 'https://integrations.alvys.com/api/p/v1/invoices?id=15fd1695595a48a48163490e3f21ddd6' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpX....'

Using Invoice Number:

curl --location 'https://integrations.alvys.com/api/p/v1/invoices?invoiceNumber=123456789' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpX....'

Response Parameters

The following table lists the parameters included in the response for invoice-related requests.

Parameter	Type	Description
id	String	The unique identifier of the invoice.
number	String	The invoice number.
type	String	The type of the invoice (e.g., Standard, Credit Memo).
status	String	The current status of the invoice (e.g., Open, Paid, Overdue).
createdDate	String (Date-Time)	The date and time when the invoice was created.
invoicedDate	String (Date-Time)	The date and time when the invoice was issued.
dueDate	String (Date-Time)	The due date for the invoice payment.
paidDate	String (Date-Time)	The date when the invoice was fully paid.
total	Object	The total amount of the invoice.
total.amount	Number	The monetary value of the total amount.
total.currency	String	The currency in which the invoice is issued.
amountPaid	Object	The amount that has been paid towards the invoice.
amountPaid.amount	Number	The monetary value of the amount paid.
amountPaid.currency	String	The currency in which the payment was made.
remainingBalance	Object	The remaining balance due on the invoice.
remainingBalance.amount	Number	The monetary value of the remaining balance.
remainingBalance.currency	String	The currency in which the balance is due.
overPaymentAmount	Object	The overpayment amount if any.
overPaymentAmount.amount	Number	The monetary value of the overpayment.
overPaymentAmount.currency	String	The currency in which the overpayment was made.
isSubmitted	Boolean	Indicates if the invoice has been submitted.
lastSendDate	String (Date-Time)	The last date and time when the invoice was sent.
supplementalInvoiceType	String	The type of supplemental invoice if applicable.
vendor	Object	Vendor details associated with the invoice.
vendor.id	String	The unique identifier of the vendor.
vendor.name	String	The name of the vendor.
vendor.remitAddress	Object	The remit address of the vendor.
vendor.remitAddress.street	String	The street address of the vendor.
vendor.remitAddress.city	String	The city of the vendor's address.
vendor.remitAddress.state	String	The state of the vendor's address.
vendor.remitAddress.zipCode	String	The zip code of the vendor's address.
vendor.remitEmail	String	The email address for remittances to the vendor.
vendor.remitPhone	String	The phone number for remittances to the vendor.
customer	Object	Customer details associated with the invoice.
customer.id	String	The unique identifier of the customer.
customer.name	String	The name of the customer.
customer.emailAddresses	Array of Strings	The list of email addresses for the customer.
customer.phoneNumbers	Array of Strings	The list of phone numbers for the customer.
customer.billingAddress	Object	The billing address of the customer.
customer.billingAddress.street	String	The street address of the customer.
customer.billingAddress.city	String	The city of the customer's billing address.
customer.billingAddress.state	String	The state of the customer's billing address.
customer.billingAddress.zipCode	String	The zip code of the customer's billing address.
customer.shippingAddress	Object	The shipping address of the customer.
customer.shippingAddress.street	String	The street address of the customer.
customer.shippingAddress.city	String	The city of the customer's shipping address.
customer.shippingAddress.state	String	The state of the customer's shipping address.
customer.shippingAddress.zipCode	String	The zip code of the customer's shipping address.
lineItems	Array of Objects	The line items included in the invoice.
lineItems.id	String	The unique identifier of the line item.
lineItems.name	String	The name of the line item.
lineItems.amount	Object	The amount associated with the line item.
lineItems.amount.amount	Number	The monetary value of the line item.
lineItems.amount.currency	String	The currency in which the line item is priced.
lineItems.rate	Object	The rate details for the line item.
lineItems.rate.unitOfMeasurement	String	The unit of measurement for the rate (e.g., hours, miles).
lineItems.rate.units	Number	The number of units billed.
lineItems.rate.rate	Number	The rate per unit.
lineItems.loadNumber	String	The load number associated with the line item.
lineItems.customerId	String	The customer ID associated with the line item.
lineItems.category	String	The category of the line item.
loads	Array of Objects	The loads associated with the invoice.
loads.id	String	The unique identifier of the load.
loads.loadNumber	String	The load number associated with the invoice.
loads.subsidiaryName	String	The name of the subsidiary associated with the load.
loads.source	String	The source of the load.
loads.orderNumber	String	The order number associated with the load.
loads.poNumber	String	The purchase order number associated with the load.
payments	Array of Objects	The payments made against the invoice.
payments.id	String	The unique identifier of the payment.
payments.paymentDate	String (Date-Time)	The date and time when the payment was made.
payments.amount	Object	The amount paid in the payment.
payments.amount.amount	Number	The monetary value of the payment.
payments.amount.currency	String	The currency in which the payment was made.
payments.checkNumber	String	The check number associated with the payment.
payments.paymentReference	String	The payment reference number.

Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the Rate Limits page.

This page is interactive, allowing you to try a request by specifying the API version in the URL path and providing the necessary request body. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.