Invoices

Xero provides a clean way of working with Xero invoices.

To work with invoices first call ->invocies() followed by a method.

Xero::invoices();

To list invoices, call the invoices()->get() method.

Xero docs for listing invoices - https://developer.xero.com/documentation/api/invoices#GET

Filtering Invoices

You can filter invoices using the filter method:

The filter can be chained to the get method, or you can use the filter method directly.

$query = Xero::invoices();

if ($invoiceNumber) {
    $query->filter('where', 'InvoiceNumber=="'.$invoiceNumber.'"');
}

if ($reference) {
    $query->filter('where', 'Reference=="'.$reference.'"');
}

if ($contactId) {
    $query->filter('where', 'ContactID==Guid("'.$contactId.'")');
}

if ($searchTerm) {
    $query->filter('searchTerm', $searchTerm);
}

if ($status) {
    $query->filter('where', 'Status=="'.$status.'"');
}

if ($fromDate) {
    $query->filter('where', 'Date>=DateTime('.$fromDate.')');
}

if ($toDate) {
    $query->filter('where', 'Date<=DateTime('.$toDate.')');
}

$query->filter('order', 'Date DESC')
->get();

Example Filters

Search term

Xero::invoices()
    ->filter('searchTerm', $searchTerm)
    ->get();

Search by ContactID

Xero::contacts()
    ->filter('where', 'ContactID==Guid("'.$this->contactId.'")');
    ->get();

Search by InvoiceNumber

Xero::contacts()
    ->filter('where', 'InvoiceNumber=="'.$this->invoiceNumber.'"')
    ->get();

Search by reference

Xero::contacts()
    ->filter('where', 'Reference=="'.$reference.'"')
    ->get();

Search by status

Xero::contacts()
    ->filter('where', 'Status=="'.$status.'"')
    ->get();

Search by fromDate

Xero::contacts()
    ->filter('where', 'Date>=DateTime('.$fromDate.')')
    ->get();

Search by toDate

Xero::contacts()
    ->filter('where', 'Date<=DateTime('.$toDate.')');
    ->get();

Paginate results

Xero::contacts()
    ->filter('page', 2)
    ->get();

Sort results

Xero::contacts()
    ->filter('order', 'Date DESC')
    ->get();

View Invoice

To view a single invoice, a find method can be called passing in the invoice id

Xero::invoices()->find(string $invoiceId);

View Online Invoice

For invoices created that have a status of either Submitted, Authorised, or Paid an online invoice can be seen by calling onlineUrl passing in the invoiceId

$url = Xero::invoices()->onlineUrl($invoiceId);

Create Invoice

To create an invoice, call a store method passing in an array of invoice data:

See https://developer.xero.com/documentation/api/invoices#post for the array contents specifications

use Dcblogdev\Xero\DTOs\InvoiceDTO;
use Dcblogdev\Xero\Enums\InvoiceType;
use Dcblogdev\Xero\Enums\InvoiceStatus;
use Dcblogdev\Xero\Enums\InvoiceLineAmountType;

// Using the DTO
$invoiceDTO = new InvoiceDTO(
    type: InvoiceType::AccRec->value,
    status: InvoiceStatus::Draft->value,
    lineAmountTypes: InvoiceLineAmountType::Exclusive->value,
    date: date('Y-m-d'),
    dueDate: date('Y-m-d', strtotime('+30 days')),
    contactID: 'contact-id'
);

// Add line items
$invoiceDTO->lineItems[] = InvoiceDTO::createLineItem(
    description: 'Web Development Services',
    quantity: 10,
    unitAmount: 100.00,
    accountCode: 200
);

// Create the invoice
$invoice = Xero::invoices()->store($invoiceDTO->toArray());

// Alternatively, create directly with an array
$invoice = Xero::invoices()->store([
    'Type' => 'ACCREC',
    'Status' => 'DRAFT',
    'LineAmountTypes' => 'Exclusive',
    'Date' => date('Y-m-d'),
    'DueDate' => date('Y-m-d', strtotime('+30 days')),
    'Contact' => [
        'ContactID' => 'contact-id'
    ],
    'LineItems' => [
        [
            'Description' => 'Web Development Services',
            'Quantity' => 10,
            'UnitAmount' => 100.00,
            'AccountCode' => 200
        ]
    ]
]);

Update Invoice

To update an invoice, 2 params are required the invoice Id and an array of data to be updated:

See https://developer.xero.com/documentation/api/invoices#post for details on the fields that can be updated.

Xero::invoices()->update($invoiceId, $data);

//Example
$invoice = Xero::invoices()->update('invoice-id', [
    'Status' => 'AUTHORISED',
    'Reference' => 'Updated Reference'
]);

Working with Invoice Attachments

To get all attachments for an invoice:

$attachments = Xero::invoices()->attachments('invoice-id');

To get a specific attachment:

// By attachment ID
$attachment = Xero::invoices()->attachment('invoice-id', 'attachment-id');

// By filename
$attachment = Xero::invoices()->attachment('invoice-id', null, 'filename.pdf');