InvoiceXpress API

Invoices

Create invoices, invoice receipts, simplified invoices, vat moss invoices, credit notes & debit notes and send them to your clients.

Send by Email

PUT /:document-type/:document-id/email-document.json

Sends a document by email.

Example Body

{
  "message": {
    "client": {
      "email": "someone@example.com",
      "save": "0"
    },
    "subject": "Invoice from company",
    "body": "This is where the email body goes",
    "cc": "cc.client@company.com",
    "bcc": "bcc.client@company.com"
  }
}

Example Request

Format:
curl --request PUT \
  --url 'https://account_name.app.invoicexpress.com/:document-type/:document-id/email-document.json?api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"message":{"client":{"email":"someone@example.com","save":"0"},"subject":"Invoice from company","body":"This is where the email body goes","cc":"cc.client@company.com","bcc":"bcc.client@company.com","logo":"0"}}'
require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/:document-type/:document-id/email-document.json?api_key=YOUR%20API%20KEY%20HERE")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Put.new(url)
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request.body = "{\"message\":{\"client\":{\"email\":\"someone@example.com\",\"save\":\"0\"},\"subject\":\"Invoice from company\",\"body\":\"This is where the email body goes\",\"cc\":\"cc.client@company.com\",\"bcc\":\"bcc.client@company.com\",\"logo\":\"0\"}}"

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "PUT",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/:document-type/:document-id/email-document.json?api_key=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "application/json",
    "content-type": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({ message: 
   { client: { email: 'someone@example.com', save: '0' },
     subject: 'Invoice from company',
     body: 'This is where the email body goes',
     cc: 'cc.client@company.com',
     bcc: 'bcc.client@company.com',
     logo: '0' } }));
req.end();
import http.client

conn = http.client.HTTPSConnection("account_name.app.invoicexpress.com")

payload = "{\"message\":{\"client\":{\"email\":\"someone@example.com\",\"save\":\"0\"},\"subject\":\"Invoice from company\",\"body\":\"This is where the email body goes\",\"cc\":\"cc.client@company.com\",\"bcc\":\"bcc.client@company.com\",\"logo\":\"0\"}}"

headers = {
    'accept': "application/json",
    'content-type': "application/json"
    }

conn.request("PUT", "/:document-type/:document-id/email-document.json?api_key=YOUR%20API%20KEY%20HERE", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/:document-type/:document-id/email-document.json?api_key=YOUR%20API%20KEY%20HERE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\"message\":{\"client\":{\"email\":\"someone@example.com\",\"save\":\"0\"},\"subject\":\"Invoice from company\",\"body\":\"This is where the email body goes\",\"cc\":\"cc.client@company.com\",\"bcc\":\"bcc.client@company.com\",\"logo\":\"0\"}}",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://account_name.app.invoicexpress.com/:document-type/:document-id/email-document.json?api_key=YOUR%20API%20KEY%20HERE"

	payload := strings.NewReader("{\"message\":{\"client\":{\"email\":\"someone@example.com\",\"save\":\"0\"},\"subject\":\"Invoice from company\",\"body\":\"This is where the email body goes\",\"cc\":\"cc.client@company.com\",\"bcc\":\"bcc.client@company.com\",\"logo\":\"0\"}}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("accept", "application/json")
	req.Header.Add("content-type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Path Parameters

Name Type Required Description Example
document-type String Required

The type of document you wish to send by email: invoices, invoice_receipts, simplified_invoices, vat_moss_invoices, credit_notes or debit_notes.

invoices
document-id Integer Required

ID of the document to send by email.

42

Request Body

Name Type Required Description Example
message Object Required

Email data.

{
  "message": {
  "message": { ... }
Object

Email data

    "client": {
    "client": { ... }
Object

Client email and save options.

      "email": "someone@example.com",
String

[Required] Document will be sent to this email address. Must be a valid email address ex: foo@bar.com

      "save": "0"
String

[Required] Saves this email as your client email address. (0 – Does not save the client’s email. 1 – Saves / Updates the client’s email).

    },
    "subject": "Invoice from company",
String

[Optional] The subject of the email.

    "body": "This is where the email body goes",
String

[Optional] The body of the email.

    "cc": "cc.client@company.com",
String

[Optional] Email CC field. Must be a valid email address ex: foo@bar.com

    "bcc": "bcc.client@company.com",
String

[Optional] Email BCC field. Must be a valid email address ex: foo@bar.com

    "logo": "0"
String

[Optional] Send email with logo. Defaults to 0. Only available in some plans. It’s ignored if the account doesn’t have the logo configured. Not available for trial accounts. (0 - Send email without logo. 1 - Send email with logo )

  }
}

Responses

200 Success

The email was sent successfully.

(Empty Response)
401 Access denied

The API Key parameter is missing or is incorrectly entered.

(Empty Response)
404 Not Found

The supplied :document-id doesn’t match any existing document.

(Empty Response)
422 Unprocessable Entity

Some parameters sent were incorrect.

(Empty Response)

Generate PDF

GET /api/pdf/:document-id.json

Returns the url of the PDF for the specified document. This is an asynchronous operation, which means the PDF file may not be ready immediately.

Example Request

Format:
curl --request GET \
  --url 'https://account_name.app.invoicexpress.com/api/pdf/:document-id.json?second_copy=false&api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json'
require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/api/pdf/:document-id.json?second_copy=false&api_key=YOUR%20API%20KEY%20HERE")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/api/pdf/:document-id.json?second_copy=false&api_key=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
import http.client

conn = http.client.HTTPSConnection("account_name.app.invoicexpress.com")

headers = { 'accept': "application/json" }

conn.request("GET", "/api/pdf/:document-id.json?second_copy=false&api_key=YOUR%20API%20KEY%20HERE", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/api/pdf/:document-id.json?second_copy=false&api_key=YOUR%20API%20KEY%20HERE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://account_name.app.invoicexpress.com/api/pdf/:document-id.json?second_copy=false&api_key=YOUR%20API%20KEY%20HERE"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("accept", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Path Parameters

Name Type Required Description Example
document-id Integer Required

The document to convert to PDF.

42

Query Parameters

Name Type Required Description Example
second_copy Boolean Optional

Set value to true to generate copy of original document.

false

Responses

200 Success

The request has been successfully processed.

Invoices Generate pdf
{
  "output": {
  "output": { ... }
Object
    "pdfUrl": "https://sum.url"
String
  }
}
202 Accepted

The request will be processed. You need to keep requesting until you get a response with HTTP status code 200.

(Empty Response)
401 Access denied

The API Key parameter is missing or is incorrectly entered.

(Empty Response)
404 Not Found

No document matches the supplied :document-id.

(Empty Response)
406 Not Acceptable

The :document-id provided is in an invalid state.

(Empty Response)

Get

GET /:document-type/:document-id.json

Returns a specific invoice.

Example Request

Format:
curl --request GET \
  --url 'https://account_name.app.invoicexpress.com/:document-type/:document-id.json?api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json'
require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/:document-type/:document-id.json?api_key=YOUR%20API%20KEY%20HERE")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/:document-type/:document-id.json?api_key=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
import http.client

conn = http.client.HTTPSConnection("account_name.app.invoicexpress.com")

headers = { 'accept': "application/json" }

conn.request("GET", "/:document-type/:document-id.json?api_key=YOUR%20API%20KEY%20HERE", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/:document-type/:document-id.json?api_key=YOUR%20API%20KEY%20HERE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://account_name.app.invoicexpress.com/:document-type/:document-id.json?api_key=YOUR%20API%20KEY%20HERE"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("accept", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Path Parameters

Name Type Required Description Example
document-type String Required

The type of invoice you want to get. For example: invoices, invoice_receipts, simplified_invoices, vat_moss_invoices, credit_notes or debit_notes.

invoices
document-id Integer Required

The requested invoice id.

42

Responses

200 Success

The invoice was returned successfully.

Invoices Get
{
  "invoice": {
  "invoice": { ... }
Object
    "id": 2137287,
Integer
    "status": "final",
String
    "archived": false,
Boolean
    "type": "Invoice",
String
    "sequence_number": "6/G",
String
    "inverted_sequence_number": "G/6",
String
    "sequence_id": "12345",
String
    "tax_exemption": "M01",
String
    "date": "04/08/2016",
String
    "due_date": "19/08/2016",
String
    "reference": "foo",
String
    "observations": "foo",
String
    "retention": "foo",
String
    "permalink": "https://www.app.invoicexpress.com/documents/213728738ca780a8de4330cad4a5a556360304bd9c57011",
String
    "saft_hash": "J4ay",
String
    "sum": 24.39,
Number
    "discount": 0,
Integer
    "before_taxes": 24.39,
Number
    "taxes": 5.61,
Number
    "total": 30,
Integer
    "currency": "Euro",
String
    "client": {
    "client": { ... }
Object
      "id": 628535,
Integer
      "name": "John",
String
      "country": "Portugal"
String
    },
    items: [
Array
      {
      { ... }
Object

Items

        "name": "Large",
String
        "description": "foo",
String
        "unit_price": "24.3902",
String
        "unit": "foo",
String
        "quantity": "1.0",
String
        "tax": {
        "tax": { ... }
Object
          "id": 69166,
Integer
          "name": "IVA23",
String
          "value": 23
Integer
        },
        "discount": 0,
Integer
        "subtotal": 24.39,
Number
        "tax_amount": 5.61,
Number
        "discount_amount": 0,
Integer
        "total": 30
Integer
      }
    ]
    "mb_reference": {
    "mb_reference": { ... }
Object
      "entity": "10611",
String
      "value": 30,
Integer
      "reference": "952000823"
String
    }
  }
}
401 Access denied

The API Key parameter is missing or is incorrectly entered.

(Empty Response)
404 Not Found

No invoice matches the supplied :document-id.

(Empty Response)

List All

GET /invoices.json

Returns all your invoices. You can filter your invoices by passing parameters in the query string.
You can also call /invoice_receipts.json, /simplified_invoices.json, /vat_moss_invoices, /credit_notes.json, /debit_notes.json or /receipts.json which will return only those types of documents.
Note: When applying filters use /invoices.json.

Example Request

Format:
curl --request GET \
  --url 'https://account_name.app.invoicexpress.com/invoices.json?text=foo&type%5B%5D=Invoice&status%5B%5D=sent&date%5Bfrom%5D=30%2F09%2F2017&date%5Bto%5D=31%2F10%2F2017&due_date%5Bfrom%5D=30%2F09%2F2017&due_date%5Bto%5D=31%2F10%2F2017&total_before_taxes%5Bfrom%5D=100.00&total_before_taxes%5Bto%5D=500.00&non_archived=true&archived=false&page=1&per_page=30&api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json'
require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/invoices.json?text=foo&type%5B%5D=Invoice&status%5B%5D=sent&date%5Bfrom%5D=30%2F09%2F2017&date%5Bto%5D=31%2F10%2F2017&due_date%5Bfrom%5D=30%2F09%2F2017&due_date%5Bto%5D=31%2F10%2F2017&total_before_taxes%5Bfrom%5D=100.00&total_before_taxes%5Bto%5D=500.00&non_archived=true&archived=false&page=1&per_page=30&api_key=YOUR%20API%20KEY%20HERE")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/invoices.json?text=foo&type%5B%5D=Invoice&status%5B%5D=sent&date%5Bfrom%5D=30%2F09%2F2017&date%5Bto%5D=31%2F10%2F2017&due_date%5Bfrom%5D=30%2F09%2F2017&due_date%5Bto%5D=31%2F10%2F2017&total_before_taxes%5Bfrom%5D=100.00&total_before_taxes%5Bto%5D=500.00&non_archived=true&archived=false&page=1&per_page=30&api_key=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
import http.client

conn = http.client.HTTPSConnection("account_name.app.invoicexpress.com")

headers = { 'accept': "application/json" }

conn.request("GET", "/invoices.json?text=foo&type%5B%5D=Invoice&status%5B%5D=sent&date%5Bfrom%5D=30%2F09%2F2017&date%5Bto%5D=31%2F10%2F2017&due_date%5Bfrom%5D=30%2F09%2F2017&due_date%5Bto%5D=31%2F10%2F2017&total_before_taxes%5Bfrom%5D=100.00&total_before_taxes%5Bto%5D=500.00&non_archived=true&archived=false&page=1&per_page=30&api_key=YOUR%20API%20KEY%20HERE", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/invoices.json?text=foo&type%5B%5D=Invoice&status%5B%5D=sent&date%5Bfrom%5D=30%2F09%2F2017&date%5Bto%5D=31%2F10%2F2017&due_date%5Bfrom%5D=30%2F09%2F2017&due_date%5Bto%5D=31%2F10%2F2017&total_before_taxes%5Bfrom%5D=100.00&total_before_taxes%5Bto%5D=500.00&non_archived=true&archived=false&page=1&per_page=30&api_key=YOUR%20API%20KEY%20HERE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://account_name.app.invoicexpress.com/invoices.json?text=foo&type%5B%5D=Invoice&status%5B%5D=sent&date%5Bfrom%5D=30%2F09%2F2017&date%5Bto%5D=31%2F10%2F2017&due_date%5Bfrom%5D=30%2F09%2F2017&due_date%5Bto%5D=31%2F10%2F2017&total_before_taxes%5Bfrom%5D=100.00&total_before_taxes%5Bto%5D=500.00&non_archived=true&archived=false&page=1&per_page=30&api_key=YOUR%20API%20KEY%20HERE"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("accept", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Query Parameters

Name Type Required Description Example
text String Optional

Search for invoice, client or item details.

foo
type[] String Required

Possible values: Invoice, InvoiceReceipt, SimplifiedInvoice, VatMossInvoice, CreditNote, DebitNote, Receipt or CashInvoice.

Invoice
status[] String Required

Possible values: draft, sent, settled, canceled or second_copy.

sent
date[from] String Optional

Date in format dd/mm/yyyy. Ex: 30/09/2017

30%2F09%2F2017
date[to] String Optional

Date in format dd/mm/yyyy. Ex: 31/10/2017

31%2F10%2F2017
due_date[from] String Optional

Due Date in format dd/mm/yyyy. Ex: 30/09/2017

30%2F09%2F2017
due_date[to] String Optional

Due Date in format dd/mm/yyyy. Ex: 31/10/2017

31%2F10%2F2017
total_before_taxes[from] Number Optional

Minimum document amount. Ex: 100.00

100.00
total_before_taxes[to] Number Optional

Maximum document amount. Ex: 500.00

500.00
non_archived Boolean Required

Possible values: true or false.

true
archived Boolean Optional

Possible values: true or false.

false
page Integer Optional

You can ask for a specific page of invoices. Defaults to 1.

1
per_page String Optional

You can specify how many results you want to fetch. Defaults to 10 or value defined in account settings (10, 20 or 30).

30

Responses

200 Success

Invoices were returned successfully.

Invoices List all
{
  invoices: [
Array

List of invoices

    {
    { ... }
Object

Invoice Object

      "id": 541793,
Integer
      "status": "final",
String
      "archived": true,
Boolean
      "type": "Invoice",
String
      "sequence_number": "28/A",
String
      "inverted_sequence_number": "A/28",
String
      "date": "27/06/2017",
String
      "due_date": "27/06/2017",
String
      "reference": "foo",
String
      "observations": "foo",
String
      "retention": "foo",
String
      "permalink": "https://www.app.invoicexpress.com/documents/541793e1ab2ebd5c06def40c346ffbe0ff2b463eb1c0f0",
String
      "saft_hash": "Tdik",
String
      "sum": 1,
Integer
      "discount": 0,
Integer
      "before_taxes": 1,
Integer
      "taxes": 0.07,
Number
      "total": 1.07,
Number
      "currency": "Euro",
String
      "client": {
      "client": { ... }
Object
        "id": 1310176,
Integer
        "name": "John",
String
        "country": "Portugal"
String
      },
      items: [
Array
        {
        { ... }
Object

Items

          "name": " iPhone ",
String
          "description": "foo",
String
          "unit_price": "1.0",
String
          "unit": "foo",
String
          "quantity": "1.0",
String
          "tax": {
          "tax": { ... }
Object
            "id": 31597,
Integer
            "name": "IVA7",
String
            "value": 7
Integer
          },
          "discount": 0,
Integer
          "subtotal": 1,
Integer
          "tax_amount": 0.07,
Number
          "discount_amount": 0,
Integer
          "total": 1.07
Number
        }
      ]
      "sequence_id": "12345",
String
      "tax_exemption": "M01"
String
    }
  ]
  "pagination": {
  "pagination": { ... }
Object

Pagination info.

    "total_entries": 6,
Integer
    "current_page": 1,
Integer
    "total_pages": 1,
Integer
    "per_page": 10
Integer
  }
}
401 Access denied

The API Key parameter is missing or is incorrectly entered.

(Empty Response)

Create

POST /:document-type.json

Creates a new invoice, simplified_invoice, invoice_receipt, credit_note or debit_note.

Creating new clients or items along with the invoice

This method also allows to create a new client and/or new items in the same request with the following behavior:

  • If the client name does not exist a new one is created.
  • If items do not exist with the given names, new ones will be created.
  • If item name already exists, the item is updated with the new values.

Taxes

Regarding item taxes, if the tax name is not found, the default tax is applyed to that item. Portuguese accounts should also send the IVA exemption reason if the invoice contains exempt items (IVA 0%).

Note: Simplified Invoices are only available in Portugal.

Example URL

https://ACCOUNT_NAME.app.invoicexpress.com/invoices.json?api_key=API_KEY

You can find your ACCOUNT_NAME and API_KEY here: https://www.app.invoicexpress.com/users/api

Example Body

{
  "invoice": {
    "date": "07/05/2017",
    "due_date": "08/05/2017",
    "client": {
      "name": "John",
      "code": "100"
    },
    "items": [
        {
          "name": "Product A",
          "description": "Cleaning product",
          "unit_price": "10.0",
          "quantity": "1.0"
        }
      ]
   }
}

Example Request

Format:
curl --request POST \
  --url 'https://account_name.app.invoicexpress.com/:document-type.json?api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"invoice":{"date":"03/12/2017","due_date":"03/12/2017","client":{"name":"Client Name","code":"A1"},"items":[{"name":"Item Name","description":"Item Description","unit_price":"100","quantity":"5"}]}}'
require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/:document-type.json?api_key=YOUR%20API%20KEY%20HERE")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request.body = "{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\"}]}}"

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "POST",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/:document-type.json?api_key=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "application/json",
    "content-type": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({ invoice: 
   { date: '03/12/2017',
     due_date: '03/12/2017',
     client: 
      { name: 'Client Name',
        code: 'A1'},
     items: 
      [ { name: 'Item Name',
          description: 'Item Description',
          unit_price: '100',
          quantity: '5' } ],
    }}));
req.end();
import http.client

conn = http.client.HTTPSConnection("account_name.app.invoicexpress.com")

payload = "{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\"}]}}"

headers = {
    'accept': "application/json",
    'content-type': "application/json"
    }

conn.request("POST", "/:document-type.json?api_key=YOUR%20API%20KEY%20HERE", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
<?php

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/:document-type.json?api_key=YOUR%20API%20KEY%20HERE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\"}]}}",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://account_name.app.invoicexpress.com/:document-type.json?api_key=YOUR%20API%20KEY%20HERE"

  payload := strings.NewReader("{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\"}]}}")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("accept", "application/json")
  req.Header.Add("content-type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

Path Parameters

Name Type Required Description Example
document-type String Required

The type of document you want to create. For example: invoices, simplified_invoices, invoice_receipts, vat_moss_invoices, credit_notes or debit_notes.

invoices

Request Body

Name Type Required Description Example
invoice Object Required

Invoice data to be created.

{
  "invoice": {
  "invoice": { ... }
Object

Replace invoice with: simplified_invoice, invoice_receipt, credit_note or debit_note depending on the type of document you want to create/update.

    "date": "03/12/2017",
String

[Required] The document date. Must be in format dd/mm/yyyy ex.: 03/12/2017. If format is invalid, date will be set to current date.

    "due_date": "03/12/2017",
String

[Required] The document due date. Must be in format dd/mm/yyyy ex.: 03/12/2017. If format is invalid, date will be set to current date.

    "reference": "999",
String

[Optional] The document purchase order reference field.

    "observations": "Observations",
String

[Optional] Document observations, these will be printed with the invoice.

    "retention": "0",
String

[Optional] Withholding tax percentage (%). Must be a number between 0 and 99.99.

    "tax_exemption": "M01",
String

[Required/Optional] Portuguese IVA exemption code. Required for portuguese accounts on invoices with IVA exempt items (0%). Must be one of the following: M01, M02, M03, M04, M05, M06, M07, M08, M09, M10, M11, M12, M13, M14, M15, M16, M99. See the table IVA Exemption Codes for more details.

    "sequence_id": "12345",
String

[Optional] ID of the sequence you want to use with this document. If missing, the default sequence will be used.

    "manual_sequence_number": "1",
String

[Required/Optional] Required for non-portuguese accounts with manual sequence numbering.

    "client": {
    "client": { ... }
Object

[Required/Optional] Client details. This field is only optional for simplified_invoices. If you issue a simplified_invoice without a client, the simplified_invoice will be issued for the final consumer.

      "name": "Client Name",
String

[Required] The document’s client. If the client doesn’t exist, a new one is created. If it exists, the remaining client fields will be ignored.

      "code": "A1",
String

[Required] The client’s unique code. If the client doesn’t exist, a new one is created. If it exists, the remaining client fields will be ignored.

      "email": "foo@bar.com",
String

[Optional] Client email address. Must be a valid email address ex: foo@bar.com

      "address": "Saldanha",
String

[Optional] Client company address.

      "city": "Lisbon",
String

[Optional] Client’s city.

      "postal_code": "1050-555",
String

[Optional] Client’s postal code for it’s company address.

      "country": "Portugal",
String

[Optional] Country, normally used for a company country. Although country is optional, when supplied, it should match one of the country list on the Appendix of this Documentation.

      "fiscal_id": "508000000",
String

[Optional] Client's fiscal ID (Número de Contribuinte).

      "website": "www.website.com",
String

[Optional] Client' website.

      "phone": "910000000",
String

[Optional] Client's phone number.

      "fax": "210000000",
String

[Optional] Client's fax number.

      "observations": "Observations"
String

[Optional] Client's default observations. This is added to the observations field of all the invoices sent to this client.

    },
    items: [
Array

[Required] An array of line items. If items with the given names do not exist, they are created. If an item already exists, it is updated with the new values. At least one is required.

      {
      { ... }
Object

Item Object

        "name": "Item Name",
String

[Required] Name of the item. Must be unique.

        "description": "Item Description",
String

[Required] Item’s description.

        "unit_price": "100",
String

[Required] Item’s unit price. Must be a number equal or greater than 0.0.

        "quantity": "5",
String

[Required] Quantity. Must be a number equal or greater than 0.

        "unit": "service",
String

[Optional] The unit of measure. Ex: hour, day, month, unit , service or other.

        "discount": "50",
String

[Optional] The item discount percentage (%). Defaults to 0.0. Must be a value between 0.0 and 100.0 inclusive.

        "tax": {
        "tax": { ... }
Object

[Optional] The tax applied to the line item. If not present the default tax is applied to the line item.

          "name": "IVA23"
String

[Optional] The tax name to be used on this line item. If not found the default tax is applied to the line item.

        }
      }
    ]
    "mb_reference": "0",
String

[Optional] Generates a Multibanco Reference after you finalize your invoice. This option is only available for invoices, simplified_invoices and invoice_receipts for Portuguese Accounts. You must have the feature enabled on your account first. Set value to "1" to generate an mb_reference.

    "owner_invoice_id": "12345",
String

[Optional] The (owner) invoice associated to this document. This option is only available for credit_notes or debit_notes. You can also send the (owner) guide id when creating an invoice to associate an invoice to a guide.

    "tax_exemption_reason": "M00",
String

[Optional] Used when updating a document and removing all tax exempt items. The code M00 means 'Without tax exemption'.

    "currency_code": "USD",
String

[Optional] If your plan has multicurrency, you can issue invoices in another currency than your accounts default currency. The currency_code should be one of the following ISO 4217 Currency Codes.

    "rate": "1.23565"
String

[Optional] When sending a currency_code, you can specify its rate.

  }
}

Responses

201 Success

Invoice was created successfully.

Invoices Get
{
  "invoice": {
  "invoice": { ... }
Object
    "id": 2137287,
Integer
    "status": "final",
String
    "archived": false,
Boolean
    "type": "Invoice",
String
    "sequence_number": "6/G",
String
    "inverted_sequence_number": "G/6",
String
    "sequence_id": "12345",
String
    "tax_exemption": "M01",
String
    "date": "04/08/2016",
String
    "due_date": "19/08/2016",
String
    "reference": "foo",
String
    "observations": "foo",
String
    "retention": "foo",
String
    "permalink": "https://www.app.invoicexpress.com/documents/213728738ca780a8de4330cad4a5a556360304bd9c57011",
String
    "saft_hash": "J4ay",
String
    "sum": 24.39,
Number
    "discount": 0,
Integer
    "before_taxes": 24.39,
Number
    "taxes": 5.61,
Number
    "total": 30,
Integer
    "currency": "Euro",
String
    "client": {
    "client": { ... }
Object
      "id": 628535,
Integer
      "name": "John",
String
      "country": "Portugal"
String
    },
    items: [
Array
      {
      { ... }
Object

Items

        "name": "Large",
String
        "description": "foo",
String
        "unit_price": "24.3902",
String
        "unit": "foo",
String
        "quantity": "1.0",
String
        "tax": {
        "tax": { ... }
Object
          "id": 69166,
Integer
          "name": "IVA23",
String
          "value": 23
Integer
        },
        "discount": 0,
Integer
        "subtotal": 24.39,
Number
        "tax_amount": 5.61,
Number
        "discount_amount": 0,
Integer
        "total": 30
Integer
      }
    ]
    "mb_reference": {
    "mb_reference": { ... }
Object
      "entity": "10611",
String
      "value": 30,
Integer
      "reference": "952000823"
String
    }
  }
}
401 Access denied

The API Key parameter is missing or is incorrectly entered.

(Empty Response)
422 Unprocessable Entity

Some parameters were incorrect.

(Empty Response)

Update

PUT /:document-type/:document-id.json

Updates an invoice, simplified_invoice, invoice_receipt, credit_note or debit_note.

Creating new clients or items along with the invoice

This method also allows to create a new client and/or new items in the same request with the following behavior:

  • If the client name does not exist a new one is created.
  • If items do not exist with the given names, new ones will be created.
  • If item name already exists, the item is updated with the new values.

Taxes

Regarding item taxes, if the tax name is not found, no tax will be applied to that item.
Be careful when updating the document items, any missing items from the original document will be deleted.

Example Body

{
  "invoice": {
    "date": "07/05/2017",
    "due_date": "08/05/2017",
    "client": {
      "name": "John",
      "code": "100"
    },
    "items": [
        {
          "name": "Product A",
          "description": "Cleaning product",
          "unit_price": "10.0",
          "quantity": "1.0"
        }
      ]
   }
}

Example Request

Format:
curl --request PUT \
  --url 'https://account_name.app.invoicexpress.com/:document-type/:document-id.json?document-type=invoices&document-id=1&api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"invoice":{"date":"03/12/2017","due_date":"03/12/2017","reference":"999","observations":"Observations","retention":"0","tax_exemption":"M01","sequence_id":"12345","manual_sequence_number":"1","client":{"name":"Client Name","code":"A1","email":"foo@bar.com","address":"Saldanha","city":"Lisbon","postal_code":"1050-555","country":"Portugal","fiscal_id":"508000000","website":"www.website.com","phone":"910000000","fax":"210000000","observations":"Observations"},"items":[{"name":"Item Name","description":"Item Description","unit_price":"100","quantity":"5","unit":"service","discount":"50","tax":{"name":"IVA23"}}],"mb_reference":"0","owner_invoice_id":"12345","tax_exemption_reason":"M00"}}'
require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/:document-type/:document-id.json?document-type=invoices&document-id=1&api_key=YOUR%20API%20KEY%20HERE")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Put.new(url)
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request.body = "{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"reference\":\"999\",\"observations\":\"Observations\",\"retention\":\"0\",\"tax_exemption\":\"M01\",\"sequence_id\":\"12345\",\"manual_sequence_number\":\"1\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\",\"email\":\"foo@bar.com\",\"address\":\"Saldanha\",\"city\":\"Lisbon\",\"postal_code\":\"1050-555\",\"country\":\"Portugal\",\"fiscal_id\":\"508000000\",\"website\":\"www.website.com\",\"phone\":\"910000000\",\"fax\":\"210000000\",\"observations\":\"Observations\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\",\"unit\":\"service\",\"discount\":\"50\",\"tax\":{\"name\":\"IVA23\"}}],\"mb_reference\":\"0\",\"owner_invoice_id\":\"12345\",\"tax_exemption_reason\":\"M00\"}}"

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "PUT",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/:document-type/:document-id.json?document-type=invoices&document-id=1&api_key=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "application/json",
    "content-type": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({ invoice: 
   { date: '03/12/2017',
     due_date: '03/12/2017',
     reference: '999',
     observations: 'Observations',
     retention: '0',
     tax_exemption: 'M01',
     sequence_id: '12345',
     manual_sequence_number: '1',
     client: 
      { name: 'Client Name',
        code: 'A1',
        email: 'foo@bar.com',
        address: 'Saldanha',
        city: 'Lisbon',
        postal_code: '1050-555',
        country: 'Portugal',
        fiscal_id: '508000000',
        website: 'www.website.com',
        phone: '910000000',
        fax: '210000000',
        observations: 'Observations' },
     items: 
      [ { name: 'Item Name',
          description: 'Item Description',
          unit_price: '100',
          quantity: '5',
          unit: 'service',
          discount: '50',
          tax: { name: 'IVA23' } } ],
     mb_reference: '0',
     owner_invoice_id: '12345',
     tax_exemption_reason: 'M00' } }));
req.end();
import http.client

conn = http.client.HTTPSConnection("account_name.app.invoicexpress.com")

payload = "{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"reference\":\"999\",\"observations\":\"Observations\",\"retention\":\"0\",\"tax_exemption\":\"M01\",\"sequence_id\":\"12345\",\"manual_sequence_number\":\"1\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\",\"email\":\"foo@bar.com\",\"address\":\"Saldanha\",\"city\":\"Lisbon\",\"postal_code\":\"1050-555\",\"country\":\"Portugal\",\"fiscal_id\":\"508000000\",\"website\":\"www.website.com\",\"phone\":\"910000000\",\"fax\":\"210000000\",\"observations\":\"Observations\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\",\"unit\":\"service\",\"discount\":\"50\",\"tax\":{\"name\":\"IVA23\"}}],\"mb_reference\":\"0\",\"owner_invoice_id\":\"12345\",\"tax_exemption_reason\":\"M00\"}}"

headers = {
    'accept': "application/json",
    'content-type': "application/json"
    }

conn.request("PUT", "/:document-type/:document-id.json?document-type=invoices&document-id=1&api_key=YOUR%20API%20KEY%20HERE", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/:document-type/:document-id.json?document-type=invoices&document-id=1&api_key=YOUR%20API%20KEY%20HERE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"reference\":\"999\",\"observations\":\"Observations\",\"retention\":\"0\",\"tax_exemption\":\"M01\",\"sequence_id\":\"12345\",\"manual_sequence_number\":\"1\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\",\"email\":\"foo@bar.com\",\"address\":\"Saldanha\",\"city\":\"Lisbon\",\"postal_code\":\"1050-555\",\"country\":\"Portugal\",\"fiscal_id\":\"508000000\",\"website\":\"www.website.com\",\"phone\":\"910000000\",\"fax\":\"210000000\",\"observations\":\"Observations\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\",\"unit\":\"service\",\"discount\":\"50\",\"tax\":{\"name\":\"IVA23\"}}],\"mb_reference\":\"0\",\"owner_invoice_id\":\"12345\",\"tax_exemption_reason\":\"M00\"}}",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://account_name.app.invoicexpress.com/:document-type/:document-id.json?document-type=invoices&document-id=1&api_key=YOUR%20API%20KEY%20HERE"

	payload := strings.NewReader("{\"invoice\":{\"date\":\"03/12/2017\",\"due_date\":\"03/12/2017\",\"reference\":\"999\",\"observations\":\"Observations\",\"retention\":\"0\",\"tax_exemption\":\"M01\",\"sequence_id\":\"12345\",\"manual_sequence_number\":\"1\",\"client\":{\"name\":\"Client Name\",\"code\":\"A1\",\"email\":\"foo@bar.com\",\"address\":\"Saldanha\",\"city\":\"Lisbon\",\"postal_code\":\"1050-555\",\"country\":\"Portugal\",\"fiscal_id\":\"508000000\",\"website\":\"www.website.com\",\"phone\":\"910000000\",\"fax\":\"210000000\",\"observations\":\"Observations\"},\"items\":[{\"name\":\"Item Name\",\"description\":\"Item Description\",\"unit_price\":\"100\",\"quantity\":\"5\",\"unit\":\"service\",\"discount\":\"50\",\"tax\":{\"name\":\"IVA23\"}}],\"mb_reference\":\"0\",\"owner_invoice_id\":\"12345\",\"tax_exemption_reason\":\"M00\"}}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("accept", "application/json")
	req.Header.Add("content-type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Query Parameters

Name Type Required Description Example
document-type String Required

The type of document you want to update. For example: invoices, simplified_invoices, invoice_receipts, vat_moss_invoices, credit_notes or debit_notes.

invoices
document-id Integer Required

ID of the document to update.

1

Request Body

Name Type Required Description Example
invoice Object Required

Invoice data to be updated.

{
  "invoice": {
  "invoice": { ... }
Object

Replace invoice with: simplified_invoice, invoice_receipt, credit_note or debit_note depending on the type of document you want to create/update.

    "date": "03/12/2017",
String

[Required] The document date. Must be in format dd/mm/yyyy ex.: 03/12/2017. If format is invalid, date will be set to current date.

    "due_date": "03/12/2017",
String

[Required] The document due date. Must be in format dd/mm/yyyy ex.: 03/12/2017. If format is invalid, date will be set to current date.

    "reference": "999",
String

[Optional] The document purchase order reference field.

    "observations": "Observations",
String

[Optional] Document observations, these will be printed with the invoice.

    "retention": "0",
String

[Optional] Withholding tax percentage (%). Must be a number between 0 and 99.99.

    "tax_exemption": "M01",
String

[Required/Optional] Portuguese IVA exemption code. Required for portuguese accounts on invoices with IVA exempt items (0%). Must be one of the following: M01, M02, M03, M04, M05, M06, M07, M08, M09, M10, M11, M12, M13, M14, M15, M16, M99. See the table IVA Exemption Codes for more details.

    "sequence_id": "12345",
String

[Optional] ID of the sequence you want to use with this document. If missing, the default sequence will be used.

    "manual_sequence_number": "1",
String

[Required/Optional] Required for non-portuguese accounts with manual sequence numbering.

    "client": {
    "client": { ... }
Object

[Required/Optional] Client details. This field is only optional for simplified_invoices. If you issue a simplified_invoice without a client, the simplified_invoice will be issued for the final consumer.

      "name": "Client Name",
String

[Required] The document’s client. If the client doesn’t exist, a new one is created. If it exists, the remaining client fields will be ignored.

      "code": "A1",
String

[Required] The client’s unique code. If the client doesn’t exist, a new one is created. If it exists, the remaining client fields will be ignored.

      "email": "foo@bar.com",
String

[Optional] Client email address. Must be a valid email address ex: foo@bar.com

      "address": "Saldanha",
String

[Optional] Client company address.

      "city": "Lisbon",
String

[Optional] Client’s city.

      "postal_code": "1050-555",
String

[Optional] Client’s postal code for it’s company address.

      "country": "Portugal",
String

[Optional] Country, normally used for a company country. Although country is optional, when supplied, it should match one of the country list on the Appendix of this Documentation.

      "fiscal_id": "508000000",
String

[Optional] Client's fiscal ID (Número de Contribuinte).

      "website": "www.website.com",
String

[Optional] Client' website.

      "phone": "910000000",
String

[Optional] Client's phone number.

      "fax": "210000000",
String

[Optional] Client's fax number.

      "observations": "Observations"
String

[Optional] Client's default observations. This is added to the observations field of all the invoices sent to this client.

    },
    items: [
Array

[Required] An array of line items. If items with the given names do not exist, they are created. If an item already exists, it is updated with the new values. At least one is required.

      {
      { ... }
Object

Item Object

        "name": "Item Name",
String

[Required] Name of the item. Must be unique.

        "description": "Item Description",
String

[Required] Item’s description.

        "unit_price": "100",
String

[Required] Item’s unit price. Must be a number equal or greater than 0.0.

        "quantity": "5",
String

[Required] Quantity. Must be a number equal or greater than 0.

        "unit": "service",
String

[Optional] The unit of measure. Ex: hour, day, month, unit , service or other.

        "discount": "50",
String

[Optional] The item discount percentage (%). Defaults to 0.0. Must be a value between 0.0 and 100.0 inclusive.

        "tax": {
        "tax": { ... }
Object

[Optional] The tax applied to the line item. If not present the default tax is applied to the line item.

          "name": "IVA23"
String

[Optional] The tax name to be used on this line item. If not found the default tax is applied to the line item.

        }
      }
    ]
    "mb_reference": "0",
String

[Optional] Generates a Multibanco Reference after you finalize your invoice. This option is only available for invoices, simplified_invoices and invoice_receipts for Portuguese Accounts. You must have the feature enabled on your account first. Set value to "1" to generate an mb_reference.

    "owner_invoice_id": "12345",
String

[Optional] The (owner) invoice associated to this document. This option is only available for credit_notes or debit_notes. You can also send the (owner) guide id when creating an invoice to associate an invoice to a guide.

    "tax_exemption_reason": "M00",
String

[Optional] Used when updating a document and removing all tax exempt items. The code M00 means 'Without tax exemption'.

    "currency_code": "USD",
String

[Optional] If your plan has multicurrency, you can issue invoices in another currency than your accounts default currency. The currency_code should be one of the following ISO 4217 Currency Codes.

    "rate": "1.23565"
String

[Optional] When sending a currency_code, you can specify its rate.

  }
}

Responses

200 Success

Document was updated successfully.

(Empty Response)
401 Access denied

The API Key parameter is missing or is incorrectly entered.

(Empty Response)
404 Not Found

The supplied :document-id doesn’t match any existing document.

(Empty Response)
422 Unprocessable Entity

Some parameters sent were incorrect.

(Empty Response)

Change State

PUT /:document-type/:document-id/change-state.json

Changes the state of an invoice, simplified_invoice, invoice_receipt, credit_note or debit_note.

Possible state transitions:

From To State on Request Body Notes
draft final finalized All documents.
draft settled finalized Only invoice_receipt.
draft deleted deleted All documents.
final canceled canceled All documents.
settled canceled canceled Only invoice_receipt.
final settled settled All documents.
settled final unsettled Only credit_note and debit_note.

Any other transitions will fail.
When cancelling a document you must specify a reason.

Example Body

{
  "invoice": {
    "state": "finalized"
  }
}

Example Request

Format:
curl --request PUT \
  --url 'https://account_name.app.invoicexpress.com/:document-type/:document-id/change-state.json?api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"invoice":{"state":"finalized","message":"Wrong invoice totals."}}'
require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/:document-type/:document-id/change-state.json?api_key=YOUR%20API%20KEY%20HERE")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Put.new(url)
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request.body = "{\"invoice\":{\"state\":\"finalized\",\"message\":\"Wrong invoice totals.\"}}"

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "PUT",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/:document-type/:document-id/change-state.json?api_key=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "application/json",
    "content-type": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({ invoice: { state: 'finalized', message: 'Wrong invoice totals.' } }));
req.end();
import http.client

conn = http.client.HTTPSConnection("account_name.app.invoicexpress.com")

payload = "{\"invoice\":{\"state\":\"finalized\",\"message\":\"Wrong invoice totals.\"}}"

headers = {
    'accept': "application/json",
    'content-type': "application/json"
    }

conn.request("PUT", "/:document-type/:document-id/change-state.json?api_key=YOUR%20API%20KEY%20HERE", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/:document-type/:document-id/change-state.json?api_key=YOUR%20API%20KEY%20HERE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\"invoice\":{\"state\":\"finalized\",\"message\":\"Wrong invoice totals.\"}}",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://account_name.app.invoicexpress.com/:document-type/:document-id/change-state.json?api_key=YOUR%20API%20KEY%20HERE"

	payload := strings.NewReader("{\"invoice\":{\"state\":\"finalized\",\"message\":\"Wrong invoice totals.\"}}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("accept", "application/json")
	req.Header.Add("content-type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Path Parameters

Name Type Required Description Example
document-type String Required

The type of document you wish to change state: invoices, invoice_receipts, simplified_invoices, vat_moss_invoices, credit_notes or debit_notes.

invoices
document-id Integer Required

ID of the document to change state.

42

Request Body

Name Type Required Description Example
invoice Object Required

Document state transition.

{
  "invoice": {
  "invoice": { ... }
Object

Replace invoice with: simplified_invoice, invoice_receipt, credit_note or debit_note depending on the type of document you want to change state.

    "state": "finalized",
String

[Required] The state the document will be in after the call to this endpoint. Options: finalized, deleted, canceled, settled or unsettled.

    "message": "Wrong invoice totals."
String

[Required/Optional] Reason for cancelling the document. Only required when state is canceled.

  }
}

Responses

200 Success

Document changed state successfully.

(Empty Response)
401 Access denied

The API Key parameter is missing or is incorrectly entered.

(Empty Response)
404 Not Found

The supplied :document-id doesn’t match any existing document.

(Empty Response)
422 Unprocessable Entity

Some parameters sent were incorrect.

(Empty Response)

Related Documents

GET /document/:document-id/related_documents.json

Returns all the documents (e.g. receipts, credit_notes or debit_notes) related to an invoice, simplified_invoice, invoice_receipt or vat_moss_invoice.

Example Request

Format:
curl --request GET \
  --url 'https://account_name.app.invoicexpress.com/document/:document-id/related_documents.json?api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json'
require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/document/:document-id/related_documents.json?api_key=YOUR%20API%20KEY%20HERE")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/document/:document-id/related_documents.json?api_key=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
import http.client

conn = http.client.HTTPSConnection("account_name.app.invoicexpress.com")

headers = { 'accept': "application/json" }

conn.request("GET", "/document/:document-id/related_documents.json?api_key=YOUR%20API%20KEY%20HERE", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/document/:document-id/related_documents.json?api_key=YOUR%20API%20KEY%20HERE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://account_name.app.invoicexpress.com/document/:document-id/related_documents.json?api_key=YOUR%20API%20KEY%20HERE"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("accept", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Path Parameters

Name Type Required Description Example
document-id Integer Required

The ID of the invoice, simplified_invoice, invoice_receipt or vat_moss_invoice with related documents.

42

Responses

200 Success

List of related documents returned successfully.

Invoices Related documents
{
  documents: [
Array

List of related documents.

    {
    { ... }
Object

Invoice Object

      "id": 541793,
Integer
      "status": "final",
String
      "archived": true,
Boolean
      "type": "Invoice",
String
      "sequence_number": "28/A",
String
      "inverted_sequence_number": "A/28",
String
      "date": "27/06/2017",
String
      "due_date": "27/06/2017",
String
      "reference": "foo",
String
      "observations": "foo",
String
      "retention": "foo",
String
      "permalink": "https://www.app.invoicexpress.com/documents/541793e1ab2ebd5c06def40c346ffbe0ff2b463eb1c0f0",
String
      "saft_hash": "Tdik",
String
      "sum": 1,
Integer
      "discount": 0,
Integer
      "before_taxes": 1,
Integer
      "taxes": 0.07,
Number
      "total": 1.07,
Number
      "currency": "Euro",
String
      "client": {
      "client": { ... }
Object
        "id": 1310176,
Integer
        "name": "John",
String
        "country": "Portugal"
String
      },
      items: [
Array
        {
        { ... }
Object

Items

          "name": " iPhone ",
String
          "description": "foo",
String
          "unit_price": "1.0",
String
          "unit": "foo",
String
          "quantity": "1.0",
String
          "tax": {
          "tax": { ... }
Object
            "id": 31597,
Integer
            "name": "IVA7",
String
            "value": 7
Integer
          },
          "discount": 0,
Integer
          "subtotal": 1,
Integer
          "tax_amount": 0.07,
Number
          "discount_amount": 0,
Integer
          "total": 1.07
Number
        }
      ]
      "sequence_id": "12345",
String
      "tax_exemption": "M01"
String
    }
  ]
}
401 Access denied

The API Key parameter is missing or is incorrectly entered.

(Empty Response)
404 Not Found

The supplied :document-id doesn’t match any existing document.

(Empty Response)

Generate Payment/Receipt

POST /documents/:document-id/partial_payments.json

Creates a payment which generates a receipt.
This endpoint is only available for invoices, simplified_invoices and vat_moss_invoices.

Example Body

{
  "partial_payment": {
    "payment_mechanism": "TB",
    "note": "Observations",
    "serie": "A",
    "amount": 100,
    "payment_date": "26/10/2017"
  }
}

Example Request

Format:
curl --request POST \
  --url 'https://account_name.app.invoicexpress.com/documents/:document-id/partial_payments.json?api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"partial_payment":{"payment_mechanism":"TB","note":"Observations","serie":"A","amount":100.0,"payment_date":"26/10/2017"}}'
require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/documents/:document-id/partial_payments.json?api_key=YOUR%20API%20KEY%20HERE")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request.body = "{\"partial_payment\":{\"payment_mechanism\":\"TB\",\"note\":\"Observations\",\"serie\":\"A\",\"amount\":100.0,\"payment_date\":\"26/10/2017\"}}"

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "POST",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/documents/:document-id/partial_payments.json?api_key=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "application/json",
    "content-type": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({ partial_payment: 
   { payment_mechanism: 'TB',
     note: 'Observations',
     serie: 'A',
     amount: 100,
     payment_date: '26/10/2017' } }));
req.end();
import http.client

conn = http.client.HTTPSConnection("account_name.app.invoicexpress.com")

payload = "{\"partial_payment\":{\"payment_mechanism\":\"TB\",\"note\":\"Observations\",\"serie\":\"A\",\"amount\":100.0,\"payment_date\":\"26/10/2017\"}}"

headers = {
    'accept': "application/json",
    'content-type': "application/json"
    }

conn.request("POST", "/documents/:document-id/partial_payments.json?api_key=YOUR%20API%20KEY%20HERE", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/documents/:document-id/partial_payments.json?api_key=YOUR%20API%20KEY%20HERE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"partial_payment\":{\"payment_mechanism\":\"TB\",\"note\":\"Observations\",\"serie\":\"A\",\"amount\":100.0,\"payment_date\":\"26/10/2017\"}}",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://account_name.app.invoicexpress.com/documents/:document-id/partial_payments.json?api_key=YOUR%20API%20KEY%20HERE"

	payload := strings.NewReader("{\"partial_payment\":{\"payment_mechanism\":\"TB\",\"note\":\"Observations\",\"serie\":\"A\",\"amount\":100.0,\"payment_date\":\"26/10/2017\"}}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("accept", "application/json")
	req.Header.Add("content-type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Path Parameters

Name Type Required Description Example
document-id Integer Required

The ID of the invoice, simplified_invoice or vat_moss_invoice for which you want to make a payment and generate a receipt.

42

Request Body

Name Type Required Description Example
partial_payment Object Required

Payment data

{
  "partial_payment": {
  "partial_payment": { ... }
Object

Payment data.

    "payment_mechanism": "TB",
String

[Optional] How the payment was made. Check the Appendix for possible values. Defaults to client settings or account settings if defined. Otherwise, defaults to TB.

    "note": "Observations",
String

[Optional] Observations.

    "serie": "A",
String

[Optional] Document serie. It can be obtained with this endpoint. Defaults to the serie of the document passed in the url.

    "amount": 100.0,
Number

[Required] Amount of the partial payment. Must be a value greater or equal to zero.

    "payment_date": "26/10/2017"
String

[Optional] Date of the payment. Defaults to today. Format: dd/mm/yyyy.

  }
}

Responses

200 Success

Payment was made successfully and the receipt was generated.

Invoices Receipt
{
  "receipt": {
  "receipt": { ... }
Object

Receipt generated after payment.

    "id": 541793,
Integer
    "status": "final",
String
    "archived": true,
Boolean
    "type": "Invoice",
String
    "sequence_number": "28/A",
String
    "inverted_sequence_number": "A/28",
String
    "date": "27/06/2017",
String
    "due_date": "27/06/2017",
String
    "reference": "foo",
String
    "observations": "foo",
String
    "retention": "foo",
String
    "permalink": "https://www.app.invoicexpress.com/documents/541793e1ab2ebd5c06def40c346ffbe0ff2b463eb1c0f0",
String
    "saft_hash": "Tdik",
String
    "sum": 1,
Integer
    "discount": 0,
Integer
    "before_taxes": 1,
Integer
    "taxes": 0.07,
Number
    "total": 1.07,
Number
    "currency": "Euro",
String
    "client": {
    "client": { ... }
Object
      "id": 1310176,
Integer
      "name": "John",
String
      "country": "Portugal"
String
    },
    items: [
Array
      {
      { ... }
Object

Items

        "name": " iPhone ",
String
        "description": "foo",
String
        "unit_price": "1.0",
String
        "unit": "foo",
String
        "quantity": "1.0",
String
        "tax": {
        "tax": { ... }
Object
          "id": 31597,
Integer
          "name": "IVA7",
String
          "value": 7
Integer
        },
        "discount": 0,
Integer
        "subtotal": 1,
Integer
        "tax_amount": 0.07,
Number
        "discount_amount": 0,
Integer
        "total": 1.07
Number
      }
    ]
    "sequence_id": "12345",
String
    "tax_exemption": "M01"
String
  }
}
401 Access denied

The API Key parameter is missing or is incorrectly entered.

(Empty Response)
404 Not Found

The supplied :document-id doesn’t match any existing document.

(Empty Response)
422 Unprocessable Entity

Some parameters sent were incorrect.

(Empty Response)

Cancel Payment/Receipt

PUT /receipts/:receipt-id/change-state.json

Cancels a payment and it's associated receipt.

Example Body

{
  "receipt": {
    "state": "canceled",
    "message": "Wrong payment values."
  }
}

Example Request

Format:
curl --request PUT \
  --url 'https://account_name.app.invoicexpress.com/receipts/:receipt-id/change-state.json?api_key=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"receipt":{"state":"canceled","message":"Wrong payment values."}}'
require 'uri'
require 'net/http'

url = URI("https://account_name.app.invoicexpress.com/receipts/:receipt-id/change-state.json?api_key=YOUR%20API%20KEY%20HERE")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Put.new(url)
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request.body = "{\"receipt\":{\"state\":\"canceled\",\"message\":\"Wrong payment values.\"}}"

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "PUT",
  "hostname": "account_name.app.invoicexpress.com",
  "port": null,
  "path": "/receipts/:receipt-id/change-state.json?api_key=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "application/json",
    "content-type": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({ receipt: { state: 'canceled', message: 'Wrong payment values.' } }));
req.end();
import http.client

conn = http.client.HTTPSConnection("account_name.app.invoicexpress.com")

payload = "{\"receipt\":{\"state\":\"canceled\",\"message\":\"Wrong payment values.\"}}"

headers = {
    'accept': "application/json",
    'content-type': "application/json"
    }

conn.request("PUT", "/receipts/:receipt-id/change-state.json?api_key=YOUR%20API%20KEY%20HERE", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://account_name.app.invoicexpress.com/receipts/:receipt-id/change-state.json?api_key=YOUR%20API%20KEY%20HERE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\"receipt\":{\"state\":\"canceled\",\"message\":\"Wrong payment values.\"}}",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://account_name.app.invoicexpress.com/receipts/:receipt-id/change-state.json?api_key=YOUR%20API%20KEY%20HERE"

	payload := strings.NewReader("{\"receipt\":{\"state\":\"canceled\",\"message\":\"Wrong payment values.\"}}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("accept", "application/json")
	req.Header.Add("content-type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Path Parameters

Name Type Required Description Example
receipt-id Integer Required

ID of the receipt to be cancelled.

42

Request Body

Name Type Required Description Example
receipt Object Required

Cancel state with message.

{
  "receipt": {
  "receipt": { ... }
Object

Data to cancel the payment/receipt.

    "state": "canceled",
String

[Required] The state the document will be in after the call to this endpoint. Options: canceled.

    "message": "Wrong payment values."
String

[Required] Reason for cancelling the payment/receipt.

  }
}

Responses

200 Success

Payment/Receipt cancelled successfully.

Invoices Receipt
{
  "receipt": {
  "receipt": { ... }
Object

Receipt generated after payment.

    "id": 541793,
Integer
    "status": "final",
String
    "archived": true,
Boolean
    "type": "Invoice",
String
    "sequence_number": "28/A",
String
    "inverted_sequence_number": "A/28",
String
    "date": "27/06/2017",
String
    "due_date": "27/06/2017",
String
    "reference": "foo",
String
    "observations": "foo",
String
    "retention": "foo",
String
    "permalink": "https://www.app.invoicexpress.com/documents/541793e1ab2ebd5c06def40c346ffbe0ff2b463eb1c0f0",
String
    "saft_hash": "Tdik",
String
    "sum": 1,
Integer
    "discount": 0,
Integer
    "before_taxes": 1,
Integer
    "taxes": 0.07,
Number
    "total": 1.07,
Number
    "currency": "Euro",
String
    "client": {
    "client": { ... }
Object
      "id": 1310176,
Integer
      "name": "John",
String
      "country": "Portugal"
String
    },
    items: [
Array
      {
      { ... }
Object

Items

        "name": " iPhone ",
String
        "description": "foo",
String
        "unit_price": "1.0",
String
        "unit": "foo",
String
        "quantity": "1.0",
String
        "tax": {
        "tax": { ... }
Object
          "id": 31597,
Integer
          "name": "IVA7",
String
          "value": 7
Integer
        },
        "discount": 0,
Integer
        "subtotal": 1,
Integer
        "tax_amount": 0.07,
Number
        "discount_amount": 0,
Integer
        "total": 1.07
Number
      }
    ]
    "sequence_id": "12345",
String
    "tax_exemption": "M01"
String
  }
}
401 Access denied

The API Key parameter is missing or is incorrectly entered.

(Empty Response)
404 Not Found

The supplied :receipt-id doesn’t match any existing receipt.

(Empty Response)
422 Unprocessable Entity

Some parameters sent were incorrect.

(Empty Response)