InvoiceOcean API

This API allows you to easily integrate with other applications. In the examples below we use CURL tool - you can easily change it to any computer language.

Please contact us If you want any additional API function, we will add it as fast as possible.

All examples work with JSON too (you simply need to change xml extension to json)

NOTE: Full documentation can be found on GitHub https://github.com/InvoiceOcean/api

API token ?

API token can be downloaded from the application's settings (Settings -> Account settings -> Integration -> API authorization code)

Invoices

Select all invoices from a selected time period

select invoice from current month:

JSON
https://YOUR_DOMAIN.invoiceocean.com/invoices.json?period=this_month&page=1&per_page=25&api_token=API_TOKEN
Download code CURL

XML
https://YOUR_DOMAIN.invoiceocean.com/invoices.xml?period=this_month&page=1&per_page=25&api_token=API_TOKEN
Download code CURL

You can pass the same parameters that are passed in the application (on the invoice list)

Select invoice by ID

JSON
https://YOUR_DOMAIN.invoiceocean.com/invoices/100.json?api_token=API_TOKEN
Download code CURL

XML
https://YOUR_DOMAIN.invoiceocean.com/invoices/100.xml?api_token=API_TOKEN
Download code CURL

Download invoice as PDF

PDF
https://YOUR_DOMAIN.invoiceocean.com/invoices/100.pdf?api_token=API_TOKEN
Download code CURL

Send invoice to client by email

JSON curl -X POST "https://YOUR_DOMAIN.invoiceocean.com/invoices/100/send_by_email.json?api_token=API_TOKEN" XML curl -X POST "https://YOUR_DOMAIN.invoiceocean.com/invoices/100/send_by_email.xml?api_token=API_TOKEN"

Download invoice by OID

JSON curl "https://YOUR_DOMAIN.invoiceocean.com/invoices.json?oid=nr_zam&api_token=API_TOKEN" XML curl "https://YOUR_DOMAIN.invoiceocean.com/invoices.xml?oid=nr_zam&api_token=API_TOKEN"

Download invoice by Id of document which was generated based on that invoice

JSON curl "https://YOUR_DOMAIN.invoiceocean.com/invoices.json?invoice_id=id&api_token=API_TOKEN" XML curl "https://YOUR_DOMAIN.invoiceocean.com/invoices.xml?invoice_id=id&api_token=API_TOKEN"

Download invoice by Id of document which was base of that invoice

JSON curl "https://YOUR_DOMAIN.invoiceocean.com/invoices.json?from_invoice_id=id&api_token=API_TOKEN" XML curl "https://YOUR_DOMAIN.invoiceocean.com/invoices.xml?from_invoice_id=id&api_token=API_TOKEN"



Add new invoice

JSON (recommended)

JSON (recommended)

curl https://YOUR_DOMAIN.invoiceocean.com/invoices.json \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "api_token": "API_TOKEN", "invoice": { "kind":"vat", "number": null, "sell_date": "2024-12-02", "issue_date": "2024-12-02", "payment_to": "2024-12-09", "seller_name": "Seller SA", "seller_tax_no": "6272616681", "buyer_name": "Client1 SA", "buyer_tax_no": "6272616681", "positions":[ {"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1}, {"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2} ] }}' Download code CURL



With default department data : curl https://YOUR_DOMAIN.invoiceocean.com/invoices.json \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "api_token": "API_TOKEN", "invoice": { "kind":"vat", "number": null, "sell_date": "2024-12-02", "issue_date": "2024-12-02", "payment_to": "2024-12-09", "buyer_name": "Client1 SA", "buyer_tax_no": "6272616681", "positions":[ {"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1}, {"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2} ] }}' Download code CURL



XML

curl https://YOUR_DOMAIN.invoiceocean.com/invoices.xml \ -u 'login:YOUR_PASSWORD' \ -H 'Accept: application/xml' \ -H 'Content-Type: application/xml' \ -d '<invoice> <kind>vat</kind> <sell_date>2024-12-02</sell_date> <issue_date>2024-12-02</issue_date> <payment_to>2024-12-09</payment_to> <seller_name>Seller SA</seller_name> <seller_tax_no>6272616681</seller_tax_no> <buyer_name>Client1 SA</buyer_name> <buyer_tax_no>6272616681</buyer_tax_no> <positions> <position> <name>Produkt X1</name> <tax>23</tax> <total_price_gross>20</total_price_gross> <quantity>1</quantity> </position> <position> <name>Produkt X2</name> <tax>0</tax> <total_price_gross>10</total_price_gross> <quantity>3</quantity> </position> </positions> </invoice>' Download code CURL


Example in Ruby

endpoint = 'https://YOUR_DOMAIN.invoiceocean.com/invoices.json' uri = URI.parse(endpoint) json_params = { "api_token" => "API_TOKEN", "invoice" => { "kind" =>"vat", "number" => nil, "sell_date" => "2024-12-02", "issue_date" => "2024-12-02", "payment_to" => "2024-12-09", "buyer_name" => "Client1 SA", "buyer_tax_no" => "6272616681", "positions" =>[ {"name" =>"Produkt A1", "tax" =>23, "total_price_gross" =>10.23, "quantity" =>1}, {"name" =>"Produkt A2", "tax" =>0, "total_price_gross" =>50, "quantity" =>2} ] }} request = Net::HTTP::Post.new(uri.path) request.body = JSON.generate(json_params) request["Content-Type"] = "application/json" http = Net::HTTP.new(uri.host, uri.port) response = http.start {|h| h.request(request)} if response.code == '201' ret = JSON.parse(response.body) else ret = response.body end puts ret.to_json



Javascript / Ajax jQuery

json_params = { "api_token": "API_TOKEN", "invoice": { "kind":"vat", "number": null, "sell_date": "2024-12-02", "issue_date": "2024-12-02", "payment_to": "2024-12-09", "buyer_name": "Client1 SA", "buyer_tax_no": "6272616681", "positions":[ {"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1}, {"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2} ] }} //alert(JSON.stringify(json_params)) endpoint = 'https://YOUR_DOMAIN.invoiceocean.com/invoices.json' $.ajax({ type: "POST", url: endpoint, data: json_params, dataType: 'json', success: function(data) { alert('invoice created! ' + data['number'])}, });

Adding invoice with a percentage discount

NOTE: Prior to issuing, please check that in Account Settings, field: 'How to calculate a discount' is set for 'percentage per net unit price' curl https://YOUR_DOMAIN.invoiceocean.com/invoices.json \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "api_token": "API_TOKEN", "invoice": { "kind":"vat", "number": null, "sell_date": "2024-12-02", "issue_date": "2024-12-02", "payment_to": "2024-12-09", "seller_name": "Seller SA", "seller_tax_no": "6272616681", "buyer_name": "Client1 SA", "buyer_tax_no": "6272616681", "show_discount": true, "discount_kind": "percent_unit", "positions":[ {"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1, "discount_percent": 50}, {"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2, "discount_percent": 10} ] }}' Download code CURL



Adding invoice with amount discount

NOTE: Before issuing, make sure to check 'Value' in Account Settings -> How to calculate a discount
curl https://YOUR_DOMAIN.invoiceocean.com/invoices.json \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "api_token": "API_TOKEN", "invoice": { "kind":"vat", "number": null, "sell_date": "2024-12-02", "issue_date": "2024-12-02", "payment_to": "2024-12-09", "seller_name": "Seller SA", "seller_tax_no": "6272616681", "buyer_name": "Client1 SA", "buyer_tax_no": "6272616681", "show_discount": true, "discount_kind": "amount", "positions":[ {"name":"Produkt A1", "tax":23, "total_price_gross":10.23, "quantity":1, "discount": 5}, {"name":"Produkt A2", "tax":0, "total_price_gross":50, "quantity":2, "discount": 25} ] }}' Download code CURL


Adding invoice to existing client and product

If you have your client's ID (client_id), seller (department_id) or product (product_id) you do not have to enter more data. Invoice will be issued with the current date and 5 day maturity.
curl https://YOUR_DOMAIN.invoiceocean.com/invoices.json \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{"api_token": "API_TOKEN", "invoice": { "payment_to_kind": 5, "department_id": 222, "client_id": 111, "positions":[ {"product_id": 333, "quantity":2} ] }}' Download code CURL


Invoice update


curl https://YOUR_DOMAIN.invoiceocean.com/invoices/444.json \ -X PUT \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{"api_token": "API_TOKEN", "invoice": { "buyer_name": "New buyer name SA" }}' Download code CURL



Delete invoice

JSON curl -X DELETE "https://YOUR_DOMAIN.invoiceocean.com/invoices/100.json?api_token=API_TOKEN" XML curl -X DELETE "https://YOUR_DOMAIN.invoiceocean.com/invoices/100.xml?api_token=API_TOKEN"



Warehouse Documents


All warehouse documents


JSON curl "https://YOUR_DOMAIN.invoiceocean.com/warehouse_documents.json?page=1&per_page=25&api_token=API_TOKEN" You can pass the same parameters that are passed in the application (on the invoice list)


Fetch warehouse document by ID

JSON curl "https://YOUR_DOMAIN.invoiceocean.com/warehouse_documents/555.json?api_token=API_TOKEN"


Add new Goods Received Note



JSON

curl https://YOUR_DOMAIN.invoiceocean.com/warehouse_documents.json \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "api_token": "API_TOKEN", "warehouse_document": { "kind":"pz", "number": null, "warehouse_id": "1", "issue_date": "2024-12-02", "department_name": "Department1 SA", "client_name": "Client1 SA", "warehouse_actions":[ {"product_name":"Produkt A1", "purchase_tax":23, "purchase_price_net":10.23, "quantity":1}, {"product_name":"Produkt A2", "purchase_tax":0, "purchase_price_net":50, "quantity":2} ] }}' Download code CURL



Add new Goods Issued Note



JSON

curl https://YOUR_DOMAIN.invoiceocean.com/warehouse_documents.json \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "api_token": "API_TOKEN", "warehouse_document": { "kind":"wz", "number": null, "warehouse_id": "1", "issue_date": "2024-12-02", "department_name": "Department1 SA", "client_name": "Client1 SA", "warehouse_actions":[ {"product_id":"333", "tax":23, "price_net":10.23, "quantity":1}, {"product_id":"333", "tax":0, "price_net":50, "quantity":2} ] }}' Download code CURL



Add new warehouse document for existing client, department and product

To set default department just skip these keys: department_id and department_name

JSON

curl https://YOUR_DOMAIN.invoiceocean.com/warehouse_documents.json \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "api_token": "API_TOKEN", "warehouse_document": { "kind":"pz", "number": null, "warehouse_id": "1", "issue_date": "2024-12-02", "department_id": "222", "client_id": "111", "warehouse_actions":[ {"product_id":"333", "purchase_tax":23, "price_net":10.23, "quantity":1}, {"product_id":"333", "purchase_tax":0, "price_net":50, "quantity":2} ] }}' Download code CURL



Update warehouse document


curl https://YOUR_DOMAIN.invoiceocean.com/warehouse_documents/555.json \ -X PUT \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{"api_token": "API_TOKEN", "warehouse_document": { "client_name": "New client name SA" }}' Download code CURL



Delete warehouse document

JSON curl -X DELETE "https://YOUR_DOMAIN.invoiceocean.com/warehouse_documents/100.json?api_token=API_TOKEN"





Products / services

Products

JSON curl "https://YOUR_DOMAIN.invoiceocean.com/products.json?page=1&per_page=25&api_token=API_TOKEN&page=1" XML curl "https://YOUR_DOMAIN.invoiceocean.com/products.xml?page=1&per_page=25&api_token=API_TOKEN&page=1"

Select product using their ID

curl "https://YOUR_DOMAIN.invoiceocean.com/products/100.xml?api_token=API_TOKEN"

Add product


curl https://YOUR_DOMAIN.invoiceocean.com/products.json \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{"api_token": "API_TOKEN", "product": { "name": "PoroductAA", "code": "A001", "price_net": "100", "tax": "23" }}' Download code CURL


Product update


curl https://YOUR_DOMAIN.invoiceocean.com/products/333.json \ -X PUT \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{"api_token": "API_TOKEN", "product": { "name": "PoroductAA2", "code": "A0012", "price_gross": "102" }}' Download code CURL


Widget

To download payment widget (in JS format) enter URL:

https://app.invoiceocean.com/a/YOUR_DOMAIN/p/{{token}}.js

where {{token}} is a specific token product value



Clients

Clients

JSON curl "https://YOUR_DOMAIN.invoiceocean.com/clients.json?page=1&per_page=25&api_token=API_TOKEN" XML curl "https://YOUR_DOMAIN.invoiceocean.com/clients.xml?page=1&per_page=25&api_token=API_TOKEN"

Select client using their ID

curl "https://YOUR_DOMAIN.invoiceocean.com/clients/100.xml?api_token=API_TOKEN"

Select client using their external ID

JSON curl "https://YOUR_DOMAIN.invoiceocean.com/clients.json?external_id=100&api_token=API_TOKEN" XML curl "https://YOUR_DOMAIN.invoiceocean.com/clients.xml?external_id=100&api_token=API_TOKEN"

Adding client


curl https://YOUR_DOMAIN.invoiceocean.com/clients.json \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{"api_token": "API_TOKEN", "client": { "name": "Client1", "tax_no": "6272616681", "bank" : "bank1", "bank_account" : "bank_account1", "city" : "city1", "country" : "", "email" : "example@email.com", "person" : "person1", "post_code" : "post-code1", "phone" : "phone1", "street" : "street1" }}' Download code CURL


Client update

curl https://YOUR_DOMAIN.invoiceocean.com/clients/111.json \ -X PUT \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{"api_token": "API_TOKEN", "client": { "name": "Klient2", "tax_no": "62726166812", "bank" : "bank2", "bank_account" : "bank_account2", "city" : "city2", "country" : "PL", "email" : "example2@email.com", "person" : "person2", "post_code" : "post-code2", "phone" : "phone2", "street" : "street2" }}' Download code CURL





Payments

Payments


JSON curl "https://YOUR_DOMAIN.invoiceocean.com/banking/payments.json?page=1&per_page=25&api_token=API_TOKEN"
XML curl "https://YOUR_DOMAIN.invoiceocean.com/banking/payments.xml?page=1&per_page=25&api_token=API_TOKEN"

Select payment using their ID


JSON curl "https://YOUR_DOMAIN.invoiceocean.com/banking/payment/100.json?api_token=API_TOKEN" XML curl "https://YOUR_DOMAIN.invoiceocean.com/banking/payments/100.xml?api_token=API_TOKEN"

Adding new payment

minimal JSON (recommended) curl https://YOUR_DOMAIN.invoiceocean.com/banking/payments.json \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "api_token": "API_TOKEN", "banking_payment": { "name":"Payment 001", "price": 100.05, "invoice_id": null, "paid":true, "kind": "api" }}' Download code CURL

full JSON (recommended) curl https://YOUR_DOMAIN.invoiceocean.com/banking/payments.json \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "api_token": "API_TOKEN", "banking_payment": { "city": null, "client_id":null, "comment":null, "country":null, "currency":"PLN", "deleted":false, "department_id":null, "description":"abonament roczny", "email":"email@email.pl", "first_name":"Jan", "generate_invoice":true, "invoice_city":"Warszawa", "invoice_comment":"", "invoice_country":null, "invoice_id":null, "invoice_name":"Company name", "invoice_post_code":"00-112", "invoice_street":"street 52", "invoice_tax_no":"6272616681", "last_name":"Kowalski", "name":"Plantnosc za produkt1", "oid":"", "paid":true, "paid_date":null, "phone":null, "post_code":null, "price":"100.00", "product_id":1, "promocode":"", "provider":"transfer", "provider_response":null, "provider_status":null, "provider_title":null, "quantity":1, "street":null, "kind": "api" }}' Download code CURL



Categories

Create new category

JSON (recommended) curl https://YOUR_DOMAIN.invoiceocean.com/categories.json \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "api_token": "API_TOKEN", "category": { "name": "my_category", "description": null } }' Download code CURL



List of categories

XML curl "https://YOUR_DOMAIN.invoiceocean.com/categories.xml?api_token=API_TOKEN" JSON curl "https://YOUR_DOMAIN.invoiceocean.com/categories.json?api_token=API_TOKEN"



Obtaining information for a single category by ID

XML curl "https://YOUR_DOMAIN.invoiceocean.com/categories/100.xml?api_token=API_TOKEN" JSON curl "https://YOUR_DOMAIN.invoiceocean.com/categories/100.json?api_token=API_TOKEN"



More examples: https://github.com/InvoiceOcean/api



Warehouses

Create new warehouse

JSON (recommended) curl https://YOUR_DOMAIN.invoiceocean.com/warehouses.json \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "api_token": "API_TOKEN", "warehouse": { "name": "my_warehouse", "kind": null, "description": null } }' Download code CURL



List of Warehouses

JSON curl "https://YOUR_DOMAIN.invoiceocean.com/warehouses.json?api_token=API_TOKEN" XML curl "https://YOUR_DOMAIN.invoiceocean.com/warehouses.xml?api_token=API_TOKEN"



Obtaining warehouse information based on ID

JSON curl "https://YOUR_DOMAIN.invoiceocean.com/warehouses/100.json?api_token=API_TOKEN" XML curl "https://YOUR_DOMAIN.invoiceocean.com/warehouses/100.xml?api_token=API_TOKEN"




Integrations


Add a new user

JSON method: POST url: https://app.invoiceocean.com/users.json { "user": { "email": "email10882@fakturowytmail.pl", "password": "your_secret_password" }, "integration_token": "email-us-for-this-token" } Download code CURL | Download code Ruby | Download code JavaScript | Download code PHP | Download code JSON


Get user info (with API Access Token)

JSON method: POST url: https://app.invoiceocean.com/login.json { "login": "email10882@fakturowytmail.pl", "password": "your_secret_password", "integration_token": "email-us-for-this-token" } Download code CURL | Download code Ruby | Download code JavaScript | Download code PHP | Download code JSON



Creating new account

JSON method: POST url: https://app.invoiceocean.com/account.json { "api_token": "API_TOKEN", "account": { "prefix": "ftprefix" }, "integration_token": "email-us-for-this-token" } Download code CURL | Download code Ruby | Download code JavaScript | Download code PHP | Download code JSON



Creating a new account with the account's owner and company data

JSON curl https://app.invoiceocean.com/account.json \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "api_token": "API_TOKEN", "account": { "prefix": "prefix1" }, "user": { "login": "login1", "email": "email1@email.pl", "password": "password1", "from_partner": "PARTNER_CODE" }, "company": { "name": "Company1", "tax_no": "5252445700", "post_code": "00-112", "city": "Warsaw", "street": "Street 1/10", "person": "Jan Nowak", "bank": "Bank1", "bank_account": "111222333444555666111" }, "integration_token": "email-us-for-this-token" }' Download code CURL

Get account info


https://YOUR_DOMAIN.invoiceocean.com/account.json?api_token=API_TOKEN&integration_token=email-us-for-this-token
Download code CURL



Departments


curl -X PUT https://YOUR_DOMAIN.invoiceocean.com/departments/222.json \ -F 'api_token=API_TOKEN' \ -F 'department[logo]=@/file_path/logo.png' Download code CURL



More examples: https://github.com/InvoiceOcean/api