Invoices

Businesses are able to create and manage invoices for their bookings on Bookinglayer.

The Invoice object

{
    "data": {
        "id": "a7443538-95e8-4ac9-b252-82d55b7887e9",
        "date": "2023-07-04T12:55:54+00:00",
        "due_date": "2023-07-18T12:55:54+00:00",
        "status": "closed",
        "reference": {
            "full": "20237322",
            "prefix": "20237",
            "suffix": "",
            "number": 322
        },
        "total_price_excl_tax": 2181.82,
        "final_price_incl_tax": 2400,
        "discount_total": 0,
        "final_price_excl_tax": 2181.82,
        "total_price_incl_tax": 2400,
        "tax_component": 218.18,
        "discounted_tax": 0,
        "final_tax_component": 0,
        "creditable_amount": 0,
        "credit_total": 0,
        "amount_due": 0,
        "amount_paid": 2400,
        "display": "items",
        "comment": null,
        "currency": "EUR",
        "tax_breakdown": {
            {
                "rate": 10,
                "amount": 218.18,
                "final_price_excl": 2181.82
            }
        }
        "booking": {
            "id": "2361736f-1646-426d-acf6-04c4f9d785dd"
        },
        "payments": [
            {
                "id": "ed3b8ffa-6ea7-4019-a9ba-3045caa7ab85",
                "currency": "EUR",
                "amount": 2400,
                "refund_amount": 0,
                "surcharge": 0,
                "status": "ok",
                "cc_brand": null,
                "cc_last4": null,
                "foreign_currency": null,
                "amount_in_foreign_currency": null,
                "transaction_reference": null,
                "comment": null,
                "metadata": null,
                "ip_address": null,
                "user": {
                    "id": "c6eef2d5-1019-11e9-bd3b-04016aacf401"
                },
                "booking": {
                    "id": "2361736f-1646-426d-acf6-04c4f9d785dd"
                },
                "guest": null,
                "invoice": {
                    "id": "a7443538-95e8-4ac9-b252-82d55b7887e9"
                },
                "payment_gateway": {
                    "id": 57,
                    "backoffice_title": "On site",
                    "slug": "onsite",
                    "description": "Activate this if you want to give bookers the option on your Payment Form to select an on site payment.",
                    "is_frontoffice": true,
                    "has_icon": false,
                    "invoicexpress_code": "OU",
                    "is_bookinglayer_pro": false,
                    "provider": null,
                    "provider_url": null,
                    "knowledge_base_link": null,
                    "notifications": null,
                    "created_at": "2018-12-05T17:47:23.000000Z",
                    "updated_at": "2020-10-22T11:38:56.000000Z",
                    "frontoffice": true,
                    "title": "On site",
                    "frontoffice_title": "On site"
                },
                "gift_certificate": null,
                "paid_at": "2023-07-03T12:57:00+00:00",
                "deleted_at": null,
                "created_at": "2023-07-03T10:57:52+00:00",
                "updated_at": "2023-07-04T12:56:00+00:00",
                "status_message": null,
                "channel": "backoffice"
            }
        ],
        "lines": [
            {
                "id": 4744208,
                "title": "Room Jenny",
                "title_translation": {
                    "en": null
                },
                "package_title": null,
                "package_title_translation": null,
                "unit_price_incl_tax": 200,
                "qty": 4,
                "total_price_incl_tax": 800,
                "discount_value": 0,
                "discount_rate": 0,
                "final_price_incl_tax": 800,
                "tax_rate": "10.00",
                "tax_value": 72.73,
                "creditable_amount": 0,
                "credit_total": 0,
                "deleted_at": null,
                "created_at": "2023-07-04T12:55:50+00:00",
                "updated_at": "2023-07-04T12:55:50+00:00"
            },
            {
                "id": 4744209,
                "description": "Room Jenny",
                "description_translation": {
                    "en": null
                },
                "package_title_translation": null,
                "unit_price_incl_tax": 200,
                "qty": 4,
                "total_price_incl_tax": 800,
                "discount_value": 0,
                "discount_rate": 0,
                "final_price_incl_tax": 800,
                "tax_rate": "0.00",
                "tax_value": 0,
                "creditable_amount": 0,
                "credit_total": 0,
                "deleted_at": null,
                "created_at": "2023-07-04T12:55:50+00:00",
                "updated_at": "2023-07-04T12:55:50+00:00"
            },
            {
                "id": 4744210,
                "description": "Room Jenny",
                "description_translation": {
                    "en": null
                },
                "package_title_translation": null,
                "unit_price_incl_tax": 200,
                "qty": 4,
                "total_price_incl_tax": 800,
                "discount_value": 0,
                "discount_rate": 0,
                "final_price_incl_tax": 800,
                "tax_rate": "0.00",
                "tax_value": 0,
                "creditable_amount": 0,
                "credit_total": 0,
                "deleted_at": null,
                "created_at": "2023-07-04T12:55:50+00:00",
                "updated_at": "2023-07-04T12:55:50+00:00"
            }
        ],
        "exports": [
            {
                "service": "fatture_in_cloud",
                "external_id": 553232,
                "status": "sent"
            }
        ],
        "created_at": "2023-07-04T12:55:50+00:00",
        "updated_at": "2023-07-04T12:56:01+00:00"
    }
}

id

Unique id of the invoice

date

The date when an invoice was closed.

due_date

The date by which payment for an invoice is expected to be received.

status

The current status of an invoice. Might be closed or draft

reference

The object with four fields: full - represents full invoice reference, prefix and suffix which are static parts of reference based on business settings, number with is integer that represents sequence.

final_price_incl_tax

The final price including all taxes.

final_price_excl_tax

The final price excluding taxes. (Net final price)

total_price_incl_tax

The total price including taxes. It is final price including taxes without discounts applied.

total_price_excl_tax

The total price excluding taxes. It is final price excluding taxes without discount applied.

discount_total

The discount including tax.

discounted_tax

The discounted tax part.

final_tax_component

The tax component after discount.

tax_component

The tax component before discount.

creditable_amount

Represents negative difference between invoiced booking lines final price including tax and current booking lines total.

credit_total

Total from invoice credit notes.

amount_due

The amount to be paid by the client.

amount_paid

Amount paid by the client up to the present time.

display

The strategy used for printing invoice PDF's, can have one of three values:

• items

• package

• hybrid

comment

Arbirtrary comment.

currency

Currency the invoice is issued in.

tax_breakdown

An array of objects containing the tax amounts per tax rate. Each object contains the tax rate, the taxable amount and the tax amount.

booking

Expandable object containing the booking the invoice belongs to.

payments

Expandable array of payments bound to the invoice.

lines

Expandable array of lines contained within the invoice.

exports

Array of objects with exports of the invoice to external systems.

created_at

Datetime when the invoice was created.

updated_at

Datetime when the invoice was last updated.

Endpoints

List invoices

Get a paginated list of all invoices

get

/invoices

Query parameters

final_price_incl_taxstring · number or range

Filter invoices by invoiced price

Example: 500,1000

created_atstring · date-time range

Filter invoices by the date they were generated on

Example: 2024-05-10,2024-05-15

closed_atstring · date-time or date-time range

Filter invoices by the date they were closed on

Example: 2024-05-10,2024-05-15

numberstring · number or range

Filter invoices by number

Example: 15

booking_created_atstring · date-time or date-time range

Filter invoices by the date the booking they belong to was created on

Example: 2024-05-10,2024-05-15

booking_statusstring · enum

Filter invoices by the the status of the booking they belong to

Options: pending, confirmed, deposit_paid, paid, cancelled, expired, waiting_list

is_closedboolean

Filter between closed or draft invoices

booking_locationinteger[]

Filter invoices by the location of the booking they belong to

Example: 15,227

currencystring · iso-4217 currency code

Filter invoices by the currency they are issued in

Example: EUR

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bookinglayer.io/private/invoices'

200

200

{
  "data": [
    {
      "date": "2000-01-23T04:56:07.000+00:00",
      "discount_total": 0,
      "amount_paid": 71,
      "metadata": "{}",
      "total_price_incl_tax": 121,
      "created_at": "2000-01-23T04:56:07.000+00:00",
      "booking_id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
      "updated_at": "2000-01-23T04:56:07.000+00:00",
      "discounted_tax": 0,
      "final_price_excl_tax": 100,
      "amount_due": 50,
      "currency": "EUR",
      "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
      "total_price_excl_tax": 100,
      "tax_component": 21,
      "final_price_incl_tax": 121,
      "credit_total": 0,
      "display": "package",
      "due_date": "2000-01-23T04:56:07.000+00:00",
      "final_tax_component": 21,
      "deleted_at": "2000-01-23T04:56:07.000+00:00",
      "comment": "comment",
      "creditable_amount": 0,
      "status": "draft",
      "reference": {
        "number": 1,
        "prefix": "INV-",
        "suffix": "-UK",
        "full": "INV-0001-UK"
      }
    },
    {
      "date": "2000-01-23T04:56:07.000+00:00",
      "discount_total": 0,
      "amount_paid": 71,
      "metadata": "{}",
      "total_price_incl_tax": 121,
      "created_at": "2000-01-23T04:56:07.000+00:00",
      "booking_id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
      "updated_at": "2000-01-23T04:56:07.000+00:00",
      "discounted_tax": 0,
      "final_price_excl_tax": 100,
      "amount_due": 50,
      "currency": "EUR",
      "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
      "total_price_excl_tax": 100,
      "tax_component": 21,
      "final_price_incl_tax": 121,
      "credit_total": 0,
      "display": "package",
      "due_date": "2000-01-23T04:56:07.000+00:00",
      "final_tax_component": 21,
      "deleted_at": "2000-01-23T04:56:07.000+00:00",
      "comment": "comment",
      "creditable_amount": 0,
      "status": "draft",
      "reference": {
        "number": 1,
        "prefix": "INV-",
        "suffix": "-UK",
        "full": "INV-0001-UK"
      }
    }
  ]
}

List of invoices

List booking invoices

Get a list of invoices for a single booking

get

/bookings/{booking_id}/invoices

Path parameters

booking_idstring · uuidrequired

ID of the booking

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bookinglayer.io/private/bookings/{booking_id}/invoices'

200

200

{
  "data": [
    {
      "date": "2000-01-23T04:56:07.000+00:00",
      "discount_total": 0,
      "amount_paid": 71,
      "metadata": "{}",
      "total_price_incl_tax": 121,
      "created_at": "2000-01-23T04:56:07.000+00:00",
      "booking_id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
      "updated_at": "2000-01-23T04:56:07.000+00:00",
      "discounted_tax": 0,
      "final_price_excl_tax": 100,
      "amount_due": 50,
      "currency": "EUR",
      "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
      "total_price_excl_tax": 100,
      "tax_component": 21,
      "final_price_incl_tax": 121,
      "credit_total": 0,
      "display": "package",
      "due_date": "2000-01-23T04:56:07.000+00:00",
      "final_tax_component": 21,
      "deleted_at": "2000-01-23T04:56:07.000+00:00",
      "comment": "comment",
      "creditable_amount": 0,
      "status": "draft",
      "reference": {
        "number": 1,
        "prefix": "INV-",
        "suffix": "-UK",
        "full": "INV-0001-UK"
      }
    },
    {
      "date": "2000-01-23T04:56:07.000+00:00",
      "discount_total": 0,
      "amount_paid": 71,
      "metadata": "{}",
      "total_price_incl_tax": 121,
      "created_at": "2000-01-23T04:56:07.000+00:00",
      "booking_id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
      "updated_at": "2000-01-23T04:56:07.000+00:00",
      "discounted_tax": 0,
      "final_price_excl_tax": 100,
      "amount_due": 50,
      "currency": "EUR",
      "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
      "total_price_excl_tax": 100,
      "tax_component": 21,
      "final_price_incl_tax": 121,
      "credit_total": 0,
      "display": "package",
      "due_date": "2000-01-23T04:56:07.000+00:00",
      "final_tax_component": 21,
      "deleted_at": "2000-01-23T04:56:07.000+00:00",
      "comment": "comment",
      "creditable_amount": 0,
      "status": "draft",
      "reference": {
        "number": 1,
        "prefix": "INV-",
        "suffix": "-UK",
        "full": "INV-0001-UK"
      }
    }
  ]
}

List of invoices

Generate an invoice

Generate an invoice for a booking. You can create an amount, percentage or remainder ID. You can also assign invoices to guests or payments, depending on your settings.

post

/bookings/{booking_id}/invoices/payment

Body

guest_uuidstring · uuid | nullable

Guest to assign to invoice. Required if other invoices for the booking are per-guest.

amountnumber · float | nullable

Amount to invoice. Required when percentage or remainder are not specified.

percentagenumber · float · min: 1 · max: 100 | nullable

Percentage of the booking final amount to invoice. Required if amount or remainder are not specified.

remainderboolean | nullable

If enabled the whole un-invoiced amount will be invoiced. Required if amount or percentage are not specified.

payment_idsstring · uuid[] | nullable

List of ID's to generate an invoice for. Generates an invoice for the sum of all paid amounts or for the sum of the whole booking, depending on which is larger. Required if amount, percentage or remainder are not specified.

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.bookinglayer.io/private/bookings/{booking_id}/invoices/payment' \
  --header 'Content-Type: application/json' \
  --data '{"payment_ids":[null]}'

201

400

422

201

{
  "data": {
    "date": "2000-01-23T04:56:07.000+00:00",
    "discount_total": 0,
    "amount_paid": 71,
    "metadata": "{}",
    "total_price_incl_tax": 121,
    "created_at": "2000-01-23T04:56:07.000+00:00",
    "booking_id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
    "updated_at": "2000-01-23T04:56:07.000+00:00",
    "discounted_tax": 0,
    "final_price_excl_tax": 100,
    "amount_due": 50,
    "currency": "EUR",
    "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
    "total_price_excl_tax": 100,
    "tax_component": 21,
    "final_price_incl_tax": 121,
    "credit_total": 0,
    "display": "package",
    "due_date": "2000-01-23T04:56:07.000+00:00",
    "final_tax_component": 21,
    "deleted_at": "2000-01-23T04:56:07.000+00:00",
    "comment": "comment",
    "creditable_amount": 0,
    "status": "draft",
    "reference": {
      "number": 1,
      "prefix": "INV-",
      "suffix": "-UK",
      "full": "INV-0001-UK"
    }
  }
}

Invoice has successfully been created.

Fetch single invoice

get

/bookings/{booking_id}/invoices/{invoice}

Path parameters

booking_idstring · uuidrequired

ID of the booking

invoice_idstring · uuidrequired

ID of the invoice

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bookinglayer.io/private/bookings/{booking_id}/invoices/{invoice}'

200

200

{
  "data": {
    "date": "2000-01-23T04:56:07.000+00:00",
    "discount_total": 0,
    "amount_paid": 71,
    "metadata": "{}",
    "total_price_incl_tax": 121,
    "created_at": "2000-01-23T04:56:07.000+00:00",
    "booking_id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
    "updated_at": "2000-01-23T04:56:07.000+00:00",
    "discounted_tax": 0,
    "final_price_excl_tax": 100,
    "amount_due": 50,
    "currency": "EUR",
    "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
    "total_price_excl_tax": 100,
    "tax_component": 21,
    "final_price_incl_tax": 121,
    "credit_total": 0,
    "display": "package",
    "due_date": "2000-01-23T04:56:07.000+00:00",
    "final_tax_component": 21,
    "deleted_at": "2000-01-23T04:56:07.000+00:00",
    "comment": "comment",
    "creditable_amount": 0,
    "status": "draft",
    "reference": {
      "number": 1,
      "prefix": "INV-",
      "suffix": "-UK",
      "full": "INV-0001-UK"
    }
  }
}

List of invoices

Update invoice

put

/bookings/{booking_id}/invoices/{invoice}

Path parameters

booking_idstring · uuidrequired

ID of the booking

invoice_idstring · uuidrequired

ID of the invoice

Body

commentstring | nullable

numberinteger | nullable

Invoice number.

closed_atstring · date-time | nullable

The date and time the invoice was closed.

prefixstring | nullable

The prefix placed before the invoice number within the invoice reference.

suffixstring | nullable

The suffix placed after the invoice number within the invoice reference.

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url 'https://api.bookinglayer.io/private/bookings/{booking_id}/invoices/{invoice}' \
  --header 'Content-Type: application/json'

204

400

422

204

No body

Invoice successfully updated

Delete an invoice

Delete an invoice. Both draft and closed invoices can be deleted, however invoices that have previously been credited cannot be deleted as long as their credit note(s) exists.

delete

/bookings/{booking_id}/invoices/{invoice}

Path parameters

booking_idstring · uuidrequired

ID of the booking

invoice_idstring · uuidrequired

ID of the invoice

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://api.bookinglayer.io/private/bookings/{booking_id}/invoices/{invoice}'

204

400

204

No body

Invoice was successfully deleted.

Download invoice PDF

Download an invoice with all of its items in PDF format.

get

/bookings/{booking_id}/invoices/{invoice_id}/pdf

Path parameters

booking_idstring · uuidrequired

ID of the booking

invoice_idstring · uuidrequired

ID of the invoice

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bookinglayer.io/private/bookings/{booking_id}/invoices/{invoice_id}/pdf'

200

200

No body

File download containing the invoice in PDF format.