Invoices ======== Resource description -------------------- The invoice resource contains the following public fields: .. rst-class:: rest-resource-table ===================================== ========================== ======================================================= 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 ``true``, if this invoice is the cancellation of a different invoice. 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 ``null``. 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 ``null`` for all invoice lines created before this field was introduced as well as for all lines not created by a product (e.g. a shipping or cancellation fee). ├ 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 ``null`` for all invoice lines created before this field was introduced as well as for all lines not created by a product (e.g. a shipping or cancellation fee). ├ 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 ``null`` for all invoice lines created before this field was introduced as well as for all lines not created by a product (e.g. a shipping or cancellation fee) as well as for all events that are not a series. ├ fee_type string Fee type, e.g. ``shipping``, ``service``, ``payment``, ``cancellation``, ``giftcard``, or ``other. Can be ``null`` for all invoice lines created before this field was introduced as well as for all lines not created by a fee (e.g. a product). ├ fee_internal_type string Additional fee type, e.g. type of payment provider. Can be ``null`` for all invoice lines created before this field was introduced as well as for all lines not created by a fee (e.g. a product). ├ event_date_from datetime Start date of the (sub)event this line was created for as it was set during invoice creation. Can be ``null`` for all invoice lines created before this was introduced as well as for lines in an event series not created by a product (e.g. shipping or cancellation fees). ├ event_date_to datetime End date of the (sub)event this line was created for as it was set during invoice creation. Can be ``null`` for all invoice lines created before this was introduced as well as for lines in an event series not created by a product (e.g. shipping or cancellation fees) as well as whenever the respective (sub)event has no end date set. ├ event_location string Location of the (sub)event this line was created for as it was set during invoice creation. Can be ``null`` for all invoice lines created before this was introduced as well as for lines in an event series not created by a product (e.g. shipping or cancellation fees) as well as whenever the respective (sub)event has no location set. ├ attendee_name string Attendee name at time of invoice creation. Can be ``null`` if no name was set or if names are configured to not be added to invoices. ├ 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 (``null`` otherwise). foreign_currency_rate decimal (string) If ``foreign_currency_rate`` is set and the system knows the exchange rate to the event currency at invoicing time, it is stored here. foreign_currency_rate_date date If ``foreign_currency_rate`` is set, this signifies the date at which the currency rate was obtained. internal_reference string Customer's reference to be printed on the invoice. ===================================== ========================== ======================================================= .. versionchanged:: 4.1 The attributes ``fee_type`` and ``fee_internal_type`` have been added. .. versionchanged:: 4.1 The attribute ``lines.event_location`` has been added. .. versionchanged:: 4.6 The attribute ``lines.subevent`` has been added. .. versionchanged:: 2023.8 The ``event`` attribute has been added. The organizer-level endpoint has been added. List of all invoices -------------------- .. http:get:: /api/v1/organizers/(organizer)/events/(event)/invoices/ Returns a list of all invoices within a given event. **Example request**: .. sourcecode:: http GET /api/v1/organizers/bigevents/events/sampleconf/invoices/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript **Example response**: .. sourcecode:: http 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 integer page: The page number in case of a multi-page result set, default is 1 :query boolean is_cancellation: If set to ``true`` or ``false``, only invoices with this value for the field ``is_cancellation`` will be returned. :query string order: If set, only invoices belonging to the order with the given order code will be returned. :query string refers: If set, only invoices referring to the given invoice will be returned. :query string locale: If set, only invoices with the given locale will be returned. :query string ordering: Manually set the ordering of results. Valid fields to be used are ``date`` and ``nr`` (equals to ``number``). Default: ``nr`` :param organizer: The ``slug`` field of the organizer to fetch :param event: The ``slug`` field of the event to fetch :statuscode 200: no error :statuscode 401: Authentication failure :statuscode 403: The requested organizer/event does not exist **or** you have no permission to view this resource. .. http: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**: .. sourcecode:: http GET /api/v1/organizers/bigevents/events/sampleconf/invoices/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript **Example response**: .. sourcecode:: http 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", ... ] } :param organizer: The ``slug`` field of the organizer to fetch :statuscode 200: no error :statuscode 401: Authentication failure :statuscode 403: The requested organizer/event does not exist **or** you have no permission to view this resource. Fetching individual invoices ---------------------------- .. http:get:: /api/v1/organizers/(organizer)/events/(event)/invoices/(number)/ Returns information on one invoice, identified by its invoice number. **Example request**: .. sourcecode:: http GET /api/v1/organizers/bigevents/events/sampleconf/invoices/SAMPLECONF-00001/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript **Example response**: .. sourcecode:: http 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" } :param organizer: The ``slug`` field of the organizer to fetch :param event: The ``slug`` field of the event to fetch :param invoice_no: The ``invoice_no`` field of the invoice to fetch :statuscode 200: no error :statuscode 401: Authentication failure :statuscode 403: The requested organizer/event does not exist **or** you have no permission to view this resource. .. http: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 :http:statuscode:`409` and you are expected to retry the request after a short period of waiting. **Example request**: .. sourcecode:: http GET /api/v1/organizers/bigevents/events/sampleconf/invoices/00001/download/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Vary: Accept Content-Type: application/pdf ... :param organizer: The ``slug`` field of the organizer to fetch :param event: The ``slug`` field of the event to fetch :param invoice_no: The ``invoice_no`` field of the invoice to fetch :statuscode 200: no error :statuscode 401: Authentication failure :statuscode 403: The requested organizer/event does not exist **or** you have no permission to view this resource. :statuscode 409: 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: .. http:post:: /api/v1/organizers/(organizer)/events/(event)/invoices/(invoice_no)/reissue/ Cancels the invoice and creates a new one. **Example request**: .. sourcecode:: http GET /api/v1/organizers/bigevents/events/sampleconf/invoices/00001/reissue/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript **Example response**: .. sourcecode:: http HTTP/1.1 204 No Content Vary: Accept Content-Type: application/pdf :param organizer: The ``slug`` field of the organizer to fetch :param event: The ``slug`` field of the event to fetch :param invoice_no: The ``invoice_no`` field of the invoice to reissue :statuscode 200: no error :statuscode 400: The invoice has already been canceled :statuscode 401: Authentication failure :statuscode 403: The requested organizer/event does not exist **or** you have no permission to change this resource. .. http:post:: /api/v1/organizers/(organizer)/events/(event)/invoices/(invoice_no)/regenerate/ Re-generates the invoice from order data. **Example request**: .. sourcecode:: http GET /api/v1/organizers/bigevents/events/sampleconf/invoices/00001/regenerate/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript **Example response**: .. sourcecode:: http HTTP/1.1 204 No Content Vary: Accept Content-Type: application/pdf :param organizer: The ``slug`` field of the organizer to fetch :param event: The ``slug`` field of the event to fetch :param invoice_no: The ``invoice_no`` field of the invoice to regenerate :statuscode 200: no error :statuscode 400: The invoice has already been canceled :statuscode 401: Authentication failure :statuscode 403: The requested organizer/event does not exist **or** you have no permission to change this resource.