Invoices¶
Resource description¶
The invoice resource contains the following public fields:
Field |
Type |
Description |
---|---|---|
number |
string |
Invoice number (with prefix) |
event |
string |
The slug of the parent event |
order |
string |
Order code of the order this invoice belongs to |
is_cancellation |
boolean |
|
invoice_from_name |
string |
Sender address: Name |
invoice_from |
string |
Sender address: Address lines |
invoice_from_zipcode |
string |
Sender address: ZIP code |
invoice_from_city |
string |
Sender address: City |
invoice_from_country |
string |
Sender address: Country code |
invoice_from_tax_id |
string |
Sender address: Local Tax ID |
invoice_from_vat_id |
string |
Sender address: EU VAT ID |
invoice_to |
string |
Full recipient address |
invoice_to_company |
string |
Recipient address: Company name |
invoice_to_name |
string |
Recipient address: Person name |
invoice_to_street |
string |
Recipient address: Address lines |
invoice_to_zipcode |
string |
Recipient address: ZIP code |
invoice_to_city |
string |
Recipient address: City |
invoice_to_state |
string |
Recipient address: State (only used in some countries) |
invoice_to_country |
string |
Recipient address: Country code |
invoice_to_vat_id |
string |
Recipient address: EU VAT ID |
invoice_to_beneficiary |
string |
Invoice beneficiary |
custom_field |
string |
Custom invoice address field |
date |
date |
Invoice date |
refers |
string |
Invoice number of an invoice this invoice refers to
(for example a cancellation refers to the invoice it
cancels) or |
locale |
string |
Invoice locale |
introductory_text |
string |
Text to be printed above the product list |
additional_text |
string |
Text to be printed below the product list |
payment_provider_text |
string |
Text to be printed below the product list with payment information |
payment_provider_stamp |
string |
Short text to be visibly printed to indicate payment status |
footer_text |
string |
Text to be printed in the page footer area |
lines |
list of objects |
The actual invoice contents |
├ position |
integer |
Number of the line within an invoice. |
├ description |
string |
Text representing the invoice line (e.g. product name) |
├ item |
integer |
Product used to create this line. Note that everything
about the product might have changed since the creation
of the invoice. Can be |
├ variation |
integer |
Product variation used to create this line. Note that everything
about the product might have changed since the creation
of the invoice. Can be |
├ subevent |
integer |
Event series date ID used to create this line. Note that everything
about the subevent might have changed since the creation
of the invoice. Can be |
├ fee_type |
string |
Fee type, e.g. |
├ fee_internal_type |
string |
Additional fee type, e.g. type of payment provider. Can be |
├ event_date_from |
datetime |
Start date of the (sub)event this line was created for as it
was set during invoice creation. Can be |
├ event_date_to |
datetime |
End date of the (sub)event this line was created for as it
was set during invoice creation. Can be |
├ event_location |
string |
Location of the (sub)event this line was created for as it
was set during invoice creation. Can be |
├ attendee_name |
string |
Attendee name at time of invoice creation. Can be |
├ gross_value |
money (string) |
Price including taxes |
├ tax_value |
money (string) |
Tax amount included |
├ tax_name |
string |
Name of used tax rate (e.g. “VAT”) |
└ tax_rate |
decimal (string) |
Used tax rate |
foreign_currency_display |
string |
If the invoice should also show the total and tax
amount in a different currency, this contains the
currency code ( |
foreign_currency_rate |
decimal (string) |
If |
foreign_currency_rate_date |
date |
If |
internal_reference |
string |
Customer’s reference to be printed on the invoice. |
Changed in version 4.1: The attributes fee_type
and fee_internal_type
have been added.
Changed in version 4.1: The attribute lines.event_location
has been added.
Changed in version 4.6: The attribute lines.subevent
has been added.
Changed in version 2023.8: The event
attribute has been added. The organizer-level endpoint has been added.
List of all invoices¶
- GET /api/v1/organizers/(organizer)/events/(event)/invoices/¶
Returns a list of all invoices within a given event.
Example request:
GET /api/v1/organizers/bigevents/events/sampleconf/invoices/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "count": 1, "next": null, "previous": null, "results": [ { "number": "SAMPLECONF-00001", "event": "sampleconf", "order": "ABC12", "is_cancellation": false, "invoice_from_name": "Big Events LLC", "invoice_from": "Demo street 12", "invoice_from_zipcode":"", "invoice_from_city":"Demo town", "invoice_from_country":"US", "invoice_from_tax_id":"", "invoice_from_vat_id":"", "invoice_to": "Sample company\nJohn Doe\nTest street 12\n12345 Testington\nTestikistan\nVAT-ID: EU123456789", "invoice_to_company": "Sample company", "invoice_to_name": "John Doe", "invoice_to_street": "Test street 12", "invoice_to_zipcode": "12345", "invoice_to_city": "Testington", "invoice_to_state": null, "invoice_to_country": "TE", "invoice_to_vat_id": "EU123456789", "invoice_to_beneficiary": "", "custom_field": null, "date": "2017-12-01", "refers": null, "locale": "en", "introductory_text": "thank you for your purchase of the following items:", "internal_reference": "", "additional_text": "We are looking forward to see you on our conference!", "payment_provider_text": "Please transfer the money to our account ABC…", "payment_provider_stamp": null, "footer_text": "Big Events LLC - Registration No. 123456 - VAT ID: EU0987654321", "lines": [ { "position": 1, "description": "Budget Ticket", "item": 1234, "variation": 245, "subevent": null, "fee_type": null, "fee_internal_type": null, "event_date_from": "2017-12-27T10:00:00Z", "event_date_to": null, "event_location": "Heidelberg", "attendee_name": null, "gross_value": "23.00", "tax_value": "0.00", "tax_name": "VAT", "tax_rate": "0.00" } ], "foreign_currency_display": "PLN", "foreign_currency_rate": "4.2408", "foreign_currency_rate_date": "2017-07-24" } ] }
- Query Parameters:
page (integer) – The page number in case of a multi-page result set, default is 1
is_cancellation (boolean) – If set to
true
orfalse
, only invoices with this value for the fieldis_cancellation
will be returned.order (string) – If set, only invoices belonging to the order with the given order code will be returned. This parameter may be given multiple times. In this case, all invoices matching one of the inputs will be returned.
number (string) – If set, only invoices with the given invoice number will be returned. This parameter may be given multiple times. In this case, all invoices matching one of the inputs will be returned.
refers (string) – If set, only invoices referring to the given invoice will be returned.
locale (string) – If set, only invoices with the given locale will be returned.
ordering (string) – Manually set the ordering of results. Valid fields to be used are
date
andnr
(equals tonumber
). Default:nr
- Parameters:
organizer – The
slug
field of the organizer to fetchevent – The
slug
field of the event to fetch
- Status Codes:
200 OK – no error
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event does not exist or you have no permission to view this resource.
- GET /api/v1/organizers/(organizer)/invoices/¶
Returns a list of all invoices within all events of a given organizer (with sufficient access permissions).
Supported query parameters and output format of this endpoint are identical to the list endpoint within an event.
Example request:
GET /api/v1/organizers/bigevents/events/sampleconf/invoices/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "count": 1, "next": null, "previous": null, "results": [ { "number": "SAMPLECONF-00001", "event": "sampleconf", "order": "ABC12", ... ] }
- Parameters:
organizer – The
slug
field of the organizer to fetch
- Status Codes:
200 OK – no error
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event does not exist or you have no permission to view this resource.
Fetching individual invoices¶
- GET /api/v1/organizers/(organizer)/events/(event)/invoices/(number)/¶
Returns information on one invoice, identified by its invoice number.
Example request:
GET /api/v1/organizers/bigevents/events/sampleconf/invoices/SAMPLECONF-00001/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "number": "SAMPLECONF-00001", "event": "sampleconf", "order": "ABC12", "is_cancellation": false, "invoice_from_name": "Big Events LLC", "invoice_from": "Demo street 12", "invoice_from_zipcode":"", "invoice_from_city":"Demo town", "invoice_from_country":"US", "invoice_from_tax_id":"", "invoice_from_vat_id":"", "invoice_to": "Sample company\nJohn Doe\nTest street 12\n12345 Testington\nTestikistan\nVAT-ID: EU123456789", "invoice_to_company": "Sample company", "invoice_to_name": "John Doe", "invoice_to_street": "Test street 12", "invoice_to_zipcode": "12345", "invoice_to_city": "Testington", "invoice_to_state": null, "invoice_to_country": "TE", "invoice_to_vat_id": "EU123456789", "invoice_to_beneficiary": "", "custom_field": null, "date": "2017-12-01", "refers": null, "locale": "en", "introductory_text": "thank you for your purchase of the following items:", "internal_reference": "", "additional_text": "We are looking forward to see you on our conference!", "payment_provider_text": "Please transfer the money to our account ABC…", "payment_provider_stamp": null, "footer_text": "Big Events LLC - Registration No. 123456 - VAT ID: EU0987654321", "lines": [ { "position": 1, "description": "Budget Ticket", "item": 1234, "variation": 245, "subevent": null, "fee_type": null, "fee_internal_type": null, "event_date_from": "2017-12-27T10:00:00Z", "event_date_to": null, "event_location": "Heidelberg", "attendee_name": null, "gross_value": "23.00", "tax_value": "0.00", "tax_name": "VAT", "tax_rate": "0.00" } ], "foreign_currency_display": "PLN", "foreign_currency_rate": "4.2408", "foreign_currency_rate_date": "2017-07-24" }
- Parameters:
organizer – The
slug
field of the organizer to fetchevent – The
slug
field of the event to fetchinvoice_no – The
invoice_no
field of the invoice to fetch
- Status Codes:
200 OK – no error
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event does not exist or you have no permission to view this resource.
- GET /api/v1/organizers/(organizer)/events/(event)/invoices/(invoice_no)/download/¶
Download an invoice in PDF format.
Note that in some cases the PDF file might not yet have been created. In that case, you will receive a status code 409 Conflict and you are expected to retry the request after a short period of waiting.
Example request:
GET /api/v1/organizers/bigevents/events/sampleconf/invoices/00001/download/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/pdf ...
- Parameters:
organizer – The
slug
field of the organizer to fetchevent – The
slug
field of the event to fetchinvoice_no – The
invoice_no
field of the invoice to fetch
- Status Codes:
200 OK – no error
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event does not exist or you have no permission to view this resource.
409 Conflict – The file is not yet ready and will now be prepared. Retry the request after waiting for a few seconds.
Modifying invoices¶
Invoices cannot be edited directly, but the following actions can be triggered:
- POST /api/v1/organizers/(organizer)/events/(event)/invoices/(invoice_no)/reissue/¶
Cancels the invoice and creates a new one.
Example request:
GET /api/v1/organizers/bigevents/events/sampleconf/invoices/00001/reissue/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript
Example response:
HTTP/1.1 204 No Content Vary: Accept Content-Type: application/pdf
- Parameters:
organizer – The
slug
field of the organizer to fetchevent – The
slug
field of the event to fetchinvoice_no – The
invoice_no
field of the invoice to reissue
- Status Codes:
200 OK – no error
400 Bad Request – The invoice has already been canceled
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event does not exist or you have no permission to change this resource.
- POST /api/v1/organizers/(organizer)/events/(event)/invoices/(invoice_no)/regenerate/¶
Re-generates the invoice from order data.
Example request:
GET /api/v1/organizers/bigevents/events/sampleconf/invoices/00001/regenerate/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript
Example response:
HTTP/1.1 204 No Content Vary: Accept Content-Type: application/pdf
- Parameters:
organizer – The
slug
field of the organizer to fetchevent – The
slug
field of the event to fetchinvoice_no – The
invoice_no
field of the invoice to regenerate
- Status Codes:
200 OK – no error
400 Bad Request – The invoice has already been canceled
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event does not exist or you have no permission to change this resource.