Invoice

Added in version 2.4.0.

Requires Pro Edition and Invoices plugin >= 4.1.3.

Manager

All operations on the Invoice resource are provided by its manager. To get access to it you have to call redmine.invoice where redmine is a configured redmine object. See the Configuration about how to configure redmine object.

Create methods

create

redminelib.managers.ResourceManager.create(**fields)

Creates new Invoice resource with given fields and saves it to the Invoices plugin.

Parameters:

  • number (string) – (required). Invoice number.

  • project_id (int or string) – (required). Id or identifier of invoice’s project.

  • status_id (int) – (required). Invoice status id:

    • 0 - estimate

    • 1 - draft

    • 2 - sent

    • 3 - paid

    • 4 - cancelled

  • invoice_date (string or date object) – (required). Date when invoice is issued.

  • subject (string) – (optional). Invoice subject.

  • contact_id (int) – (optional). Invoice contact id.

  • assigned_to_id (int) – (optional). Invoice will be assigned to this user id.

  • order_number (string) – (optional). Invoice order number.

  • is_recurring (bool) – (optional). Whether invoice is recurring.

  • recurring_period (string) – (optional). Invoice recurring period:

    • 1week - weekly

    • 2week - every 2 weeks

    • 1month - monthly

    • 2month - every 2 months

    • 3month - every 3 months

    • 6month - every 6 months

    • 1year - yearly

  • recurring_action (int) – (optional). Invoice recurring action:

    • 0 - create draft

    • 1 - send to client

  • recurring_occurrences (int) – (optional). Invoice recurring occurrences.

  • due_date (string or date object) – (optional). Invoice should be payed by this date.

  • discount (int) – (optional). Invoice percentage discount.

  • currency (string) – (optional). Invoice currency.

  • template_id (int) – (optional). Invoice template id.

  • language (string) – (optional). Invoice language.

  • description (string) – (optional). Invoice description.

  • custom_fields (list) – (optional). Custom fields as [{‘id’: 1, ‘value’: ‘foo’}].

  • lines_attributes (list) – (optional). Invoice lines as [{'': ''}, ...], accepted keys are:

    • description (required). Product description.

    • position (optional). Position of the line among other invoice lines.

    • quantity (optional). Product quantity.

    • product_id (optional). ID of the product.

    • tax (optional). Tax in percentage.

    • price (optional). Price of the product.

    • units (optional). Unit type, i.e. hours, days, products etc.

  • uploads (list) – (optional). Uploads as [{'': ''}, ...], accepted keys are:

    • path (required). Absolute file path or file-like object that should be uploaded.

    • filename (optional). Name of the file after upload.

    • description (optional). Description of the file.

    • content_type (optional). Content type of the file.

Returns:

Resource object

>>> invoice = redmine.invoice.create(
...     number='INV-001',
...     project_id='invoices',
...     status_id=1,
...     invoice_date='2023-01-11',
...     subject='invoice subject',
...     contact_id=3,
...     assigned_to_id=12,
...     due_date='2023-01-13',
...     discount=20,
...     currency='USD',
...     template_id=7,
...     language='en',
...     description='invoice description',
...     order_number='ON-0001',
...     is_recurring=True,
...     recurring_period='6month',
...     recurring_action=1,
...     recurring_occurrences=3,
...     lines_attributes=[{'position': 1, 'quantity': '3', 'description': 'product description', 'product_id': 1, 'tax': '10', 'price': '5', 'units': 'hours'}],
...     custom_fields=[{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}],
...     uploads=[{'path': '/absolute/path/to/file'}, {'path': BytesIO(b'I am content of file 2')}]
... )
>>> invoice
<redminelib.resources.Invoice #123>

new

redminelib.managers.ResourceManager.new()

Creates new empty Invoice resource, but saves it to the Invoices plugin only when save() is called, also calls pre_create() and post_create() methods of the Resource object. Valid attributes are the same as for create() method above.

Returns:

Resource object

>>> invoice = redmine.invoice.new()
>>> invoice.number = 'INV-001'
>>> invoice.project_id = 'invoices'
>>> invoice.status_id = 1
>>> invoice.invoice_date = '2023-01-11'
>>> invoice.subject = 'invoice subject'
>>> invoice.contact_id = 3
>>> invoice.assigned_to_id = 12
>>> invoice.due_date = '2023-01-13'
>>> invoice.discount = 20
>>> invoice.currency = 'USD'
>>> invoice.template_id = 7
>>> invoice.language = 'en'
>>> invoice.description = 'invoice description'
>>> invoice.order_number = 'ON-0001'
>>> invoice.is_recurring = True
>>> invoice.recurring_period = '6month'
>>> invoice.recurring_action = 1
>>> invoice.recurring_occurrences = 3
>>> invoice.lines_attributes = [{'position': 1, 'quantity': '3', 'description': 'product description', 'product_id': 1, 'tax': '10', 'price': '5', 'units': 'hours'}]
>>> invoice.custom_fields = [{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}]
>>> invoice.uploads = [{'path': '/absolute/path/to/file'}, {'path': BytesIO(b'I am content of file 2')}]
>>> invoice.save()
<redminelib.resources.Invoice #123>

Read methods

get

redminelib.managers.ResourceManager.get(resource_id, **params)

Returns single Invoice resource from the Invoices plugin by its id.

Parameters:

resource_id (int) – (required). Id of the invoice.

Returns:

Resource object

>>> invoice = redmine.invoice.get(123)
>>> invoice
<redminelib.resources.Invoice #123>

all

redminelib.managers.ResourceManager.all(**params)

Returns all Invoice resources from the Invoices plugin.

Parameters:

  • limit (int) – (optional). How much resources to return.

  • offset (int) – (optional). Starting from what resource to return the other resources.

Returns:

ResourceSet object

>>> invoices = redmine.invoice.all(limit=50)
>>> invoices
<redminelib.resultsets.ResourceSet object with Invoice resources>

filter

redminelib.managers.ResourceManager.filter(**filters)

Returns Invoice resources that match the given lookup parameters.

Parameters:

  • project_id (int or string) – (optional). Id or identifier of invoice’s project.

  • assigned_to_id (int) – (optional). Get invoices which are assigned to this user id.

  • query_id (int) – (optional). Get invoices for the given query id.

  • status_id (int) – (optional). Get invoices which have this status id.

  • contact_id (int) – (optional). Get invoices for the given contact id.

  • author_id (int) – (optional). Get invoices created by given author id.

  • recurring (bool) – (optional). Whether invoice is recurring.

  • due_date (string or date object) – (optional). Get invoices that should be payed by this date.

  • invoice_date (string or date object) – (optional). Get invoices issued on the given date.

  • currency (string) – (optional). Get invoices which have the given currency.

  • search (string) – (optional). Get invoices with given search string.

  • limit (int) – (optional). How much resources to return.

  • offset (int) – (optional). Starting from what resource to return the other resources.

Returns:

ResourceSet object

>>> invoices = redmine.invoice.filter(project_id='invoices', assigned_to_id=123, status_id=1, search='INV', recurring=True)
>>> invoices
<redminelib.resultsets.ResourceSet object with Invoice resources>

Hint

You can also get invoices from a Project, User, Contact and CrmQuery resource objects directly using invoices relation:

>>> project = redmine.project.get('invoices')
>>> project.invoices
<redminelib.resultsets.ResourceSet object with Invoice resources>

Update methods

update

redminelib.managers.ResourceManager.update(resource_id, **fields)

Updates values of given fields of an Invoice resource and saves them to the Invoices plugin.

Parameters:

  • resource_id (int) – (required). Invoice id.

  • number (string) – (optional). Invoice number.

  • project_id (int or string) – (optional). Id or identifier of invoice’s project.

  • status_id (int) – (optional). Invoice status id:

    • 0 - estimate

    • 1 - draft

    • 2 - sent

    • 3 - paid

    • 4 - cancelled

  • invoice_date (string or date object) – (optional). Date when invoice is issued.

  • subject (string) – (optional). Invoice subject.

  • contact_id (int) – (optional). Invoice contact id.

  • assigned_to_id (int) – (optional). Invoice will be assigned to this user id.

  • order_number (string) – (optional). Invoice order number.

  • is_recurring (bool) – (optional). Whether invoice is recurring.

  • recurring_period (string) – (optional). Invoice recurring period:

    • 1week - weekly

    • 2week - every 2 weeks

    • 1month - monthly

    • 2month - every 2 months

    • 3month - every 3 months

    • 6month - every 6 months

    • 1year - yearly

  • recurring_action (int) – (optional). Invoice recurring action:

    • 0 - create draft

    • 1 - send to client

  • recurring_occurrences (int) – (optional). Invoice recurring occurrences.

  • due_date (string or date object) – (optional). Invoice should be payed by this date.

  • discount (int) – (optional). Invoice percentage discount.

  • currency (string) – (optional). Invoice currency.

  • template_id (int) – (optional). Invoice template id.

  • language (string) – (optional). Invoice language.

  • description (string) – (optional). Invoice description.

  • custom_fields (list) – (optional). Custom fields as [{‘id’: 1, ‘value’: ‘foo’}].

  • lines_attributes (list) – (optional). Invoice lines as [{'': ''}, ...], accepted keys are:

    • id (optional). If not set, a new line will be created.

    • description (optional). Product description.

    • position (optional). Position of the line among other invoice lines.

    • quantity (optional). Product quantity.

    • product_id (optional). ID of the product.

    • tax (optional). Tax in percentage.

    • price (optional). Price of the product.

    • units (optional). Unit type, i.e. hours, days, products etc.

    • _destroy (optional). Whether to delete line with a specified id.

  • uploads (list) – (optional). Uploads as [{'': ''}, ...], accepted keys are:

    • path (required). Absolute file path or file-like object that should be uploaded.

    • filename (optional). Name of the file after upload.

    • description (optional). Description of the file.

    • content_type (optional). Content type of the file.

Returns:

True

>>> redmine.invoice.update(
...     123,
...     number='INV-001',
...     project_id='invoices',
...     status_id=1,
...     invoice_date='2023-01-11',
...     subject='invoice subject',
...     contact_id=3,
...     assigned_to_id=12,
...     due_date='2023-01-13',
...     discount=20,
...     currency='USD',
...     template_id=7,
...     language='en',
...     description='invoice description',
...     order_number='ON-0001',
...     is_recurring=True,
...     recurring_period='6month',
...     recurring_action=1,
...     recurring_occurrences=3,
...     lines_attributes=[{'id': 1, '_destroy': True}, {'position': 1, 'quantity': '3', 'description': 'product description', 'product_id': 1, 'tax': '10', 'price': '5', 'units': 'hours'}],
...     custom_fields=[{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}],
...     uploads=[{'path': '/absolute/path/to/file'}, {'path': BytesIO(b'I am content of file 2')}]
... )
True

save

redminelib.resources.Invoice.save(**attrs)

Saves the current state of an Invoice resource to the Invoices plugin. Attrs that can be changed are the same as for update() method above.

Returns:

Resource object

>>> invoice = redmine.invoice.get(123)
>>> invoice.number = 'INV-001'
>>> invoice.project_id = 'invoices'
>>> invoice.status_id = 1
>>> invoice.invoice_date = '2023-01-11'
>>> invoice.subject = 'invoice subject'
>>> invoice.contact_id = 3
>>> invoice.assigned_to_id = 12
>>> invoice.due_date = '2023-01-13'
>>> invoice.discount = 20
>>> invoice.currency = 'USD'
>>> invoice.template_id = 7
>>> invoice.language = 'en'
>>> invoice.description = 'invoice description'
>>> invoice.order_number = 'ON-0001'
>>> invoice.is_recurring = True
>>> invoice.recurring_period = '6month'
>>> invoice.recurring_action = 1
>>> invoice.recurring_occurrences = 3
>>> invoice.lines_attributes = [{'id': 1, '_destroy': True}, {'position': 1, 'quantity': '3', 'description': 'product description', 'product_id': 1, 'tax': '10', 'price': '5', 'units': 'hours'}]
>>> invoice.custom_fields = [{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}]
>>> invoice.uploads = [{'path': '/absolute/path/to/file'}, {'path': BytesIO(b'I am content of file 2')}]
>>> invoice.save()
<redminelib.resources.Invoice #123>

Added in version 2.1.0: Alternative syntax was introduced.

>>> invoice = redmine.invoice.get(123).save(
...     number='INV-001',
...     project_id='invoices',
...     status_id=1,
...     invoice_date='2023-01-11',
...     subject='invoice subject',
...     contact_id=3,
...     assigned_to_id=12,
...     due_date='2023-01-13',
...     discount=20,
...     currency='USD',
...     template_id=7,
...     language='en',
...     description='invoice description',
...     order_number='ON-0001',
...     is_recurring=True,
...     recurring_period='6month',
...     recurring_action=1,
...     recurring_occurrences=3,
...     lines_attributes=[{'id': 1, '_destroy': True}, {'position': 1, 'quantity': '3', 'description': 'product description', 'product_id': 1, 'tax': '10', 'price': '5', 'units': 'hours'}],
...     custom_fields=[{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}],
...     uploads=[{'path': '/absolute/path/to/file'}, {'path': BytesIO(b'I am content of file 2')}]
... )
>>> invoice
<redminelib.resources.Invoice #123>

Delete methods

delete

redminelib.managers.ResourceManager.delete(resource_id)

Deletes single Invoice resource from the Invoices plugin by its id.

Parameters:

resource_id (int) – (required). Invoice id.

Returns:

True

>>> redmine.invoice.delete(123)
True
redminelib.resources.Invoice.delete()

Deletes current Invoice resource object from the Invoices plugin.

Returns:

True

>>> invoice = redmine.invoice.get(1)
>>> invoice.delete()
True

Export

Added in version 2.0.0.

redminelib.resources.Invoice.export(fmt, savepath=None, filename=None)

Exports Invoice resource in one of the following formats: pdf

Parameters:

  • fmt (string) – (required). Format to use for export.

  • savepath (string) – (optional). Path where to save the file.

  • filename (string) – (optional). Name that will be used for the file.

Returns:

String or Object

>>> invoice = redmine.invoice.get(123)
>>> invoice.export('pdf', savepath='/home/jsmith')
'/home/jsmith/123.pdf'
redminelib.resultsets.ResourceSet.export(fmt, savepath=None, filename=None)

Exports a resource set of Invoice resources in one of the following formats: csv

Parameters:

  • fmt (string) – (required). Format to use for export.

  • savepath (string) – (optional). Path where to save the file.

  • filename (string) – (optional). Name that will be used for the file.

Returns:

String or Object

>>> invoices = redmine.invoice.all()
>>> invoices.export('csv', savepath='/home/jsmith', filename='invoices.csv')
'/home/jsmith/invoices.csv'