Customer Invoices

Introduction

A customer invoice is usually an invoice that's a consequence of an order and as such is related to an order. However, Keyline also allows creating and therefore tracking invoices totally unrelated to an order and with arbitrary line items.

Lifecycle of a Customer Invoice

The most common way to interact with the customer_invoices endpoints, is to

  • create a record with a POST request
  • extract id attribute of the created customer invoice.
  • attach line_items to the invoice by way of issuing POST requests to the line_items resources of the invoice
  • declare the customer invoice as billed and therefore not editable anymore by setting the billed_at field to a valid date.

Additionally any customer invoice can be reverted at any point in time, resulting in the creation of a reversal invoice.

Attributes of a Customer Invoice object

address Object The invoicing address
billed_at datetime The date and time the invoice was billed to the customer
business_unit_id integer ID of the business unit this invoice belongs to
contact Object The number of the invoice
custom_references Object Key-value pairs custom to this invoice
custom_text text A custom free-form text that is added to the invoice.
customer_id integer ID of the customer this invoice belongs to.
due_at date The due date of the invoice
gross_total Money The gross total amount of the invoice
line_items line_item[] Array of line_item objects
net_total Money The net total amount of the invoice
number string The number of the invoice
order_id integer ID of the order this invoice belongs to. If this invoice is not associated with an order, this field is null
paid_at date The date the invoice was paid by the customer
reversal_invoice_id integer If this invoices was reversed, this field contains the ID of the reversal invoice, otherwise this field is null.
sent_at date Date when the invoice was sent to the customer
taxes Tax[] All taxes of the invoice, where the keys are the tax rates and the values are accrued amounts of all line items with the respective tax rate

Attributes that you can set via the API

The only mandatory attribute, when creating a customer invoice, is the customer_id.
Otherwise any combination of the below attributes can be provided to the POST and PATCH actions, to create or update a customer invoice, with a minimum of one attribute.

billed_at datetime The date and time when the invoice was or is billed to the customer. Once this date is set, the invoice is considered 'invoiced' and therefore final from an accounting perspective and can't be changed anymore.
business_unit_id integer ID of the business unit this invoice should belong to
customer_id integer ID of the customer this invoice should belong to
custom_text string A custom free-form text that is added to the invoice
due_at date The date and time when the invoice is due for payment
paid_at date The date the invoice was paid by the customer
sent_at date Date when the invoice was sent to the customer

Actions

Listing Customer Invoices

GET
/api/v1/customer_invoices

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  https://api.keyline-mis.com/api/v1/customer_invoices

Fetch a Single Customer Invoice

GET
/api/v1/customer_invoices/{customer_invoice_id}

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  https://api.keyline-mis.com/api/v1/customer_invoices/3689

Creating a Customer invoice

The only must-have attribute when creating a customer invoice is the customer_id.

POST
/api/v1/customer_invoices

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "customer_invoice": {
          "due_at": "2017-03-15",
          "customer_id": 1398
        }
      }
  '
  https://api.keyline-mis.com/api/v1/customer_invoices

Update a Customer invoice

All fields, except the customer_id, of a Customer invoices can be updated as long as billed_at is null. When trying to update an already billed customer invoice, the response's status code will be 422.

PATCH
/api/v1/customer_invoices/{customer_invoice_id}

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
        "customer_invoice": {
          "due_at": "2017-03-25",
          "custom_text": "This invoice can be payed later"
        }
      }
  '
  https://api.keyline-mis.com/api/v1/customer_invoices/3067

Delete a Customer Invoice

Customer invoices can be deleted as long as billed_at is null. When trying to delete an already billed customer invoice, the response's status code will be 422.

DELETE
/api/v1/customer_invoices/{customer_invoice_id}

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  -X DELETE \
  https://api.keyline-mis.com/api/v1/customer_invoices/3067

Reverse a Customer Invoice

Billed Customer Invoices can be reversed, that is a reversal invoice is created, which is a negation of the original customer invoice in all relevant aspects.

See the documentation about reversal invoices for more details.

POST
/api/v1/customer_invoices/{customer_invoice_id}/reverse

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  -X POST \
  -H "Content-Type: application/json" \
  https://api.keyline-mis.com/api/v1/customer_invoices/3688/reverse