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

Get a paginated list of all invoices

Query parameters

final_price_incl_taxstring · number or rangeOptional

Filter invoices by invoiced price

Example: 500,1000

created_atstring · date-time rangeOptional

Filter invoices by the date they were generated on

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

closed_atstring · date-time or date-time rangeOptional

Filter invoices by the date they were closed on

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

numberstring · number or rangeOptional

Filter invoices by number

Example: 15

booking_created_atstring · date-time or date-time rangeOptional

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

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

booking_statusstring · enumOptional

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

Possible values:

is_closedbooleanOptional

Filter between closed or draft invoices

booking_locationinteger[]Optional

Filter invoices by the location of the booking they belong to

Example: 15,227

currencystring · iso-4217 currency codeOptional

Filter invoices by the currency they are issued in

Example: EUR

Responses

200

List of invoices

application/json

get

GET /private/invoices HTTP/1.1
Host: api.bookinglayer.io
Accept: */*

200

List of invoices

{
  "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",
      "reference": {
        "number": 1,
        "prefix": "INV-",
        "suffix": "-UK",
        "full": "INV-0001-UK"
      },
      "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"
    },
    {
      "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",
      "reference": {
        "number": 1,
        "prefix": "INV-",
        "suffix": "-UK",
        "full": "INV-0001-UK"
      },
      "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"
    }
  ]
}

List booking invoices

get

Get a list of invoices for a single booking

Path parameters

booking_idstring · uuidRequired

ID of the booking

Responses

200

List of invoices

application/json

get

GET /private/bookings/{booking_id}/invoices HTTP/1.1
Host: api.bookinglayer.io
Accept: */*

200

List of invoices

{
  "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",
      "reference": {
        "number": 1,
        "prefix": "INV-",
        "suffix": "-UK",
        "full": "INV-0001-UK"
      },
      "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"
    },
    {
      "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",
      "reference": {
        "number": 1,
        "prefix": "INV-",
        "suffix": "-UK",
        "full": "INV-0001-UK"
      },
      "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"
    }
  ]
}

Generate an invoice

post

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.

Body

guest_uuidstring · uuid | nullableOptional

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

amountnumber · float | nullableOptional

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

percentagenumber · float | nullableOptional

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

remainderboolean | nullableOptional

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

payment_idsstring · uuid[] | nullableOptional

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

201

Invoice has successfully been created.

application/json

400

Invoice creation is not possible at the present time.

application/json

422

The sent request is invalid.

application/json

post

POST /private/bookings/{booking_id}/invoices/payment HTTP/1.1
Host: api.bookinglayer.io
Content-Type: application/json
Accept: */*
Content-Length: 151

{
  "guest_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 1,
  "percentage": 1,
  "remainder": true,
  "payment_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

{
  "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",
    "reference": {
      "number": 1,
      "prefix": "INV-",
      "suffix": "-UK",
      "full": "INV-0001-UK"
    },
    "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"
  }
}

Fetch single invoice

get

Path parameters

booking_idstring · uuidRequired

ID of the booking

invoice_idstring · uuidRequired

ID of the invoice

Responses

200

List of invoices

application/json

get

GET /private/bookings/{booking_id}/invoices/{invoice} HTTP/1.1
Host: api.bookinglayer.io
Accept: */*

200

List of invoices

{
  "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",
    "reference": {
      "number": 1,
      "prefix": "INV-",
      "suffix": "-UK",
      "full": "INV-0001-UK"
    },
    "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"
  }
}

Update invoice

put

Path parameters

booking_idstring · uuidRequired

ID of the booking

invoice_idstring · uuidRequired

ID of the invoice

Body

commentstring | nullableOptional

numberinteger | nullableOptional

Invoice number.

closed_atstring · date-time | nullableOptional

The date and time the invoice was closed.

prefixstring | nullableOptional

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

suffixstring | nullableOptional

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

Responses

204

Invoice successfully updated

400

Invoice cannot be updated with the provided data at the present time.

application/json

422

The sent request is invalid.

application/json

put

PUT /private/bookings/{booking_id}/invoices/{invoice} HTTP/1.1
Host: api.bookinglayer.io
Content-Type: application/json
Accept: */*
Content-Length: 100

{
  "comment": "text",
  "number": 1,
  "closed_at": "2025-07-02T10:18:51.240Z",
  "prefix": "text",
  "suffix": "text"
}

No content

Delete an invoice

delete

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.

Path parameters

booking_idstring · uuidRequired

ID of the booking

invoice_idstring · uuidRequired

ID of the invoice

Responses

204

Invoice was successfully deleted.

400

Invoice cannot be deleted at the present time, most likely a credit note for the invoice exists.

application/json

delete

DELETE /private/bookings/{booking_id}/invoices/{invoice} HTTP/1.1
Host: api.bookinglayer.io
Accept: */*

No content

Download invoice PDF

get

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

Path parameters

booking_idstring · uuidRequired

ID of the booking

invoice_idstring · uuidRequired

ID of the invoice

Responses

200

File download containing the invoice in PDF format.

get

GET /private/bookings/{booking_id}/invoices/{invoice_id}/pdf HTTP/1.1
Host: api.bookinglayer.io
Accept: */*

200

File download containing the invoice in PDF format.

No content

PreviousBookers NextBooking

Last updated 1 year ago