Return items of a sale receipt
This tutorial demonstrates how to handle item returns.
You''ll learn how to
- Issue a return receipt for specific items of a sale receipt issued by the same Point of Sale or a different one
- Issue a return receipt associated to a sale receipt that hasn't been issued by a Point of Sale.
Case 1: Sale receipt issued by a Point of Sale
Prerequisites
Receipts can be issued only by a merchant or a cashier with a valid certificate (PEM file).
Since our goal is to return items of a sale receipt, we will issue one from a cash register associated to the Point of Sale E001-000001
:
import requests
CERT_PATH = '/var/certs/pos/E001-000001/cashregister.pem'
KEY_PATH = '/var/certs/pos/E001-000001/cashregister.pem'
response = requests.post(
'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipt',
cert=(CERT_PATH, KEY_PATH),
json={
"electronic_payment_amount": "244",
"items": [
{
"good_or_service": "B",
"quantity": "1",
"description": "Product A",
"unit_price": "100",
"vat_rate_code": "22"
},
{
"good_or_service": "B",
"quantity": "1",
"description": "Product B",
"unit_price": "100",
"vat_rate_code": "22"
}
]
}
)
const fs = require('fs');
const https = require('https');
const CERT = fs.readFileSync('/var/certs/pos/E001-000001/cashregister.pem')
const KEY = fs.readFileSync('/var/certs/pos/E001-000001/cashregister.pem')
const req = https.request(
{
hostname: 'ereceipts-it-sandbox.acubeapi.com',
headers: {
"Content-Type": "application/json"
},
port: 444,
path: '/mf1/receipt',
method: 'POST',
cert: CERT,
key: KEY
},
res => {
let body = '';
res.on('data', function(data) {
body += data;
});
res.on('end', function() {
console.log(body);
})
}
);
req.write(JSON.stringify({
"items": [
{
"good_or_service": "B",
"quantity": "1",
"description": "Product A",
"unit_price": "100",
"vat_rate_code": "22"
},
{
"good_or_service": "B",
"quantity": "1",
"description": "Product B",
"unit_price": "100",
"vat_rate_code": "22"
}
]
}));
req.end();
curl -X POST https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipt \
-H 'Content-Type: application/json' \
-d '{"electronic_payment_amount":"244","items":[{"good_or_service":"B","quantity":"1","description":"Product A","unit_price":"100","vat_rate_code":"22"},{"good_or_service":"S","quantity":"1","description":"Product B","unit_price":"100","vat_rate_code":"22"}]}' \
--cert /var/certs/pos/E001-000001/cashregister.pem \
--key /var/certs/pos/E001-000001/cashregister.pem
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipt');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode('{
"electronic_payment_amount": "244",
"items": [
{
"good_or_service": "B",
"quantity": "1",
"description": "Product A",
"unit_price": "100",
"vat_rate_code": "22"
},
{
"good_or_service": "B",
"quantity": "1",
"description": "Product B",
"unit_price": "100",
"vat_rate_code": "22"
}
]
}'));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type:application/json']);
curl_setopt($ch, CURLOPT_SSLCERT, '/var/certs/pos/E001-000001/cashregister.pem');
curl_setopt($ch, CURLOPT_SSLKEY, '/var/certs/pos/E001-000001/cashregister.pem');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);
You will receive the following response:
Response 201
{
"uuid": "18a681da-a868-47ba-a931-2f702474c3d1",
"type": "sale",
"total_amount": "244",
"document_number": "0001-0001",
"document_datetime": "2025-09-01T10:00:00",
"parent_receipt_uuid": null
}
Issue the return receipt
Supposing you are working from a cash register associated to the Point of Sale E001-000002
and you need to return the item Product B
of the sale receipt above, you'd need to make the following HTTP request:
import requests
CERT_PATH = '/var/certs/pos/E001-000002/cashregister.pem'
KEY_PATH = '/var/certs/pos/E001-000002/cashregister.pem'
response = requests.post(
'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipt/return',
cert=(CERT_PATH, KEY_PATH),
json={
"pem_id": "E001-0001",
"document_number": "0001-0001",
"items": [
{
"good_or_service": "B",
"quantity": "1",
"description": "Product B",
"unit_price": "100",
"vat_rate_code": "22"
}
]
}
)
const fs = require('fs');
const https = require('https');
const CERT = fs.readFileSync('/var/certs/pos/E001-000002/cashregister.pem')
const KEY = fs.readFileSync('/var/certs/pos/E001-000002/cashregister.pem')
const req = https.request(
{
hostname: 'ereceipts-it-sandbox.acubeapi.com',
headers: {
"Content-Type": "application/json"
},
port: 444,
path: '/mf1/receipt/return',
method: 'POST',
cert: CERT,
key: KEY
},
res => {
let body = '';
res.on('data', function(data) {
body += data;
});
res.on('end', function() {
console.log(body);
})
}
);
req.write(JSON.stringify( {
"document_number": "0001-0001",
"items": [
{
"good_or_service": "B",
"quantity": "1",
"description": "Product B",
"unit_price": "100",
"vat_rate_code": "22"
}
]
}));
req.end();
curl -X POST https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipt/return \
-H 'Content-Type: application/json' \
-d '{"document_number":"0001-0001","items":[{"good_or_service":"B","quantity":"1","description":"Product B","unit_price":"100","vat_rate_code":"22"}]}' \
--cert /var/certs/pos/E001-000002/cashregister.pem \
--key /var/certs/pos/E001-000002/cashregister.pem
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipt/return');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode('{
"document_number": "0001-0001",
"items": [
{
"good_or_service": "B",
"quantity": "1",
"description": "Product B",
"unit_price": "100",
"vat_rate_code": "22"
}
]
}'));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type:application/json']);
curl_setopt($ch, CURLOPT_SSLCERT, '/var/certs/pos/E001-000002/cashregister.pem');
curl_setopt($ch, CURLOPT_SSLKEY, '/var/certs/pos/E001-000002/cashregister.pem');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);
The response will be:
Response 201
{
"uuid": "25a34bea-3418-17ba-ac31-2f704474abb3",
"type": "return",
"total_amount": "122",
"document_number": "0001-0002",
"document_datetime": "2025-09-01T11:00:00",
"parent_receipt_uuid": "18a681da-a868-47ba-a931-2f702474c3d1"
}
info
If the return receipt is issued by the same Point of Sale that issued the sale receipt, you can avoid to specify the pem_id
in the request. If you specify it, the request will still be processed correctly as long as the cash register from which you are working is associated to the specified Point of Sale.
Case 2: Sale receipt not issued by a Point of Sale
It might be that the sale receipt has not been issued by a Point of Sale, so it is not possible to specify a document_number
.
In this case you should make a POST
request to /mf1/receipts/return-with-proof
:
import requests
CERT_PATH = '/var/certs/pos/E001-000001/cashregister.pem'
KEY_PATH = '/var/certs/pos/E001-000001/cashregister.pem'
response = requests.post(
'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipt/return-with-proof',
cert=(CERT_PATH, KEY_PATH),
json= {
"proof": "POS",
"document_datetime": "2025-09-01T10:00:00",
"items":
[
{
"good_or_service": "B",
"quantity": "1",
"description": "Product B",
"unit_price": "100",
"vat_rate_code": "22"
}
]
}
)
const fs = require('fs');
const https = require('https');
const CERT = fs.readFileSync('/var/certs/pos/E001-000001/cashregister.pem')
const KEY = fs.readFileSync('/var/certs/pos/E001-000001/cashregister.pem')
const req = https.request(
{
hostname: 'ereceipts-it-sandbox.acubeapi.com',
headers: {
"Content-Type": "application/json"
},
port: 444,
path: '/mf1/receipt/return-with-proof',
method: 'POST',
cert: CERT,
key: KEY
},
res => {
let body = '';
res.on('data', function(data) {
body += data;
});
res.on('end', function() {
console.log(body);
})
}
);
req.write(JSON.stringify( {
"proof": "POS",
"document_datetime": "2025-09-01T10:00:00",
"items":
[
{
"good_or_service": "B",
"quantity": "1",
"description": "Product B",
"unit_price": "100",
"vat_rate_code": "22"
}
]
}));
req.end();
curl -X POST https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipt/return-with-proof \
-H 'Content-Type: application/json' \
-d '{"proof":"POS","document_datetime":"2025-09-01T10:00:00","items":[{"good_or_service":"B","quantity":"1","description":"Product B","unit_price":"100","vat_rate_code":"22"}]}' \
--cert /var/certs/pos/E001-000001/cashregister.pem \
--key /var/certs/pos/E001-000001/cashregister.pem
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipt/return-with-proof');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode('{
"proof": "POS",
"document_datetime": "2025-09-01T10:00:00",
"items":
[
{
"good_or_service": "B",
"quantity": "1",
"description": "Product B",
"unit_price": "100",
"vat_rate_code": "22"
}
]
}'));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type:application/json']);
curl_setopt($ch, CURLOPT_SSLCERT, '/var/certs/pos/E001-000001/cashregister.pem');
curl_setopt($ch, CURLOPT_SSLKEY, '/var/certs/pos/E001-000001/cashregister.pem');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);
info
This endpoint requires you to specify time and date of the sale receipt for which you are returning items.
info
the field proof
can be set to one of "POS", "VR" (vuoti a rendere), or "ND" (non definito). "POS" in this case refers to a payment processing device, not the Point of Sale entity referred to in this documentation.