Supplier Invoices

Introduction

A supplier invoice is an invoice, that your printery has received from one of it's suppliers, and which you want to track with Keyline. Tracking supplier invoices with Keyline, allows you to associate material orders, which might get triggered by customer orders, to supplier invoices, which in turn allows for full tracking of all costs that are associated with an order and it's associated products.

Lifecycle of a Supplier Invoice

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

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

Supplier invoices can be created and updated with any combination of the below listed attributes, as long as at least one attribute is specified. A supplier invoice is not editable anymore as soon as the checked_at attribute is set. Once this is the case, the PATCH and DELETE actions will return a 403 status code.

Note, that supplier invoices are different from customer invoices in many respects. Most important is, the significance of the billed_at field. While customer invoices can't be changed once billed_at is set to a date, the same is not true for supplier invoices.

Attributes of a Supplier Invoice object

billed_at datetime The date and time when the invoice was billed
checked_at datetime The date and time when the invoice was checked. Once this date is set, the invoice can't be changed anymore.
custom_text string A custom free-form text that has been set for this invoice
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 The ID of the associated order
paid_at date The date when the invoice was paid
supplier_id integer The ID of the associated supplier
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 you send to Keyline to Create or Update a Supplier Invoice

The only mandatory attribute, when creating a supplier invoice, is the supplier_id.
Otherwise and as mentioned above, any combination of attributes can be provided to the POST and PATCH actions, to create or update a supplier invoice, with a minimum of one attribute.

billed_at datetime The date and time when the invoice was billed
checked_at datetime The date and time when the invoice was checked. Once this date is set, the invoice can't be changed anymore.
custom_text string A custom free-form text that has been set for this invoice
due_at date The due date of the invoice
number string The number of the invoice
order_id integer The ID of the associated order
paid_at date The date when the invoice was paid
supplier_id integer The ID of the associated supplier

Actions

Listing Supplier Invoices

GET
/api/v1/supplier_invoices

Example Request

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

Fetch a Single Supplier Invoice

GET
/api/v1/supplier_invoices/{supplier_invoice_id}

Example Request

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

Creating a Supplier invoice

The only must-have attribute when creating a supplier invoice is the supplier_id.

POST
/api/v1/supplier_invoices

Example Request

$ curl -i -H "Authorization: Bearer a2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "supplier_invoice": {
          "billed_at": "2017-02-21",
          "due_at": "2017-03-15",
          "number": "13-XC 456",
          "supplier_id": 36
        }
      }
  '
  https://api.keyline-mis.com/api/v1/supplier_invoices

Update a Supplier invoice

Supplier invoices can be updated as long as checked_at is null. When trying to update an already checked supplier invoice, the response's status code will be 422.

PATCH
/api/v1/supplier_invoices/{supplier_invoice_id}

Example Request

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

Delete a Supplier invoice

Supplier invoices can be deleted as long as checked_at is null. When trying to delete an already checked supplier invoice, the response's status code will be 422.

DELETE
/api/v1/supplier_invoices/{supplier_invoice_id}

Example Request

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