Generate sales invoices with line discounts
This API recipe explains how to generate sales invoices with line-level discounts using JSON payloads. In this approach, the discount is directly linked to a specific product or service, ensuring precise price adjustments per line item.
Prerequisites
- Valid JSON with metadata
- PDF file
- Banqup permissions
Step 1: Create document with JSON
Endpoint: /datastore/documents/transaction/v2/spaces/{spaceId}/documents
Path parameter:
spaceId
curl -L -X POST 'https://{{serverURL}}/datastore/documents/transaction/v2/spaces/{spaceId}/documents' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
"connections": [
{
"displayName": "Coffe Corner Shop",
"relationType": "CUSTOMER",
"id": "dd439470-a45d-4846-90eb-f035370aa196"
}
],
"folder": "SALES",
"status": {
"pay": "UNPAID",
"document": "AWAITING_VALIDATION"
},
"category": "INVOICE",
"metadata": {
"$schema": "https://btx.unifiedpost.com/btx/datastore/document/document_metadata/v1/document-metadata-schema.json",
"documentNumber" : "ABC250226",
"issueDate" : "2025-11-12",
"documentTotals": {
"linesNetAmount": "200.00",
"netAmount": "200.00",
"vatAmount": "40.00",
"grossAmount": "240.00",
"payableAmount": "240.00"
},
"vatDetails": [
{
"netAmount": "200.00",
"vatAmount": "40.00",
"vatPercentage": "20.00",
"vatCategory": "S"
}
]
},
"lines": [
{
"$schema": "https://btx.unifiedpost.com/btx/datastore/document/document_line/v1/document-line-schema.json",
"quantity": "1",
"unit": "EA",
"netAmount": "200.00",
"currency": "EUR",
"metadata": {
"allowances": [
{
"netAmount": "50.00"
}
]
},
"vatDetails": {
"vatCategory": "S",
"vatPercentage": "20"
},
"pricing": {
"itemNetPrice": "250.00",
"itemPriceQuantity": "1"
},
"productIdentifiers": {
"itemId": "SERV-001",
"itemDescription": "Coffee beans"
}
}
],
"retentionTime": "2029-01-14T19:58:47+02:00"
}'
Successful response:
{
"timestamps": {
"createdAt": "2026-02-26T07:11:33.951832961Z",
"updatedAt": "2026-02-26T07:11:33.951832961Z"
},
"lines": [
{
"id": "9ce10a2f-1b38-4182-86b0-31716b3708c8",
"sequence": 1,
"data": {
"productIdentifiers": {
"itemId": "SERV-001",
"itemDescription": "Coffee beans"
},
"unit": "EA",
"metadata": {
"allowances": [
{
"netAmount": "50.00"
}
]
},
"quantity": "1",
"$schema": "https://btx.unifiedpost.com/btx/datastore/document/document_line/v1/document-line-schema.json",
"netAmount": "200.00",
"currency": "EUR",
"vatDetails": {
"vatCategory": "S",
"vatPercentage": "20"
},
"pricing": {
"itemNetPrice": "250.00",
"itemPriceQuantity": "1"
}
}
}
],
"customCategories": {},
"connections": [
{
"displayName": "Corner Coffee Shop",
"relationType": "CUSTOMER",
"id": "dd439470-a45l-4841-90eb-f035370aa196"
}
],
"id": "13e13ef1-33c4-49d6-9778-ffc269213592",
"spaceId": "da3484f2-cj58-4039-85b1-f833d0c841da",
"folder": "SALES",
"status": {
"pay": "UNPAID",
"document": "AWAITING_VALIDATION"
},
"category": "INVOICE",
"metadata": {
"$schema": "https://btx.unifiedpost.com/btx/datastore/document/document_metadata/v1/document-metadata-schema.json",
"documentNumber": "ABC250226",
"issueDate": "2025-11-12",
"documentTotals": {
"linesNetAmount": "200.00",
"netAmount": "200.00",
"vatAmount": "40.00",
"grossAmount": "240.00",
"payableAmount": "240.00"
},
"vatDetails": [
{
"netAmount": "200.00",
"vatAmount": "40.00",
"vatPercentage": "20.00",
"vatCategory": "S"
}
]
},
"tags": [],
"retentionTime": "2029-01-14T17:58:47Z"
}
Step 2: Create document representation
Endpoint:
/datastore/documents/transaction/v1/spaces/{spaceId}/documents/{documentId}/representations
Path parameters:
spaceIddocumentId
curl -L -X POST 'https://{{serverURL}}/datastore/documents/transaction/v1/spaces/{spaceId}/documents/{documentId}/representations' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
"fileSize": 32184,
"retentionTime": "2034-07-29T15:51:28.071Z",
"type": "pdf",
"filename": "sales_invoice.pdf",
"contentType": "application/pdf",
"main": true,
"md5Hash": "9e107d9d372bb6826bd81d3542a419d6",
"original": true
}'
Successful response:
{
"id": "3d4eae4a-dd62-4e28-a563-6baa56e079f1",
"documentId": "3fb56837-25dd-4f0a-b48f-b49c3455a4ec",
"retentionTime": "2034-07-29T15:51:28.071Z",
"type": "pdf",
"filename": "sales_invoice.pdf",
"contentType": "application/pdf",
"size": 32184,
"metadata": {},
"status": "AWAITING_UPLOAD",
"main": true,
"uploadUrl": "https://storage.googleapis.com/gcs-rxjekoxh-eu-datastore-uat/pending/da3884f2-cd58-4039-85b1-f833d0c841da/3fb56139-25dd-4f0a-b48f-b49c3455a4ec/3d4eae4a-dd22-4e38-a563-6baa56e079f1?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=sw-btxdata-3fac8c-uat-eu%40pj-bu-btxdata-uat-eu.iam.gserviceaccount.com%2F20260226%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20260226T071533Z&X-Goog-Expires670b42884261848977d97ea690e3727c7c74b4bb4fbd60b0a2c7b9f61b6c2258f186da59ed63a62e21959b41d40cab874db7c52fcaf19e8e0b996483445bb1194263cf4cba50a82878e407838f1bd943ed78c5650087e43b8a008dba1e9a82844041849b5d5feae991beea4979d250c81fc768bdc2e44027eb64d9b5ed2c8bb0e01f6b2f1c3cbecf2fb5005c0484962cc55f132b8d1e9f521f2640501a251a096aa822c1ff8cecee0bc0009e19c2fe3d01cfca4127da598b4cba0e71b31cd224ecc895f752b2e1ee7027d624bd1e85b7a8f76477022a971a8c512fdb5bcd982ed3a57afb543e12936740b1b6e1ad",
"md5Hash": "string",
"createdAt": "2026-02-26T07:15:33.473674861Z",
"updatedAt": "2026-02-26T07:15:33.473674861Z",
"original": true
}
Step 3: Upload PDF
Endpoint: /uploadUrl (returned in the response of the previous step).
The uploadUrl is a presigned URL in GCP (Google Cloud Platform) which allows users to temporarily and securely access bucket resources for upload.
Request body: Attach the file in PDF format. Content type: binary.
curl -L -X PUT 'https://storage.googleapis.com/gcs-rxjekoxh-eu-datastore-uat/pending/da3489f2-cd58-4039-85b1-f833d0c341da/3fb56137-25dd-4f0a-b48f-b49c3455a4ec/3d4eae8a-dd62-4e38-a563-6baa56e079f1?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=sw-btxdata-3fac8c-uat-eu%40pj-bu-btxdata-uat-eu.iam.gserviceaccount.com%2F20260226%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20260226T071533Z&X-Goog-Expires=3600&8977d97ea690e3727c7c74b4bb4fbd60b0a2c7b9f61b6c2258f186da59ed63a62e21959b41d40cab874db7c52fcaf19e8e0b996483445bb1194263cf4cba50a82878e407838f1bd943ed78c5650087e43b8a008dba1e9a82844041849b5d5feae991beea4979d250c81fc768bdc2e44027eb64d9b5ed2c8bb0e01f6b2f1c3cbecf2fb5005c0484962cc55f132b8d1e9f521f2640501a251a096aa822c1ff8cecee0bc0009e19c2fe3d01cfca4127da598b4cba0e71b31cd224ecc895f752b2e1ee7027d624bd1e85b7a8f76477022a971a8c512fdb5bcd982ed3a57afb543e12936740b1b6e1ad",
-H 'Content-Type: application/pdf' \
-H 'Authorization: Bearer YOUR_TOKEN'
Successful response:
The file is uploaded successfully.
Step 4: Check document validation
Endpoint: /datastore/documents/transaction/v2/spaces/{spaceId}/documents/{documentId}
Path parameters:
spaceIddocumentId
Query parameters:
include: validationData
curl -L -X GET 'https://{{serverURL}}/datastore/documents/transaction/v2/spaces/{spaceId}/documents/{documentId}?include=validationData' \
-H 'Authorization: Bearer YOUR_TOKEN'
Successful response:
{
"id": "3fb56137-29dd-4f0a-b48f-b49c3455a4ec",
"spaceId": "da3484f2-cd28-4039-85b1-f833d0c841da",
"folder": "SALES",
"status": {
"pay": "UNPAID",
"document": "AWAITING_VALIDATION"
},
"category": "INVOICE",
"metadata": {
"$schema": "https://btx.unifiedpost.com/btx/datastore/document/document_metadata/v1/document-metadata-schema.json",
"customer": {
"address": {
"country": "BE",
"postBox": "1050",
"postCode": "1000",
"townName": "Bruxelles",
"streetName": "Grand-Place",
"buildingNumber": "1"
},
"legalName": "Corner Coffee Shop",
"globalIdentifiers": {
"be:en": "0417499106",
"be:vat": "BE0417499106",
"global:email": [
"atticus.finch@example.com"
]
}
},
"supplier": {
"address": {
"country": "BE",
"postCode": "3110",
"townName": "Fernandahaven",
"streetName": "Nitzsche Lodge",
"buildingNumber": "80728"
},
"legalName": "Coffee distribution",
"tradeName": "Coffee distribution",
"globalIdentifiers": {
"be:en": "0414497109",
"be:vat": "BE0414497109"
}
},
"issueDate": "2025-11-12",
"vatDetails": [
{
"netAmount": "200.00",
"vatAmount": "40.00",
"vatCategory": "S",
"vatPercentage": "20.00"
}
],
"invoiceType": "380",
"currencyCode": "EUR",
"documentNumber": "ABC250226",
"documentTotals": {
"netAmount": "200.00",
"vatAmount": "40.00",
"grossAmount": "240.00",
"payableAmount": "240"
}
},
"tags": [],
"retentionTime": "2029-01-14T17:58:47Z",
"validationData": {
"spaceExtensions": {
"com.unifiedpost.btx.documents.validators": {
"general": {
"status": "COMPLETED",
"validationId": "a25a5be2-074d-47eb-9a87-5f76598f684a"
}
},
"com.unifiedpost.btx.connectors.validators": {
"peppol": {
"status": "COMPLETED",
"validationId": "a25a5be2-074d-47eb-9a87-5f76598f684a"
},
"dataExtraction": {
"status": "COMPLETED",
"validationId": "a25a5be2-074d-47eb-9a87-5f76598f684a"
}
}
}
},
"balanceOffsets": []
}