Recurring Generators

Attributes

Attribute	Type	Description
`id`	`Integer`	Unique identifier in Fakturoid
`custom_id`	`String`	Identifier in your application
`name`	`String`	Generator name
`active`	`Boolean`	Generator is active or paused Values: `true` (active), `false` (paused) Default: `true`
`proforma`	`Boolean`	Issue invoice as a proforma Default: `false`
`paypal`	`Boolean`	Show PayPal pay button on invoice Default: `false`
`gopay`	`Boolean`	Show GoPay pay button on invoice Default: `false`
`start_date`	`Date`	Start date
`end_date`	`Date`	End date
`months_period`	`Integer`	Number of months until the next invoice
`next_occurrence_on`	`Date`	Next invoice date
`last_day_in_month`	`Boolean`	Issue an invoice on the last day of the month Default: `false`
`tax_date_at_end_of_last_month`	`Boolean`	Set CED at the end of last month Default: `false`
`due`	`Integer`	Number of days until the invoice is overdue Default: Inherit from account settings
`send_email`	`Boolean`	Send invoice by email Default: `false`
`subject_id`	`Integer`	Subject ID
`number_format_id`	`Integer`	Number format ID Default: Inherit from default account settings
`note`	`String`	Text before invoice lines
`footer_note`	`String`	Text in invoice footer
`legacy_bank_details`	`Object`	Display IBAN, BIC (SWIFT) and bank account number for legacy generators set without bank account ID Default: `null`
`bank_account_id`	`Integer`	Bank account ID Default: Inherit from account settings
`iban_visibility`	`String`	Controls IBAN visibility on the document webinvoice and PDF. IBAN must be valid to show Values: `automatically`, `always` Default: `automatically`
`tags`	`Array[String]`	List of tags
`order_number`	`String`	Order number
`currency`	`String`	Currency ISO code Default: Inherit from account settings
`exchange_rate`	`Decimal`	Exchange rate
`payment_method`	`String`	Payment method Values: `bank`, `cash`, `cod` (cash on delivery), `card`, `paypal`, `custom` Default: Inherit from account settings
`custom_payment_method`	`String`	Custom payment method (`payment_method` attribute must be set to `custom`, otherwise the `custom_payment_method` value is ignored and set to `null`) Value: String up to 20 characters Default: Inherit from account settings if default account payment method is set to `custom`
`language`	`String`	Invoice language Values: `cz`, `sk`, `en`, `de`, `fr`, `it`, `es`, `ru`, `pl`, `hu`, `ro` Default: Inherit from account settings
`vat_price_mode`	`String`	Calculate VAT from base or final amount, more info in a table below Values: `without_vat`, `from_total_with_vat` Default: Inherit from account settings
`transferred_tax_liability`	`Boolean`	Use reverse charge Default: `false`
`supply_code`	`Integer`	Supply code for reverse charge List of codes
`oss`	`String`	Use OSS mode on invoice Values: `disabled`, `service`, `goods` Default: `disabled`
`round_total`	`Boolean`	Round total amount (VAT included) Default: `false`
`subtotal`	`Decimal`	Total amount without VAT
`total`	`Decimal`	Total amount with VAT
`native_subtotal`	`Decimal`	Total amount without VAT in the account currency
`native_total`	`Decimal`	Total amount with VAT in the account currency
`lines`	`Array[Object]`	List of lines to invoice. You can use variables for inserting dates to your text.
`html_url`	`String`	Generator HTML web address
`url`	`String`	Generator API address
`subject_url`	`String`	API address of subject
`created_at`	`DateTime`	Date and time of generator creation
`updated_at`	`DateTime`	Date and time of last generator update

VAT Price Mode

vat_price_mode settings is ignored in following cases:

Account is set as non VAT payer.
Reverse charge (transferred_tax_liability) is used.

Attribute	Description
`null`	Inherited automatically from the account settings
`"without_vat"`	The price in the invoice line is entered without VAT and the VAT is calculated automatically as a percentage from the line
`"from_total_with_vat"`	The price in the invoice line is inclusive of VAT and the VAT is calculated from it

Lines

Attributes

Attribute	Type	Description
`id`	`Integer`	Unique identifier in Fakturoid
`name`	`String`	Line name
`quantity`	`Decimal`	Quantity Default: `1`
`unit_name`	`String`	Unit name
`unit_price`	`Decimal`	Unit price
`vat_rate`	`Integer`	VAT Rate Default: `0` for non-vat payers, otherwise inherited from account settings
`unit_price_without_vat`	`Decimal`	Unit price without VAT
`unit_price_with_vat`	`Decimal`	Unit price including VAT
`total_price_without_vat`	`Decimal`	Total price without VAT
`total_vat`	`Decimal`	Total VAT
`native_total_price_without_vat`	`Decimal`	Total price without VAT in account currency
`native_total_vat`	`Decimal`	Total VAT in account currency
`inventory_item_id`	`Integer`	ID of the related inventory item, use this to set an ID during document creation
`sku`	`String`	Stock Keeping Unit (SKU), use this to load data from an inventory item with matching SKU code. You can specify the other writable attributes as well and they will override the values from the inventory item.
`inventory`	`Object`	Inventory information Default: `null`

Inventory

Attribute	Type	Description
`item_id`	`Integer`	ID of the related inventory item
`sku`	`String`	Stock Keeping Unit (SKU)
`article_number_type`	`String`	Article number type (only if `article_number` is present) Values: `ian`, `ean`, `isbn`
`article_number`	`String`	Article number (if present)
`move_id`	`Integer`	ID of the related inventory move

Line Example

{
  "id": 1304,
  "name": "Disk 2TB",
  "quantity": "2.0",
  "unit_name": "ks",
  "unit_price": "1000.0",
  "vat_rate": 21,
  "unit_price_without_vat": "1000.0",
  "unit_price_with_vat": "1210.0",
  "total_price_without_vat": "2000.0",
  "total_vat": "420.0",
  "native_total_price_without_vat": "2000.0",
  "native_total_vat": "420.0",
  "inventory": {
    "item_id": 28,
    "sku": "KU994RUR8465",
    "article_number_type": "ian",
    "article_number": "32165478",
    "move_id": 52
  }
}

When editing a document, it is important to send the line ID with the lines, without it the line will be added again.

The unit_price_without_vat and unit_price_with_vat attributes are read-only and are set based on the amount entered in unit_price, the vat_rate and the vat_price_mode attribute.

The unit_price_without_vat and unit_price_with_vat attributes have the same value in the following cases:

The VAT rate is set to 0.
Reverse charge is enabled (if reverse charge is enabled on the document, the vat_price_mode setting is ignored).

You can use variables in recurring generators for inserting dates to your text.

More Examples

Unit price without VAT

Request

{
  "vat_price_mode": "without_vat",
  …
  "lines": [
    {
      …
      "unit_price": "1000.0",
      "vat_rate": "21"
    }
  ]
}

Response

{
  …
  "vat_price_mode": "without_vat",
  …
  "lines": [
    {
      …
      "unit_price": "1000.0",
      "vat_rate": "21",
      "unit_price_without_vat": "1000.0",
      "unit_price_with_vat": "1210.0"
    }
  ]
}

Unit price with VAT

Request

{
  …
  "vat_price_mode": "from_total_with_vat",
  …
  "lines": [
    {
      …
      "unit_price": "1210.0",
      "vat_rate": "21"
    }
  ]
}

Response

{
  …
  "vat_price_mode": "from_total_with_vat",
  …
  "lines": [
    {
      …
      "unit_price": "1000.0",
      "vat_rate": "21",
      "unit_price_without_vat": "1000.0",
      "unit_price_with_vat": "1210.0"
    }
  ]
}

Delete Line

For deleting the line the attribute _destroy: true must be included:

{
  "id": 1234,
  "name": "PC",
  "quantity": "1.0",
  "unit_name": "",
  "unit_price": "20000.0",
  "vat_rate": 21,
  "_destroy": true
}

Legacy Bank Details

Attribute	Type	Description
`bank_account`	`String`	Bank account number
`iban`	`String`	IBAN
`swift_bic`	`String`	BIC (for SWIFT payments)

Required attribute (must always be present).
Read-only attribute (cannot be changed).
Write-only attribute (will not be returned).
Unmarked attributes are optional and can be omitted during request.

Recurring Generators Index

If query parameters since and updated_since are not valid date time format (ISO 8601) the server will respond with 400 Bad Request.

Request

GET https://app.fakturoid.cz/api/v3/accounts/{slug}/recurring_generators.json

Headers

Name	Value
`User-Agent`	`YourApp (yourname@example.com)`

URL Parameters

Name	Description	Type	Example
`slug`	Account name	`String`	`applecorp`

Query Parameters

Name	Description	Type	Example
`since`	Recurring generators created after this date	`DateTime`	`2023-08-25T10:55:14+02:00`
`updated_since`	Recurring generators created or updated after this date	`DateTime`	`2023-08-25T10:55:14+02:00`
`page`	Page number (40 records per page)	`Integer`	`2`
`subject_id`	Recurring generators for subject	`Integer`	`24`

Response

Status 200 OK

Body

[
  {
    "id": 24,
    "custom_id": null,
    "name": "Vývoj",
    "active": true,
    "proforma": false,
    "paypal": false,
    "gopay": false,
    "start_date": "2023-10-11",
    "end_date": null,
    "months_period": 12,
    "next_occurrence_on": "2024-10-11",
    "last_day_in_month": false,
    "tax_date_at_end_of_last_month": false,
    "due": 14,
    "send_email": false,
    "subject_id": 37,
    "number_format_id": null,
    "note": null,
    "footer_note": null,
    "legacy_bank_details": null,
    "bank_account_id": null,
    "iban_visibility": "always",
    "tags": [
      "štítek"
    ],
    "order_number": null,
    "currency": "CZK",
    "payment_method": "bank",
    "custom_payment_method": null,
    "exchange_rate": "1.0",
    "language": "cz",
    "vat_price_mode": "without_vat",
    "transferred_tax_liability": false,
    "oss": "disabled",
    "supply_code": null,
    "subtotal": "50550.0",
    "total": "61165.5",
    "native_subtotal": "50550.0",
    "native_total": "61165.5",
    "lines": [
      {
        "id": 1292,
        "name": "One plan",
        "quantity": "1.0",
        "unit_name": "",
        "unit_price": "550.0",
        "vat_rate": 21,
        "unit_price_without_vat": "550.0",
        "unit_price_with_vat": "665.5",
        "inventory_item_id": null
      },
      {
        "id": 1294,
        "name": "Napojení na Fakturoid",
        "quantity": "1.0",
        "unit_name": "",
        "unit_price": "50000.0",
        "vat_rate": 21,
        "unit_price_without_vat": "50000.0",
        "unit_price_with_vat": "60500.0",
        "inventory_item_id": null
      }
    ],
    "html_url": "https://app.fakturoid.cz/applecorp/recurring_generators/24",
    "url": "https://app.fakturoid.cz/api/v3/accounts/applecorp/generators/24.json",
    "subject_url": "https://app.fakturoid.cz/api/v3/accounts/applecorp/subjects/37.json",
    "created_at": "2023-10-11T13:38:21.603+02:00",
    "updated_at": "2023-10-11T19:59:20.290+02:00"
  },
  …
]

Recurring Generator Detail

Request

GET https://app.fakturoid.cz/api/v3/accounts/{slug}/recurring_generators/{id}.json

Headers

Name	Value
`User-Agent`	`YourApp (yourname@example.com)`

URL Parameters

Name	Description	Type	Example
`slug`	Account name	`String`	`applecorp`
`id`	Recurring generator ID	`Integer`	`24`

Response

Status 200 OK

Body

{
  "id": 24,
  "custom_id": null,
  "name": "Vývoj",
  "active": true,
  "proforma": false,
  "paypal": false,
  "gopay": false,
  "start_date": "2023-10-11",
  "end_date": null,
  "months_period": 12,
  "next_occurrence_on": "2024-10-11",
  "last_day_in_month": false,
  "tax_date_at_end_of_last_month": false,
  "due": 14,
  "send_email": false,
  "subject_id": 37,
  "number_format_id": null,
  "note": null,
  "footer_note": null,
  "legacy_bank_details": null,
  "bank_account_id": null,
  "iban_visibility": "always",
  "tags": [
    "štítek"
  ],
  "order_number": null,
  "currency": "CZK",
  "payment_method": "bank",
  "custom_payment_method": null,
  "exchange_rate": "1.0",
  "language": "cz",
  "vat_price_mode": "without_vat",
  "transferred_tax_liability": false,
  "oss": "disabled",
  "supply_code": null,
  "subtotal": "50550.0",
  "total": "61165.5",
  "native_subtotal": "50550.0",
  "native_total": "61165.5",
  "lines": [
    {
      "id": 1292,
      "name": "One plan",
      "quantity": "1.0",
      "unit_name": "",
      "unit_price": "550.0",
      "vat_rate": 21,
      "unit_price_without_vat": "550.0",
      "unit_price_with_vat": "665.5",
      "inventory_item_id": null
    },
    {
      "id": 1294,
      "name": "Napojení na Fakturoid",
      "quantity": "1.0",
      "unit_name": "",
      "unit_price": "50000.0",
      "vat_rate": 21,
      "unit_price_without_vat": "50000.0",
      "unit_price_with_vat": "60500.0",
      "inventory_item_id": null
    }
  ],
  "html_url": "https://app.fakturoid.cz/applecorp/recurring_generators/24",
  "url": "https://app.fakturoid.cz/api/v3/accounts/applecorp/generators/24.json",
  "subject_url": "https://app.fakturoid.cz/api/v3/accounts/applecorp/subjects/37.json",
  "created_at": "2023-10-11T13:38:21.603+02:00",
  "updated_at": "2023-10-12T20:56:18.345+02:00"
}

Create Recurring Generator

After successful generator creation, you will receive a 201 Created response from the server, the location header will be set to the address of the newly created generator.
If non-valid data is sent, you will receive a 422 Unprocessable Entity response from the server and a JSON with a list of errors in the sent data.
In the case where no bank account is specified in Fakturoid account, the API returns a 403 Forbidden. The body of the response will contain a description of the error with a link to the bank account settings (bank account cannot be entered via the API).
Only one recurring generator is allowed on the Zdarma, Základ and Sólo plans, if you try to add another, the server will return 403 Forbidden.

Request

POST https://app.fakturoid.cz/api/v3/accounts/{slug}/recurring_generators.json

Headers

Name	Value
`User-Agent`	`YourApp (yourname@example.com)`
`Content-Type`	`application/json`

URL Parameters

Name	Description	Type	Example
`slug`	Account name	`String`	`applecorp`

Body

{
  "name": "Web service",
  "start_date": "2023-10-13",
  "months_period": "12",
  "subject_id": "37",
  "lines": [
    {
      "name": "One plan",
      "quantity": "1",
      "unit_price": "550",
      "vat_rate": "21"
    }
  ]
}

Response

Status 201 Created

Headers

Name	Value
`Location`	`https://app.fakturoid.cz/api/v3/accounts/applecorp/generators/28.json`

Body

{
  "id": 28,
  "custom_id": null,
  "name": "Web service",
  "active": true,
  "proforma": false,
  "paypal": false,
  "gopay": false,
  "start_date": "2023-10-13",
  "end_date": null,
  "months_period": 12,
  "next_occurrence_on": "2023-10-13",
  "last_day_in_month": false,
  "tax_date_at_end_of_last_month": false,
  "due": 14,
  "send_email": false,
  "subject_id": 37,
  "number_format_id": null,
  "note": null,
  "footer_note": null,
  "legacy_bank_details": null,
  "bank_account_id": null,
  "iban_visibility": "automatically",
  "tags": [],
  "order_number": null,
  "currency": "CZK",
  "payment_method": "bank",
  "custom_payment_method": null,
  "exchange_rate": "1.0",
  "language": "cz",
  "vat_price_mode": "without_vat",
  "transferred_tax_liability": false,
  "oss": "disabled",
  "supply_code": null,
  "subtotal": "550.0",
  "total": "665.5",
  "native_subtotal": "550.0",
  "native_total": "665.5",
  "lines": [
    {
      "id": 1299,
      "name": "One plan",
      "quantity": "1.0",
      "unit_name": "",
      "unit_price": "550.0",
      "vat_rate": 21,
      "unit_price_without_vat": "550.0",
      "unit_price_with_vat": "665.5",
      "inventory_item_id": null
    }
  ],
  "html_url": "https://app.fakturoid.cz/applecorp/recurring_generators/28",
  "url": "https://app.fakturoid.cz/api/v3/accounts/applecorp/generators/28.json",
  "subject_url": "https://app.fakturoid.cz/api/v3/accounts/applecorp/subjects/37.json",
  "created_at": "2023-10-12T21:16:35.730+02:00",
  "updated_at": "2023-10-12T21:16:35.730+02:00"
  }

Request with invalid data

Body

{
  "name": ""
}

Response

Status 422 Unprocessable Entity

Body

{
  "errors": {
    "name": [
      "je povinná položka",
    ]
  }
}

Response if missing bank account

Status 403 Forbidden

Body

{
  "errors": {
    "bank_account": [
      "You have to setup bank account in your Fakturoid account https://app.fakturoid.cz/applecorp/settings/bank_accounts to create a generator.",
    ]
  }
}

Response if cannot add more generators (limit would be exceeded)

Status 403 Forbidden

Update Recurring Generator

If generator is successfuly updated the server will respond with 200 OK and a JSON body with its data.
Request with invalid data will result in response 422 Unprocessable Entity with a JSON body describing errors found in the request.

Request

PATCH https://app.fakturoid.cz/api/v3/accounts/{slug}/recurring_generators/{id}.json

Headers

Name	Value
`User-Agent`	`YourApp (yourname@example.com)`
`Content-Type`	`application/json`

URL Parameters

Name	Description	Type	Example
`slug`	Account name	`String`	`applecorp`
`id`	Recurring generator ID	`Integer`	`24`

Body

{
  "name": "Web UI"
}

Response

Status 200 OK

Body

{
  "id": 28,
  "custom_id": null,
  "name": "Web UI",
  "active": true,
  "proforma": false,
  "paypal": false,
  "gopay": false,
  "start_date": "2023-10-13",
  "end_date": null,
  "months_period": 12,
  "next_occurrence_on": "2023-10-13",
  "last_day_in_month": false,
  "tax_date_at_end_of_last_month": false,
  "due": 14,
  "send_email": false,
  "subject_id": 37,
  "number_format_id": null,
  "note": null,
  "footer_note": null,
  "legacy_bank_details": null,
  "bank_account_id": null,
  "iban_visibility": "automatically",
  "tags": [],
  "order_number": null,
  "currency": "CZK",
  "payment_method": "bank",
  "custom_payment_method": null,
  "exchange_rate": "1.0",
  "language": "cz",
  "vat_price_mode": "without_vat",
  "transferred_tax_liability": false,
  "oss": "disabled",
  "supply_code": null,
  "subtotal": "550.0",
  "total": "665.5",
  "native_subtotal": "550.0",
  "native_total": "665.5",
  "lines": [
    {
      "id": 1299,
      "name": "One plan",
      "quantity": "1.0",
      "unit_name": "",
      "unit_price": "550.0",
      "vat_rate": 21,
      "unit_price_without_vat": "550.0",
      "unit_price_with_vat": "665.5",
      "inventory_item_id": null
    }
  ],
  "html_url": "https://app.fakturoid.cz/applecorp/recurring_generators/28",
  "url": "https://app.fakturoid.cz/api/v3/accounts/applecorp/generators/28.json",
  "subject_url": "https://app.fakturoid.cz/api/v3/accounts/applecorp/subjects/37.json",
  "created_at": "2023-10-12T21:16:35.730+02:00",
  "updated_at": "2023-10-12T21:35:22.409+02:00"
}

Request with invalid data

Body

{
  "oss": "invoice"
}

Response

Status 422 Unprocessable Entity

Body

{
  "errors": {
    "oss": [
      "není v seznamu povolených hodnot"
    ]
  }
}

Pause Recurring Generator

If generator is successfuly updated the server will respond with 200 OK and a JSON body with its data.
Unsucessful request will result in response 422 Unprocessable Entity with a JSON body describing error or in response 404 Not Found if generator is not recurring nor exists.

Request

PATCH https://app.fakturoid.cz/api/v3/accounts/{slug}/recurring_generators/{id}/pause.json

Headers

Name	Value
`User-Agent`	`YourApp (yourname@example.com)`

URL Parameters

Name	Description	Type	Example
`slug`	Account name	`String`	`applecorp`
`id`	Generator ID	`Integer`	`28`

Response

Status 200 OK

Body

{
  "id": 28,
  "active": false,
  … // other generator attributes removed for brevity
}

Response if generator is already paused

Status 422 Unprocessable Entity

Body

{
  "errors": {
    "generator": [
      "Generator is already paused"
    ]
  }
}

Response if generator is already finished

Status 422 Unprocessable Entity

Body

{
  "errors": {
    "generator": [
      "Generator is already finished"
    ]
  }
}

Response if generator is not recurring or is not exists

Status 404 Not Found

Activate Recurring Generator

If generator is successfuly activated the server will respond with 200 OK and a JSON body with its data.
Unsucessful request will result in response 422 Unprocessable Entity with a JSON body describing error or in response 404 Not Found if generator is not recurring nor exists.
It is possible to specify the date of the next generator occurrence, it must be in the future.
If the generator has the last_day_in_month attribute set to true, the next occurrence will be the last day of the respective month.

Request

PATCH https://app.fakturoid.cz/api/v3/accounts/{slug}/recurring_generators/{id}/activate.json

Headers

Name	Value
`User-Agent`	`YourApp (yourname@example.com)`

URL Parameters

Name	Description	Type	Example
`slug`	Account name	`String`	`applecorp`
`id`	Generator ID	`Integer`	`28`

Body

{
  "next_occurrence_on": "2024-09-15"
}

Response

Status 200 OK

Body

{
  "id": 28,
  "active": true,
  "last_day_in_month": false,
  "next_occurrence_on": "2024-09-15",
  … // other generator attributes removed for brevity
}

Response if generator is already active

Status 422 Unprocessable Entity

Body

{
  "errors": {
    "generator": [
      "Generator is already active"
    ]
  }
}

Response if generator is already finished

Status 422 Unprocessable Entity

Body

{
  "errors": {
    "generator": [
      "Generator is already finished"
    ]
  }
}

Response if generator is not recurring or is not exists

Status 404 Not Found

Delete Recurring Generator

After deleting the recurring generator the server will respond with 204 No Content.

Request

DELETE https://app.fakturoid.cz/api/v3/accounts/{slug}/recurring_generators/{id}.json

Headers

Name	Value
`User-Agent`	`YourApp (yourname@example.com)`

URL Parameters

Name	Description	Type	Example
`slug`	Account name	`String`	`applecorp`
`id`	Recurring generator ID	`Integer`	`12`

Response

Status 204 No Content