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:
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:
What are the supported by the recurring invoice API properties?
If status_id is not supported, how a recurring invoice could be created/transitioned into âPendingâ state via API?
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)?
What is the recommended strategy for recurring invoices tax update based on group settings?
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?
Are we missing some âprocessing/refactoringâ API endpoints which will solve most of the above questions?
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.
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.
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.
Thank you for the example. What about if we want to stop a recurring invoice? Should we use âstopâ? Are there other actions available?
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.
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.
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.
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);
// 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!