Create/Update recurring invoice via API

Self-Hosted | v5
1

Running IN v.5.5.86-C109 via docker-compose with nginx and mariaDB.
Purpose - evaluation for whitelabel or hosted licensing.
So far very impressed by the UI and the feature set.
Currently running integration scenarios with Java base application.

At that stage we are trying to create recurring invoices for customers via API.
Step 1
Expectations:
POST /api/v1/recurring_invoices with minimum set of properties:

{
    "client_id": "existing_client_id",
    "line_items": [
        {
            "product_key": "existing_product_key_1"
        },
        {
            "product_key": "existing_product_key_2"
        }
    ],
    "entity_type": "recurringInvoice",
    "frequency_id": "5",
    "remaining_cycles": -1
}

will result in fully functional recurring invoice based on company, group, client and product settings.
Result:
Unusable empty recurring invoice.
Step 2
This led us to think that reference a manually created “template” recurring invoice might be a better approach.
Expectations:
GET /api/v1/recurring_invoices/{id} result could be cleared from source specifics and appended with new client_id and a consequent POST /api/v1/recurring_invoices will result in fully functional recurring invoice.
Result:
Matches the expectations. However all newly created recurring invoices are in “Draft” state.
Step 3
Expectations:
PUT /api/v1/recurring_invoices/{id} with status_id of 2 will move the entity to “Pending” state.

{
   "status_id":"2"
}

Result:
No change in state of the entity.

Given the above, could you please suggest:

  1. What are the supported by the recurring invoice API properties?
  2. If status_id is not supported, how a recurring invoice could be created/transitioned into “Pending” state via API?
  3. If the recurring invoice has a line item with variable quantity between billing periods, what would be the best approach to update the invoice so it reflects the line item new quantity (and related totals)?
  4. What is the recommended strategy for recurring invoices tax update based on group settings?
  5. Could you confirm that some entities relationships are intentionally removed? For example change in product price will not be reflected in recurring invoice created prior the product price change. What is the recommended strategy in such situations? Bulk update to recurring invoices?
  6. Are we missing some “processing/refactoring” API endpoints which will solve most of the above questions?

Thank you in advance for your time.

1 Like
2

Hi,

  1. Sorry, I don’t understand this question
  2. You can use the ‘start’ bulk action, the status_id field is read only
  3. One option may be to use the API
  4. I think this would also require the API
  5. That’s correct, we’d recommend using the API
  6. I don’t believe so
3

Thank you for your swift response.
On:

  1. The question refers to the API endpoints related with recurring invoice entity management. The documentation doesn’t specify anything about the fields (properties) which should be used in CRUD operations. Example for that is status_id field which is returned in the response but it turns out to be read only field. Documentation update with the relevant information might be helpful.
  2. Can you provide a simple example on how to use the ‘start’ action to apply on the docs example data for POST /api/v1/recurring_invoices/bulk:
[
  [
    0,
    1,
    2,
    3
  ]
]

There is nothing for the supported "actions’ in the documentation. What are the other bulk actions available to use with this endpoint and how to use them?
3. This is our intention, however adding a line item in an (recurring) invoice doesn’t help much. Nothing else is changed in the invoice properties. We have to update discounts, taxes and totals. An alternative to such update is to update the DB record for this invoice. All the logic available when one works with the UI is not applied during the invoice update via API.
4. We actually don’t want to use the UI for creation of IN entities and to apply updates to existing entities. So yes, the API is the way to go. However if we change a group setting, this is not applied neither through the API nor through the UI to existing (recurring) invoice although from our perspective it should.
5. Understood. This requires to replicate the logic for the calculated fields in an (recurring) invoice in our system, to ensure CRUD operations are correct.
6. Thank you for confirming. We were hoping that the “UI” based invoice CRUD logic is exposed somewhere as API endpoint.

4
  1. The fields are listed in the docs here: https://api-docs.invoicing.co/
  2. You’d want to pass {'action': 'start', 'ids':['3412332']}
  3. If you change a recurring invoice it will affect the next invoices it generates
  4. Feel free to create a feature request here: Issues ¡ invoiceninja/invoiceninja ¡ GitHub
5
  1. I am sorry, but we fail to see what are the fields which are available for Invoice Ninja API Spec. The example lists all fields from the response, but it doesn’t provide any information for the fields available to use in the request.
  2. Thank you for the example. What about if we want to stop a recurring invoice? Should we use ‘stop’? Are there other actions available?
  3. The focus here is not on the invoice change, but on group property change which affects the invoice definition. It works when the invoice is created from scratch, but it is not applied to the invoice when updated at later stage to recurring invoices.
6
  1. I don’t think that’s specified, one option is to use the network tab in the browser console to debug the API requests made by the app.
  2. Correct, the action is stop
  3. @david any thoughts?
7

@Lara

The api docs are still a work in progress, I’ll focus on recurring invoices next.

Recurring invoices have bulk actions where you can pass an array of recurring invoice IDs along with an action:

availabe actions include:

start
stop
archive
restore
delete
send_now (only works for recurring invoices that are in a draft state.

{POST} /api/v1/recurring_invoices/bulk

{‘action’: ‘start’, ‘ids’:[‘id’,‘id’,id’]}

Alternatively if you only wish to target individual invoices you can do this via the

PUT verb on /api/v1/recurring_invoices/{id}?stop=true
or
POST on /api/v1/recurring_invoices?start=true

actions are available at the query level here ?start=true ?stop=true send_now=true

1 Like
8

@david
Thank you for the detailed response.

The following I believe would be a valuable feedback for you from our evaluation process so far:

Our internal discussion demonstrated a growing concern regarding the conceptual approach towards cross-entities lack of relationship or an alternative processing.

An example is the use case described above. It involves recurring invoices (we can speculate that any recurring entity will be impacted also, such as expenses) and the entities settings/properties used for their composition like: client, product, group, tax, etc.
It is not unusual to have a customer with recurring invoice being settled up and to have legitimate business reasons to update the price of a product included in the recurring invoice template. In IN case, one must update all recurring invoices containing the updated product with product new price at line level and recalculate all calculated fields (totals, discounts, taxes) for each recurring invoice and each customer. Provided that a r-invoice can contain multiple products this in addition to be serious undertaking becomes an error prone process.

So far we didn’t get any guidance on how to approach the use case and we suppose, it is because there is no a good one.

9

Feature request had been logged: Enable recurring invoices/expenses auto-updates based on composing entities (group, client, product, tax, etc.) settings ¡ Issue #8370 ¡ invoiceninja/invoiceninja ¡ GitHub

1 Like
10

@Lara

The example of bulk updating products in Recurring Invoices has come up for discussion interally recently, we’ve had a few requests for this and are actively looking into it.

11

Hello All

I am late to the party, but for anyone searching for similar and using the SDK-php API.
The below worked for me, in creating a recurring invoice, emailing it to the customer, and setting its status to Pending (from Draft)

$ninja = new InvoiceNinja(YOUR_TOKEN);
$ninja->setUrl(YOUR_URL_IF_SELFHOSTED);

$invoice = $ninja->recurring_invoices->create([
‘client_id’ => $ninjaUserIDToken,
‘date’ => date(‘Y-m-d’),
‘due_date’ => date(‘Y-m-d’),
// recuring start
‘frequency_id’ => 5, // monthly
‘remaining_cycles’ => -1, // for ever
// recuring end
‘line_items’ => [
[
‘quantity’ => 1,
‘cost’ => ‘cost,’
‘product_key’ => ‘product_key’,
‘notes’ => ‘notes’,
],
],
],
[‘send_email’ => ‘true’]
);

// now sent the email, as it will NOT send after the start command!
$invoiceEmail = $ninja->recurring_invoices->bulk(“send_now”, array($invoice[‘data’][‘id’]));
// now take the invoice out of draft and set to pending
$invoiceStart = $ninja->recurring_invoices->bulk(“start”, array($invoice[‘data’][‘id’]));

The email is sent (i do have a server error when the email is clicked on, but i think this is a permissions issue… = my next thing to work out…) Howerver the invoice does show in the clients account!

1 Like