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)
- Invoices
- Products / services
- Clients
- Warehouse Documents
- Payments
- Categories
- Warehouses
- Integrations
- Departments
NOTE: Full documentation can be found on GitHub
https://github.com/InvoiceOcean/api
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
Download code CURL
https://YOUR_DOMAIN.invoiceocean.com/invoices.json?period=this_month&page=1&per_page=25&api_token=API_TOKEN
XML
Download code CURL
https://YOUR_DOMAIN.invoiceocean.com/invoices.xml?period=this_month&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)
Select invoice by ID
JSON
Download code CURL
https://YOUR_DOMAIN.invoiceocean.com/invoices/100.json?api_token=API_TOKEN
XML
Download code CURL
https://YOUR_DOMAIN.invoiceocean.com/invoices/100.xml?api_token=API_TOKEN
Download invoice as PDF
PDF
Download code CURL
https://YOUR_DOMAIN.invoiceocean.com/invoices/100.pdf?api_token=API_TOKEN
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 CURLWith 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 CURLXML
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 CURLExample 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 CURLAdding invoice with amount discount
NOTE: Before issuing, make sure to check 'Value' in Account Settings -> How to calculate a discountcurl 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 CURLAdding 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 CURLInvoice 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 CURLDelete 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
JSONcurl "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 CURLAdd 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 CURLAdd new warehouse document for existing client, department and product
To set default department just skip these keys: department_id and department_nameJSON
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 CURLUpdate 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 CURLDelete 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 CURLProduct 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 CURLWidget
To download payment widget (in JS format) enter URL:
https://app.invoiceocean.com/a/YOUR_DOMAIN/p/{{token}}.js
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 CURLClient 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 CURLPayments
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 CURLfull 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 CURLCategories
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 CURLList 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 CURLList 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 JSONGet 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 JSONCreating 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 JSONCreating a new account with the account's owner and company data
JSONcurl 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 CURLGet account info
Download code CURL
https://YOUR_DOMAIN.invoiceocean.com/account.json?api_token=API_TOKEN&integration_token=email-us-for-this-token
Departments
Add logo
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
- Invoices
- Products / services
- Clients
- Warehouse Documents
- Payments
- Categories
- Warehouses
- Integrations
- Departments