Integrating invoicing systems with Jumpseller

To have a better sales process for your online store, you should implement automatic invoicing, it reduces the time wasted creating manually these documents and decreases the number of human errors, making order management easier.

With Jumpseller, it is very easy to integrate an external invoicing system, let us take you through the process of developing the integrating with an invoice software.

---

Requirements

If you want to integrate an Invoicing system with your store, here is what you need:

• A Jumpseller store
• An invoice software with an API and the credentials for the API (normally the communication is via XML or JSON);
• Technical knowledge in programming software to integrate both systems;
• The integration code, typically running on an external server, managing the communication between the store and the invoicing system.

---

Workflow

The typical flow between the two systems is:

• A new order is created in the Jumpseller store;
• The Jumpseller’s store informs the invoicing system of this new sale, passing a JSON with the order’s information via a webhook;
• The external invoicing system creates the invoice;
• Either the invoicing system or the integration notify the customer of the invoice generation, normally by attaching the invoice in PDF to an email;
• (optionally) if the invoicing system also controls the stock, the stock should be updated according this event;
• (optionally) when the Jumpseller’s order changes status - Pending Payment, Paid or Canceled - the invoicing system can also be informed - important when “Paid” orders are “Canceled” and a “Credit Note” needs to be created.

To view the full list of available options please see the invoicing section on Jumpseller Apps Chile and Jumpseller Apps Portugal.

---

Integration

The integration code, can be written in any given language, capable of processing JSON data. This integration code has to be hosted your own web-server and will handle the communication between the store and the invoicing system.

We recommend you to start by:

• Create a test store, free up to 14 days - contact us if you need more trial days;
• Add a webhook, which will fire data as a POST request on every “Order Update” to your Integration - use RequestBin to inspect them;
• At your Integration code, read the body message and headers of the POST request (i.e the Webhook from the previous step);
• With this data, process it and push it to the invoicing system, thus creating the invoice;
• Add an new “Order Document Entry” with the document type, ID and url to the Jumpseller’s store Order. Use the API POST /orders/{id}/documents.json endpoint;
• Send an email to the Customer, with the Merchant’s email address in BCC, informing him of the newly created invoice;
• “Tax Id” field can be set on a store as “Optional” or “Mandatory” on the Admin Panel. Prepare your Integration according with this;
• (optionally) create “Checkout Custom Fields” to collect specific Invoicing Information, like “Business Name”. Use the API too.
• (optionally) add Javascript Code to the store’s front-end to validate fields, like “Business Name” or the “Tax Id”. Use the Javascript Apps for this purpose.
• (optionally) every hour or every day, use the API to list all orders from a store and save them (fields: order_id, order_status, invoice_id). Issue invoices for all those orders without and invoice_id. Use the REST API for this purpose.

When this is done we recommended you to publish your integration, as an App, to all Jumpseller merchants. This will increase your work visibility and will be easier for new merchants to install and start using your integration.

Invoicing with Gift Cards

• Ordered Products with type = 'gift_card' should be invoiced with VAT Tax zero (0);
• (optionally) after redeeming a Gift Card - order.gift_cards_amount is positive - consider including a note or observation about the used Gift Card on the invoice document.

---

Resources

• Jumpseller’s Webhooks - triggering POST requests to external Apps
• Jumpseller’s API Documentation - listing all the endpoints for you Integration to communicate with a Jumpseller store
• Jumpseller’s Apps Documentation - explaining how to publish your Integration as an App to all Jumpseller’s merchants
• Ngrok - local tunnelling, allowing your Integration to communicate with the Jumpseller’s store & invoicing system
• ResquestBin - to inspect POST requests from the Jumpseller hooks.

---

Frequently asked questions

1. In case of roundings, how are they done?
Roundings are done item by item basis (and not on the order.total). There is extensive literature and legislation about it.

2. What is the Time/Dates format?
All Jumpseller dates are represented as strings in Coordinated Universal Time (UTC), like: “2023-02-10 13:56:35 UTC”. You should transform this date-time to the most appropriate timezone.