Top-Up API

1. Introduction

This document explains the process of using the Top-Up service in the HORISEN SMS Platform application. It provides detailed instructions of how to retrieve needed data before initiating a top-up request, creating a top-up, as well as described in details the APIs endpoints methods associated with the Top-Up feature.

The HORISEN Top-Up API is a standard REST HTTP API with JSON payload. The SMS Platform API authorization is implemented as the industry-standard OAuth 2.0 protocol. For more information, please refer to the OAuth2 Authentication Guidelines page.

1.1 API Call Examples

The following steps explains the process of retrieving needed data for initiating a top-up process, as well as creating clearing records and top-up invoices.

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

More details about the APIs endpoints methods can be found in 2. Methods Overview section of this document.

1. To start a top-up process, creditRecordType with codeName=TOP-UP is required for further API calls. The following example cURL API call retrieves details of Credit Record Types available in the system:

curl 'https://api{separator}{platform_domain}/bulk/billing/v2/credit-record-types?sort=name' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

An example of a response is given below:

{
    "data": [
        {
            "id": 1,
            "typeUid": "string",
            "codeName": "TOP-UP",
            "name": "Prepaid Top Up",
            "billingTypeId": 1,
            "createInvoice": "yes",
            "status": "active",
            "statusDt": "2021-12-28T14:18:59+01:00",
            "comment": ""
        },
        {
            "id": 2,
            "typeUid": "string",
            "codeName": "TEST-CREDIT",
            "name": "Prepaid Test Credit",
            "billingTypeId": 1,
            "createInvoice": "no",
            "status": "active",
            "statusDt": "2021-12-28T14:18:59+01:00",
            "comment": ""
        },
        {
            "id": 3,
            "typeUid": "string",
            "codeName": "PART-PAYMENT",
            "name": "Postpaid Part Payment",
            "billingTypeId": 2,
            "createInvoice": "yes",
            "status": "active",
            "statusDt": "2021-12-28T14:18:59+01:00",
            "comment": ""
        }
    ],
    "meta": {
        "pagination": {
            "total": 3,
            "totalPages": 1,
            "currentPage": 1,
            "perPage": 3,
            "count": 3
        }
    }
}

2. The next API call returns all Business Partners associated with the product:

curl 'https://api{separator}{platform_domain}/biz-core/v1/product-type-partners-lov?productCodeName=BULK-SMS&productTypeCodeName=BULK-SMS&relationTypeCodeName=CUSTOMER&sort=briefName&status=active' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Where productTypeCodeName=BULK-SMS indicates that 'BULK_SMS' is a product type.
relationTypeCodeName=CUSTOMER is used because the process will create a Customer Invoice.
status=active is used in order to retrieve all active Business Partners.

3. The following cURL call retrieves all valid prepaid total balances associated with the selected Business Partner.

curl 'https://api{separator}{platform_domain}/bulk/billing/v2/valid-prepaid-total-balances?bizPartnerId=BIZ_PARTNER_ID&status=active&page_number=1&page_size=10000&sort=name' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Where bizPartnerId=BIZ_PARTNER_ID is the ID of the selected Business Partner.

4. For the selected Invoice Conditions (Total Balance), the next API call will retrieve Platform Owner Bank Accounts for the selected currency=CURRENCY_ID, which is retrieved from the previously selected Invoice Conditions:

curl 'https://api{separator}{platform_domain}/settings/v1/platform-owner-bank-accounts?all=yes&coOwnerId=0&currency=CURRENCY_ID&sort=name' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

5. The next API call creates a Credit Record and a Top-Up invoice with the given data for amount as the top-up total amount and creditAmount as allowed amount for the top-up:

curl 'https://api{separator}{platform_domain}/bulk/billing/v2/credit-record-invoices' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  --data-raw '{"balanceId": BALANCE_ID,"amount": 1500,"comment":"Test comment","payment":{"fullyPaid": true,"paymentType": 4,"bankAccountId": 0}}'

An example of a payload is given below:

{
  "balanceId": 83,
  "amount": 1500,
  "comment": "Test comment",
  "payment": {
    "fullyPaid": true,
    "paymentType": 4,
    "bankAccountId": 0
  }
}

and the response example would be:

{
    "id": 742,
    "creditUid": "e10963bf-40d5-b711-8085-f6da1dda261a",
    "balanceId": 83,
    "activationDate": "2024-04-25",
    "amount": 1500,
    "creditAmount": 1500,
    "paidAmount": 1500,
    "conditionalAmount": 0,
    "unpaidAmount": 0,
    "currency": 756,
    "description": "",
    "status": "active",
    "isAggregateRecord": "no",
    "aggregateFromDate": "0001-01-01",
    "comment": "Test comment",
    "invoiceId": 2860,
    "creationDate": "2024-04-25",
    "typeId": 1,
    "billingRecordId": 0,
    "orderingStatus": "off",
    "orderingStatusDt": "2024-04-25T13:23:15+02:00",
    "selectedPriceListId": 0,
    "ownerId": 0,
    "ownerBpName": "",
    "ownerBpBriefName": "",
    "currencyCode": "CHF",
    "currencyName": "Swiss Franc",
    "balanceName": "Test PetPrepaid",
    "bizPartnerId": 3000043,
    "bizPartnerName": "Test Partner",
    "bizPartnerShortName": "Test Partner",
    "billingType": 1,
    "type": "TOP-UP",
    "typeName": "Prepaid Top Up",
    "createInvoice": "yes",
    "invoice": {
        "id": 2860,
        "instanceID": 3000003,
        "custID": 3000043,
        "custName": "Mike T",
        "custAttn": "Mike test",
        "custAddress": "Test address",
        "custAddress2": "",
        "custPost": "11000",
        "custCity": "Belgrade",
        "custVatNumber": "123",
        "custShortName": "Mike",
        "custCountry": 756,
        "custPOBox": "",
        "invType": 1,
        "invTypeName": "Bulk Invoice - Prepaid Topup",
        "selfBilling": "no",
        "templateID": 1,
        "invDate": "2024-04-25",
        "invNumberFix": "250424-%d",
        "invNumberNum": 3,
        "invNumber": "250424-3",
        "invPeriod": "",
        "invDueDate": "2024-04-25",
        "overDueDate": 0,
        "ownerVatNumber": "12",
        "currency": 756,
        "currencyCode": "CHF",
        "amountNoVat": 1500,
        "amountVat": 1500,
        "vatPercent": 0,
        "rounding": 0,
        "total": 1500,
        "totalUnpaid": 0,
        "totalPaid": 1500,
        "vatInPrice": 0,
        "vatInTotal": 0,
        "status": "approved",
        "insertDt": "2024-04-25T11:23:15Z",
        "statusDt": "2024-04-25T11:23:15Z",
        "deliveryDate": "2024-04-25",
        "invPeriodStart": null,
        "invPeriodEnd": null,
        "docsDeliveryStatus": "none",
        "docsDeliveryStatusDate": null,
        "docsDeliveryDlrStatus": "none",
        "docsDeliveryDlrStatusDate": null,
        "classCodeName": "CUSTOMER_INVOICE",
        "classDomain": "invoice",
        "classArea": "sales",
        "lang": "en",
        "paymentStatus": "closed",
        "paymentStatusDate": "2024-04-25T11:23:15Z",
        "disputeStatus": "none",
        "disputeStatusDate": null,
        "nettingInvoiceId": 0,
        "nettingInvoiceNumber": "",
        "dataSourceId": 1,
        "dataSourceCodeName": "PREPAID",
        "domainId": 1,
        "domainCodeName": "BULK",
        "disputeNextId": 0,
        "collectionMode": "none",
        "collectionLeadId": 0,
        "processingStatus": "none",
        "dtsSelectorId": 0,
        "dtsSelectorCodeName": "",
        "ownerId": 0,
        "domesticCurrency": 0,
        "domesticCurrencyCode": "",
        "ownerName": "OwnerNameExample",
        "ownerBpName": "",
        "ownerBpBriefName": "",
        "customerType": "",
        "industryName": "",
        "domainName": "Bulk SMS",
        "domesticCurrencyAmountNoVAT": 0,
        "domesticCurrencyAmountVAT": 0,
        "domesticCurrencyTotal": 0,
        "collectionLeadNumber": "",
        "collectionLeadNettingInvoiceId": 0,
        "billingBalance": {
            "id": 83,
            "name": "Test PetPrepaid",
            "resourceUrl": "https://api{separator}{platform_domain}/bulk/billing/v2/total-balances/83"
        },
        "items": [
            {
                "id": 17945,
                "invoiceId": 2860,
                "ordNum": 1,
                "name": "{\"1\": \"Prepaid Bulk SMS Credit\", \"2\" : \"Test PetPrepaid\"}",
                "itemType": "ITEM-2",
                "quantity": 0,
                "quantityMore": 1,
                "quantityMode": 0,
                "measureUnit": 1,
                "price": 0,
                "vatInPrice": 0,
                "totalNoVat": 1500,
                "totalVat": 1500,
                "status": "active",
                "insertDt": "2024-04-25T11:23:15Z",
                "statusDt": "2024-04-25T11:23:15Z",
                "dataSourceId": 0,
                "dataSourceForeignKey": 0,
                "dtsSelectorId": 0,
                "dtsSelectorCodeName": ""
            }
        ]
    }
}

Where balanceId and currency are data retrieved from the selected Total Balance from the previous step.

This invoice is newly created Customer Prepaid Invoice with status approved. It can be retrieved by calling the following endpoint with specified INVOICE_ID:

curl 'https://api{separator}{platform_domain}/finance/sit/v1/invoices/INVOICE_ID' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

6. The following cURL call lists all invoices within the specific date range with status 'approved':

curl 'https://api{separator}{platform_domain}/finance/sit/v1/invoices?between(invDate)=2024-01-01%2C2024-12-31&classCodeName=CUSTOMER_INVOICE&in(disputeStatus)=closed%2Cnone&lang=en&page_number=1&page_size=10&sort=-invDate%2C-id&status=approved' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

7. To view payment history data for INVOICE_ID, the following API call can be used:

curl 'https://api{separator}{platform_domain}/finance/sit/v1/invoices/INVOICE_ID/clearingrecords?status=active&page_number=1&page_size=1000' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

An example of a response is given below:

{
    "data": [
        {
            "id": 2544,
            "clearingId": 1276,
            "clearingTypeId": 1,
            "clearingTypeCodeName": "INVOICE",
            "recordDate": "2024-04-19",
            "paymentTypeId": 0,
            "paymentTypeName": "",
            "amountIncrement": 200,
            "paidAmount": 0,
            "paymentReference": "",
            "comment": "Invoice: 190424-3",
            "status": "active",
            "statusDate": "2024-04-19T11:54:22Z",
            "bankAccountId": 0,
            "bankAccountName": "",
            "bankAccountNumber": "",
            "bankAccountIban": "",
            "bankAccountSwiftBic": ""
        }
    ],
    "meta": {
        "pagination": {
            "total": 1,
            "totalPages": 1,
            "currentPage": 1,
            "perPage": 1000,
            "count": 1
        }
    }
}

8. To add a Payment for the invoice with id=INVOICE_ID, the following API call can be made:

curl 'https://api{separator}{platform_domain}/finance/sit/v1/invoices/INVOICE_ID/clearingrecords?status=active&page_number=1&page_size=1000' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  --data-raw '{"clearingTypeId":2,"recordDate":"2024-04-22","paymentTypeId":1,"bankAccountId":BANK_ACCOUNT_ID,"paidAmount":100}'

where "clearingTypeId":2 is for payment, "paymentTypeId":1 is for 'Bank Account' selected type, "bankAccountId":BANK_ACCOUNT_ID is Platform Owner Bank Account ID retrieved in the previous API call.

9. The example of the API call for listing all clearing records for the invoice with INVOICE_ID, is given below:

curl 'https://api{separator}{platform_domain}/finance/sit/v1/invoices/INVOICE_ID/clearingrecords?status=active&page_number=1&page_size=1000' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

2. Methods Overview

2.1 Invoices

These endpoints allow retrieving a list of payable invoices and top-up invoices.

The API endpoints belong to the Finance domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/finance/sit/v1

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

GET/payable-invoices
Returns a list of all payable invoices.Read More
GET/topup-invoices
Returns a list of top-up invoices.Read More

The following endpoint is used for a top-up or part payment invoice creation.

The API endpoint belongs to the Bulk Billing domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/bulk/billing/v2
POST/credit-record-invoices
Creates a top-up or part payment invoice.Read More

2.2 Invoice Clearing

The following endpoints allow performing operations with invoices clearing records.

The API endpoints belong to the Finance domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/finance/sit/v1

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

GET/invoices/{invoiceid}/clearingrecords
Returns a list of all invoice Clearing Records for a given invoiceId.Read More
POST/invoices/{invoiceid}/clearingrecords
Adds an invoice Clearing Record for a given InvoiceId.Read More
GET/invoices-by-number/{invoiceNumber}/clearingrecords
Returns a list of all invoice Clearing Records for a given invoiceNumber.Read More
POST/invoices-by-number/{invoiceNumber}/clearingrecords
Adds an invoice Clearing Record for a given invoiceNumber.Read More
GET/invoices-by-uid/{invoiceUid}/clearingrecords
Returns a list of invoice Clearing Records for a given invoiceUid.Read More
POST/invoices-by-uid/{invoiceUid}/clearingrecords
Adds an invoice Clearing Record for a given invoiceUid.Read More
GET/invoices/{invoiceid}/clearingrecords/{recordid}
Returns an invoice clearing record with given recordid, which belongs to an invoice identified with invoiceid.Read More
PUT/invoices/{invoiceid}/clearingrecords/{recordid}
Updates an existing InvoiceClearingRecord.Read More
DELETE/invoices/{invoiceid}/clearingrecords/{recordid}
Deletes an invoice clearing record with given recordid.Read More

2.3 Payment Type

The endpoint described in this section allows retrieving a list of payment types that can be used in invoices payment process.

The API endpoint belong to the Finance domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/finance/sit/v1

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

GET/payment-types
Returns a list of Payment Types.Read More

2.4 Total Balances

The following endpoints are used for listing Total Balances.

The API endpoints belong to the Bulk Billing domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/bulk/billing/v2

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

GET/total-balances
Returns a list of total balances.Read More
GET/valid-prepaid-total-balances
Returns a prepaid total balance list.Read More
GET/valid-postpaid-total-balances
Returns a postpaid total balance list.Read More

2.5 Credit Record Types

This endpoint is used to get all Credit Records Types.

The API endpoint belongs to the Billing domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/bulk/billing/v2

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

GET/credit-record-types
Returns a list of supported credit record types.Read More

2.6 Product Type Partners LOV

The endpoint described in this section allows retrieving a list of Product Type Partners LOV.

The API endpoint belong to the Biz-core domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/biz-core/v1

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

GET/product-type-partners-lov
Returns a list of Product Type Partners LOV.Read More

2.7 Platform Owner Bank Accounts

The following endpoint is used for listing data of platform owner bank accounts.

The API endpoint belong to the Settings domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/settings/v1

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

GET/platform-owner-bank-accounts
Returns a list of bank accounts of a platform owner or a co-owner.Read More

3. Methods Details

3.1 Invoices

These endpoints allow retrieving a list of payable invoices and top-up invoices.

The API endpoints belong to the Finance domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/finance/sit/v1

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

GET/payable-invoices
Returns a list of all payable invoices.Up
Method Overview

The method returns a list of payable invoices.

Payable invoices are invoices whose status is 'approved' and whose payment status is 'open'.

Authorization privilege needed for this endpoint: finance-invoices.view.
Optional: privilege used in this endpoint is finance-invoices-own.view.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

Parameters
Name Type Description
page_number integer (query) Page number. Default value: 1.
page_size integer (query) Page size. Default value: 10.
paging string (query) Paging options in form of &paging=page_num page_size e.g. paging=1,10.
operator(fieldName) string (query) Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: custName, custShortName, invNumber, invDate, invDueDate, overDueDate, total, totalUnpaid, totalPaid, invType, invTypeName, invPeriod, invPeriodStart, invPeriodEnd, invoicingDate, invoicingDatePolicy, classCodeName, currency, id, disputeStatus, statusDt, dataSourceCodeName, custID, processingStatus, collectionLeadId, collectionMode, vat, amountNoVat, amountVat, domainCodeName, custCountry, nettingInvoiceStatus, nettingInvoicePaymentStatus, rounding, dtsSelectorId, dtsSelectorCodeName, invUid, custPOBox, docsDeliveryStatus, selfBilling, customerType, domainName, syncStatus, syncStatusDt, syncMode, collectionLeadNumber, ownerId, ownerBpName, ownerBpBriefName.

  • If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted.
  • If the operator is in or notin, the field value must be a comma separated list of values.
  • If the operator is between or notbetween, the field value must be a comma separated list of two values, representing the beginning and the end of the range.
  • Operator can be omitted and in that case it will be treated as operator is eq (Example: fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q' and operator is eq or omitted, the field value will be used in general search across multiple attributes.
q string (query) General search criteria.

Available fields: custShortName, custName, invNumber, invDate, invoicingDate, invoicingDatePolicy, invDueDate, invTypeName, invPeriod, disputeStatus, ownerId, ownerBpName, ownerBpBriefName.

sort string (query) Sorting options in form of sort=-attribute1,attribute2,-attribute3.

Sorting available fields: custName, custShortName, invNumber, invDate, invDueDate, overDueDate, total, totalUnpaid, totalPaid, invType, invTypeName, invPeriod, invPeriodStart, invPeriodEnd, invoicingDate, invoicingDatePolicy, classCodeName, currency, id, disputeStatus, statusDt, dataSourceCodeName, custID, processingStatus, collectionLeadId, collectionMode, vat, amountNoVat, amountVat, domainCodeName, custCountry, nettingInvoiceStatus, nettingInvoicePaymentStatus, rounding, dtsSelectorId, dtsSelectorCodeName, invUid, custPOBox, docsDeliveryStatus, selfBilling, customerType, domainName, syncStatus, syncStatusDt, syncMode, collectionLeadNumber, ownerId, ownerBpName, ownerBpBriefName.

Responses
Code Description Links
200 List of invoices. No links
default Unexpected Error. No links
Success Response 200: List of Invoices
{
  "data": [
    {
      "id": 0,
      "invUid": "string",
      "instanceID": 0,
      "custID": 0,
      "custName": "string",
      "custShortName": "string",
      "custAttn": "string",
      "custAddress": "string",
      "custAddress2": "string",
      "custPost": "string",
      "custCity": "string",
      "custCountry": 0,
      "custPOBox": "string",
      "customerType": "string",
      "custVatNumber": "string",
      "invType": 0,
      "invTypeName": "string",
      "templateID": 0,
      "invDate": "2024-02-29",
      "invoicingDate": "2024-02-29",
      "invoicingDatePolicy": "delivery",
      "invNumberFix": "string",
      "invNumberNum": 0,
      "invNumber": "string",
      "invPeriod": "string",
      "invDueDate": "2024-02-29",
      "overDueDate": 0,
      "ownerVatNumber": "string",
      "currency": 0,
      "currencyCode": "string",
      "amountNoVat": 0,
      "amountVat": 0,
      "vatPercent": 0,
      "vat": 0,
      "rounding": 0,
      "total": 0,
      "totalUnpaid": 0,
      "totalPaid": 0,
      "vatInPrice": 0,
      "vatInTotal": 0,
      "status": "draft",
      "insertDt": "2024-02-29T13:52:05.633Z",
      "statusDt": "2024-02-29T13:52:05.633Z",
      "deliveryDate": "2024-02-29",
      "invPeriodStart": "2024-02-29",
      "invPeriodEnd": "2024-02-29",
      "docsDeliveryStatus": "string",
      "docsDeliveryStatusDate": "2024-02-29T13:52:05.633Z",
      "docsDeliveryDlrStatus": "string",
      "docsDeliveryDlrStatusDate": "2024-02-29T13:52:05.633Z",
      "classCodeName": "string",
      "classDomain": "string",
      "classArea": "string",
      "lang": "string",
      "paymentStatus": "none",
      "paymentStatusDate": "2024-02-29T13:52:05.633Z",
      "disputeStatus": "string",
      "disputeStatusDate": "2024-02-29T13:52:05.633Z",
      "dataSourceId": 0,
      "dataSourceCodeName": "string",
      "nettingInvoiceId": 0,
      "nettingInvoiceNumber": "string",
      "selfBilling": "yes",
      "domainId": 0,
      "domainCodeName": "string",
      "domainName": "string",
      "domainProduct": 0,
      "accountManagerId": 0,
      "accountManagerName": "string",
      "disputeNextId": 0,
      "collectionMode": "none",
      "collectionLeadId": 0,
      "collectionLeadNumber": "string",
      "collectionLeadNettingInvoiceId": 0,
      "collectionLeadNettingInvoiceNumber": "string",
      "collectionLeadNettingInvoiceStatus": "string",
      "collectionLeadNettingInvoicePaymentStatus": "string",
      "collectionLeadNettingInvoiceTotal": "string",
      "collectionLeadNettingInvoiceTotalPaid": "string",
      "collectionLeadNettingInvoiceTotalUnpaid": "string",
      "processingStatus": "none",
      "comment": "string",
      "nettingInvoiceStatus": "draft",
      "nettingPaymentStatus": "none",
      "nettingTotal": 0,
      "nettingTotalUnpaid": 0,
      "nettingTotalPaid": 0,
      "dtsSelectorId": 0,
      "dtsSelectorCodeName": "string",
      "sitInvoiceEmailImportId": 0,
      "billingBalance": {
        "id": 0,
        "name": "string",
        "resourceUrl": "string"
      },
      "billingTypeName": "string",
      "smsCount": 0,
      "syncStatus": "none",
      "syncStatusDt": "2024-02-29T13:52:05.633Z",
      "syncMode": "disabled",
      "reminderStatus": "enabled",
      "domesticCurrency": 0,
      "domesticCurrencyCode": "string",
      "domesticCurrencyAmountNoVAT": 0,
      "domesticCurrencyAmountVAT": 0,
      "domesticCurrencyTotal": 0,
      "domesticCurrencyRounding": 0,
      "domesticCurrencyRate": 0,
      "industryName": "string",
      "ownerName": "string",
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "documentSync": {}
    }
  ],
  "meta": {
    "pagination": {}
  }
}
Error Response Unexpected Error: Default
{
  "Code": 0,
  "Message": "string"
}
GET/topup-invoices
Returns a list of top-up Invoices.Up
Method Overview

The method returns a list of top-up Invoices.

Authorization privilege needed for this endpoint: finance-invoices.view.
Optional privilege used in this endpoint: finance-invoices-own.view.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

Parameters
Name Type Description
page_number integer (query) Page number. Default value: 1.
page_size integer (query) Page size. Default value: 10.
paging string (query) Paging options. The format is: &paging=page_num,page_size e.g. paging=1,10.
operator(fieldName) string (query) Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: custName, custShortName, invNumber, invDate, invDueDate, overDueDate, total, totalUnpaid, totalPaid, invType, invTypeName, invPeriod, invPeriodStart, invPeriodEnd, invoicingDate, invoicingDatePolicy, classCodeName, currency, id, disputeStatus, statusDt, dataSourceCodeName, custID, processingStatus, collectionLeadId, collectionMode, vat, amountNoVat, amountVat, domainCodeName, custCountry, nettingInvoiceStatus, nettingInvoicePaymentStatus, rounding, dtsSelectorId, dtsSelectorCodeName, invUid, custPOBox, docsDeliveryStatus, selfBilling, customerType, domainName, syncStatus, syncStatusDt, syncMode, collectionLeadNumber, ownerId, ownerBpName, ownerBpBriefName.

  • If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted.
  • If the operator is in or notin, the field value must be a comma separated list of values.
  • If the operator is between or notbetween, the field value must be a comma separated list of two values, representing the beginning and the end of the range.
  • Operator can be omitted and in that case it will be treated as operator is eq (Example: fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q' and operator is eq or omitted, the field value will be used in general search across multiple attributes.
q string (query) General search criteria.

Available fields: custShortName, custName, invNumber, invDate, invoicingDate, invoicingDatePolicy, invDueDate, invTypeName, invPeriod, disputeStatus, ownerId, ownerBpName, ownerBpBriefName.

sort string (query) Sorting options in form of sort=-attribute1,attribute2,-attribute3.

Sorting available fields: custName, custShortName, invNumber, invDate, invDueDate, overDueDate, total, totalUnpaid, totalPaid, invType, invTypeName, invPeriod, invPeriodStart, invPeriodEnd, invoicingDate, invoicingDatePolicy, classCodeName, currency, id, disputeStatus, statusDt, dataSourceCodeName, custID, processingStatus, collectionLeadId, collectionMode, vat, amountNoVat, amountVat, domainCodeName, custCountry, nettingInvoiceStatus, nettingInvoicePaymentStatus, rounding, dtsSelectorId, dtsSelectorCodeName, invUid, custPOBox, docsDeliveryStatus, selfBilling, customerType, domainName, syncStatus, syncStatusDt, syncMode, collectionLeadNumber, ownerId, ownerBpName, ownerBpBriefName.

Success Response 200: List of Invoices
{
  "data": [
    {
      "id": 0,
      "invUid": "string",
      "instanceID": 0,
      "custID": 0,
      "custName": "string",
      "custShortName": "string",
      "custAttn": "string",
      "custAddress": "string",
      "custAddress2": "string",
      "custPost": "string",
      "custCity": "string",
      "custCountry": 0,
      "custPOBox": "string",
      "customerType": "string",
      "custVatNumber": "string",
      "invType": 0,
      "invTypeName": "string",
      "templateID": 0,
      "invDate": "2024-05-07",
      "invoicingDate": "2024-05-07",
      "invoicingDatePolicy": "delivery",
      "invNumberFix": "string",
      "invNumberNum": 0,
      "invNumber": "string",
      "invPeriod": "string",
      "invDueDate": "2024-05-07",
      "overDueDate": 0,
      "ownerVatNumber": "string",
      "currency": 0,
      "currencyCode": "string",
      "amountNoVat": 0,
      "amountVat": 0,
      "vatPercent": 0,
      "vat": 0,
      "rounding": 0,
      "total": 0,
      "totalUnpaid": 0,
      "totalPaid": 0,
      "vatInPrice": 0,
      "vatInTotal": 0,
      "status": "draft",
      "insertDt": "2024-05-07T12:10:38.923Z",
      "statusDt": "2024-05-07T12:10:38.923Z",
      "deliveryDate": "2024-05-07",
      "invPeriodStart": "2024-05-07",
      "invPeriodEnd": "2024-05-07",
      "docsDeliveryStatus": "string",
      "docsDeliveryStatusDate": "2024-05-07T12:10:38.923Z",
      "docsDeliveryDlrStatus": "string",
      "docsDeliveryDlrStatusDate": "2024-05-07T12:10:38.923Z",
      "classCodeName": "string",
      "classDomain": "string",
      "classArea": "string",
      "lang": "string",
      "paymentStatus": "none",
      "paymentStatusDate": "2024-05-07T12:10:38.923Z",
      "disputeStatus": "string",
      "disputeStatusDate": "2024-05-07T12:10:38.923Z",
      "dataSourceId": 0,
      "dataSourceCodeName": "string",
      "nettingInvoiceId": 0,
      "nettingInvoiceNumber": "string",
      "selfBilling": "yes",
      "domainId": 0,
      "domainCodeName": "string",
      "domainName": "string",
      "domainProduct": 0,
      "accountManagerId": 0,
      "accountManagerName": "string",
      "disputeNextId": 0,
      "collectionMode": "none",
      "collectionLeadId": 0,
      "collectionLeadNumber": "string",
      "collectionLeadNettingInvoiceId": 0,
      "collectionLeadNettingInvoiceNumber": "string",
      "collectionLeadNettingInvoiceStatus": "string",
      "collectionLeadNettingInvoicePaymentStatus": "string",
      "collectionLeadNettingInvoiceTotal": "string",
      "collectionLeadNettingInvoiceTotalPaid": "string",
      "collectionLeadNettingInvoiceTotalUnpaid": "string",
      "processingStatus": "none",
      "comment": "string",
      "nettingInvoiceStatus": "draft",
      "nettingPaymentStatus": "none",
      "nettingTotal": 0,
      "nettingTotalUnpaid": 0,
      "nettingTotalPaid": 0,
      "dtsSelectorId": 0,
      "dtsSelectorCodeName": "string",
      "sitInvoiceEmailImportId": 0,
      "billingBalance": {
        "id": 0,
        "name": "string",
        "resourceUrl": "string"
      },
      "billingTypeName": "string",
      "smsCount": 0,
      "syncStatus": "none",
      "syncStatusDt": "2024-05-07T12:10:38.923Z",
      "syncMode": "disabled",
      "reminderStatus": "enabled",
      "domesticCurrency": 0,
      "domesticCurrencyCode": "string",
      "domesticCurrencyAmountNoVAT": 0,
      "domesticCurrencyAmountVAT": 0,
      "domesticCurrencyTotal": 0,
      "domesticCurrencyRounding": 0,
      "domesticCurrencyRate": 0,
      "industryName": "string",
      "ownerName": "string",
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "documentSync": {}
    }
  ],
  "meta": {
    "pagination": {}
  }
}
Error Response Unexpected Error: Default
{
  "Code": 0,
  "Message": "string"
}
POST/credit-record-invoices
Creates a top-up or part payment invoice.Up

This endpoint will create Customer Part Payment Invoices for Postpaid Total Balances and Customer Top-Up Invoices, for Prepaid Total Balances.

The API endpoint belongs to the Bulk Billing domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/bulk/billing/v2

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

Method Overview

The method creates a top-up or part payment invoice creation. For a top-up process, it is used to create new credit record with related invoice.

Parameters
Name Type Description
credit record create (required) object (body) New credit record with invoice to store.
fields string (query) Comma separated list of attributes that needs to be returned in partial response.
Data Parameters

post data object

{
  "balanceId": 0,
  "amount": 0,
  "comment": "string",
  "payment": {
    "fullyPaid": true,
    "paymentType": 0,
    "bankAccountId": 0
  }
}
Responses
Code Description Links
200 Credit record object with related invoice is created. No links
default Unexpected Error. No links
{
  "id": 0,
  "creditUid": "string",
  "balanceId": 0,
  "activationDate": "2024-04-25",
  "creationDate": "2024-04-25",
  "amount": 0,
  "currency": 0,
  "creditAmount": 0,
  "conditionalAmount": 0,
  "paidAmount": 0,
  "unpaidAmount": 0,
  "status": "string",
  "isAggregateRecord": "string",
  "aggregateFromDate": "2024-04-25",
  "invoiceId": 0,
  "bizPartnerName": "string",
  "bizPartnerShortName": "string",
  "bizPartnerId": 0,
  "balanceName": "string",
  "typeId": 0,
  "billingRecordId": 0,
  "type": "string",
  "typeName": "string",
  "createInvoice": "yes",
  "billingType": 0,
  "currencyCode": "string",
  "currencyName": "string",
  "orderingStatus": "off",
  "orderingStatusDt": "2024-04-25T14:04:05.979Z",
  "selectedPriceListId": 0,
  "ownerId": 0,
  "ownerBpName": "string",
  "ownerBpBriefName": "string",
  "description": "string",
  "comment": "string",
  "invoice": {
    "id": 0,
    "instanceID": 0,
    "custID": 0,
    "custName": "string",
    "custShortName": "string",
    "custAttn": "string",
    "custAddress": "string",
    "custAddress2": "string",
    "custPost": "string",
    "custCity": "string",
    "custCountry": 0,
    "custPOBox": "string",
    "custVatNumber": "string",
    "invType": 0,
    "invTypeName": "string",
    "templateID": 0,
    "invDate": "string",
    "invNumberFix": "string",
    "invNumberNum": 0,
    "invNumber": "string",
    "invPeriod": "string",
    "invDueDate": "string",
    "overDueDate": 0,
    "ownerVatNumber": "string",
    "currency": 0,
    "currencyCode": "string",
    "amountNoVat": 0,
    "amountVat": 0,
    "vatPercent": 0,
    "rounding": 0,
    "total": 0,
    "totalUnpaid": 0,
    "vatInPrice": 0,
    "vatInTotal": 0,
    "status": "string",
    "insertDt": "string",
    "statusDt": "string",
    "deliveryDate": "string",
    "invPeriodStart": "string",
    "invPeriodEnd": "string",
    "docsDeliveryStatus": "string",
    "docsDeliveryStatusDate": "string",
    "docsDeliveryDlrStatus": "string",
    "docsDeliveryDlrStatusDate": "string",
    "selfBilling": "yes",
    "totalPaid": 0,
    "classCodeName": "string",
    "classDomain": "string",
    "classArea": "string",
    "lang": "string",
    "paymentStatus": "none",
    "paymentStatusDate": "2024-04-25T14:04:05.979Z",
    "disputeStatus": "string",
    "disputeStatusDate": "2024-04-25T14:04:05.979Z",
    "dataSourceId": 0,
    "dataSourceCodeName": "string",
    "nettingInvoiceId": 0,
    "nettingInvoiceNumber": "string",
    "domainId": 0,
    "domainCodeName": "string",
    "disputeNextId": 0,
    "collectionMode": "none",
    "collectionLeadId": 0,
    "processingStatus": "none",
    "dtsSelectorId": 0,
    "dtsSelectorCodeName": "string",
    "ownerId": 0,
    "items": [
      {
        "id": 0,
        "invoiceId": 0,
        "ordNum": 0,
        "name": "string",
        "itemType": "string",
        "quantity": 0,
        "quantityMore": 0,
        "quantityMode": 0,
        "measureUnit": 0,
        "price": 0,
        "vatInPrice": 0,
        "totalNoVat": 0,
        "totalVat": 0,
        "status": "string",
        "insertDt": "string",
        "statusDt": "string",
        "dataSourceId": 0,
        "dataSourceForeignKey": 0,
        "dtsSelectorId": 0,
        "dtsSelectorCodeName": "string"
      }
    ]
  }
}
Error Response Unexpected Error: Default
{
  "code": 0,
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

3.2 Invoice Clearing

The following endpoints allow performing operations with invoices clearing records.

The API endpoints belong to the Finance domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/finance/sit/v1

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

GET/invoices/{invoiceid}/clearingrecords
Returns a list of all invoice Clearing Records for a given invoiceId.Up
Method Overview

The method returns a list of all invoice clearing records for a given invoice ID.

Returned InvoiceClearingRecords belong to InvoiceClearing.
InvoiceClearing is created when Invoice status is changed to 'approved' and payment status is set to 'open'.
By default, only clearing records with 'active' status will be returned.

Authorization privilege needed for this endpoint: finance-invoices.view.
Optional: the privilege used in this endpoint: finance-invoices-own.view.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

If clearing records with other statuses should be returned, it should be used query parameter status with operator in and value containing a comma separated list of statuses (in(status)=active,canceled). For the time being, only 'active' and 'canceled' status are available as clearing record status values.

Parameters
Name Type Description
invoiceid (required) integer (path) Invoice ID to get Clearing Records.
page_number integer (query) Page number. Default value: 1.
page_size integer (query) Page size. Default value: 10.
paging string (query) Paging options in form of &paging=page_num page_size e.g. paging=1,10.
operator(fieldName) string (query) Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: id, clearingId, clearingTypeId, clearingTypeCodeName, recordDate, paymentTypeId, paymentTypeName, amountIncrement, paidAmount, paymentReference, comment, status, statusDate, bankAccountId, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic, revokeUserId, revokeUserName, revokeComment.

  • If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted.
  • If the operator is in or notin, the field value must be a comma separated list of values.
  • If the operator is between or notbetween, the field value must be a comma separated list of two values representing the beginning and the end of a range.
  • Operator can be omitted and in that case it will be treated as operator is eq (Example: fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q' and operator is eq or omitted, the field value will be used in general search across multiple attributes.
q string (query) General search criteria.

Available fields: status, paymentReference, comment, revokeUserId, revokeUserName, revokeComment, clearingTypeCodeName, paymentTypeName, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic.

sort string (query) Sorting options in form of sort=-attribute1,attribute2,-attribute3.

Sorting available fields: id, clearingId, clearingTypeId, clearingTypeCodeName, recordDate, paymentTypeId, paymentTypeName, amountIncrement, paidAmount, paymentReference, comment, status, statusDate, bankAccountId, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic, revokeUserId, revokeUserName, revokeComment.

Responses
Code Description Links
200 List of InvoiceClearingRecords. No links
default Unexpected Error. No links
Success Response 200: List of InvoiceClearingRecords
{
  "data": [
    {
      "id": 0,
      "clearingId": 0,
      "clearingTypeId": 0,
      "clearingTypeCodeName": "string",
      "recordDate": "2021-03-11",
      "paymentTypeId": 0,
      "paymentTypeName": "string",
      "amountIncrement": 0,
      "paidAmount": 0,
      "paymentReference": "string",
      "comment": "string",
      "status": "string",
      "statusDate": "2021-03-11T10:35:26.862Z",
      "revokeUserId": "string",
      "revokeUserName": "string",
      "revokeComment": "string",
      "bankAccountId": 0,
      "bankAccountName": "string",
      "bankAccountNumber": "string",
      "bankAccountIban": "string",
      "bankAccountSwiftBic": "string"
    }
  ],
  "meta": {
    "pagination": {}
  }
}
Error Response Unexpected Error: Default
{
  "Code": 0,
  "Message": "string"
}
POST/invoices/{invoiceid}/clearingrecords
Adds an invoice Clearing Record for a given InvoiceId.Up
Method Overview

The method adds an invoice clearing record for a given invoice ID.

Authorization privilege needed for this endpoint:
- finance-invoices.manage or
- finance-cust-invoices.manage or
- finance-supplier-invoices.manage or
- finance-netting-invoices.manage.

InvoiceClearing is created when Invoice status is changed to 'approved' and payment status is set to 'open'.
Approved supplier invoices with payment status 'on-hold', do not have clearing created. Clearing record for supplier invoice is created when a supplier invoice is approved for payment.
Invoice clearing record can not be added if an invoice does not have Clearing created.
When totalUnpaid is 0, invoice.paymentStatus is set to 'closed'.

clearingType type can be:
1 - Invoice = amount increment, is auto-generated when Invoice status is changed to 'approved',
2 - Payment = paidAmount - must be <> 0,
3 - Interest = amount increment - must be <> 0,
4 - Reminder = amount increment - must be <> 0.

paymentType type can be:
1 - Bank Transfer,
2 - Credit Card,
3 - PayPal,
4 - Cash.

If paymentType is '1 - Bank Transfer', bankAccountId greater than 0 must be sent, in other cases it should not be sent or can be 0.

status is set to 'active'.
comment is set to name of clearingType if omitted.
recordDate must be in format 2006-01-02.

If clearing record represents payment and invoice document class code name is CUSTOMER_INVOICE, payment will be automatically applied to billing balance.

Minimal JSON body parameters
{
  "clearingTypeId": 2,
  "recordDate": "2016-08-05",
  "paymentTypeId": 1,
  "amountIncrement": 0,
  "paidAmount": 10,
  "paymentReference": "string"
}
Parameters
Name Type Description
invoiceID (required) string (path) Invoice ID to get.
post data (required) object (body) Post data. If status is used, it must be in (active, deleted). recordDate must be in format 2006-01-02.
Data Parameters

Clearing Record post data object example

{
  "clearingTypeId": 0,
  "recordDate": "2021-03-11",
  "paymentTypeId": 0,
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "bankAccountId": 0
}
Responses
Code Description Links
200 InvoiceClearingRecord added. No links
default Unexpected Error. No links
Success Response 200: InvoiceClearingRecord added
{
  "id": 0,
  "clearingId": 0,
  "clearingTypeId": 0,
  "clearingTypeCodeName": "string",
  "recordDate": "2021-03-11",
  "paymentTypeId": 0,
  "paymentTypeName": "string",
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "status": "string",
  "statusDate": "2021-03-11T10:11:27.765Z",
  "revokeUserId": "string",
  "revokeUserName": "string",
  "revokeComment": "string",
  "bankAccountId": 0,
  "bankAccountName": "string",
  "bankAccountNumber": "string",
  "bankAccountIban": "string",
  "bankAccountSwiftBic": "string"
}
Error Response Unexpected Error: Default
{
  "Code": 0,
  "Message": "string"
}
GET/invoices-by-number/{invoiceNumber}/clearingrecords
Returns a list of all invoice Clearing Records for a given invoiceNumber.Up
Method Overview

The method returns a list of all invoice clearing records for a given invoice number.

Authorization privilege needed for this endpoint: finance-invoices.view.
Optional privilege used in this endpoint: finance-invoices-own.view.

List of all InvoiceClearingRecords is returned that belongs to InvoiceClearing.
InvoiceClearing is created when Invoice status is changed to 'approved' and payment status is set to 'open'.
By default, only clearing records with active status will be returned.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

If clearing records with other statuses should be returned, it should be used query parameter status with operator in and value containing a comma separated list of statuses (in(status)=active,canceled). For the time being, only 'active' and 'canceled' status are available as clearing record status values.

Parameters
Name Type Description
invoiceNumber (required) string (path) Invoice number to get Clearing Records.
If the invoice number contains slashes, it must be encoded.
Example: For invoiceNumber = 00033/E/2021 value 00033%2FE%2F2021 should be in URL as invoiceNumber parameter (/ = %2F).
page_number integer (query) Page number. Default value: 1.
page_size integer (query) Page size. Default value: 10.
paging string (query) Paging options in form of &paging=page_num page_size e.g. paging=1,10.
operator(fieldName) string (query) Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: id, clearingId, clearingTypeId, clearingTypeCodeName, recordDate, paymentTypeId, paymentTypeName, amountIncrement, paidAmount, paymentReference, comment, status, statusDate, bankAccountId, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic, revokeUserId, revokeUserName, revokeComment.

  • If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted.
  • If the operator is in or notin, the field value must be a comma separated list of values.
  • If the operator is between or notbetween, the field value must be a comma separated list of two values representing the beginning and the end of a range.
  • Operator can be omitted and in that case, it will be treated as operator is eq (Example: fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q' and operator is eq or omitted, the field value will be used in general search across multiple attributes.
q string (query) General search criteria.

Available fields: status, paymentReference, comment, revokeUserId, revokeUserName, revokeComment, clearingTypeCodeName, paymentTypeName, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic.

sort string (query) Sorting options in form of sort=-attribute1,attribute2,-attribute3.

Sorting available fields: id, clearingId, clearingTypeId, clearingTypeCodeName, recordDate, paymentTypeId, paymentTypeName, amountIncrement, paidAmount, paymentReference, comment, status, statusDate, bankAccountId, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic, revokeUserId, revokeUserName, revokeComment.

Responses
Code Description Links
200 List of InvoiceClearingRecords. No links
default Unexpected Error. No links
Success Response 200: List of InvoiceClearingRecords
{
  "data": [
    {
      "id": 0,
      "clearingId": 0,
      "clearingTypeId": 0,
      "clearingTypeCodeName": "string",
      "recordDate": "2021-03-11",
      "paymentTypeId": 0,
      "paymentTypeName": "string",
      "amountIncrement": 0,
      "paidAmount": 0,
      "paymentReference": "string",
      "comment": "string",
      "status": "string",
      "statusDate": "2021-03-11T10:50:05.688Z",
      "revokeUserId": "string",
      "revokeUserName": "string",
      "revokeComment": "string",
      "bankAccountId": 0,
      "bankAccountName": "string",
      "bankAccountNumber": "string",
      "bankAccountIban": "string",
      "bankAccountSwiftBic": "string"
    }
  ],
  "meta": {
    "pagination": {}
  }
}
Error Response Unexpected Error: Default
{
  "Code": 0,
  "Message": "string"
}
POST/invoices-by-number/{invoiceNumber}/clearingrecords
Adds an invoice Clearing Record for a given invoiceNumber.Up
Method Overview

The method adds an invoice clearing record for a given invoice number.

Authorization privilege needed for this endpoint:
- finance-invoices.manage or
- finance-cust-invoices.manage or
- finance-supplier-invoices.manage or
- finance-netting-invoices.manage.

InvoiceClearing is created when Invoice status is changed to 'approved' and payment status is set to 'open'.
Approved supplier invoices with payment status 'on-hold', do not have clearing created. Clearing record for supplier invoice is created when a supplier invoice is approved for payment.
Invoice clearing record can not be added if an invoice does not have Clearing created.
When totalUnpaid is 0, invoice.paymentStatus is set to 'closed'.

clearingType type can be:
1 - Invoice = amount increment, is auto-generated when Invoice status is changed to 'approved',
2 - Payment = paidAmount - must be <> 0,
3 - Interest = amount increment - must be <> 0,
4 - Reminder = amount increment - must be <> 0.

paymentType type can be:
1 - Bank Transfer,
2 - Credit Card,
3 - PayPal,
4 - Cash.

If paymentType is '1 - Bank Transfer', bankAccountId greater than 0 must be sent, in other cases it should not be sent or can be 0.

status is set to 'active'.
comment is set to name of clearingType if omitted.
recordDate must be in format 2006-01-02.

If clearing record represents payment and invoice document class code name is CUSTOMER_INVOICE, payment will be automatically applied to billing balance.

Minimal JSON body parameters
{
  "clearingTypeId": 2,
  "recordDate": "2016-08-05",
  "paymentTypeId": 1,
  "amountIncrement": 0,
  "paidAmount": 10,
  "paymentReference": "string"
}
Parameters
Name Type Description
invoiceNumber (required) string (path) Invoice number to get Clearing Records.
If the invoice number contains slashes, it must be encoded.
Example: For invoiceNumber = 00033/E/2021 value 00033%2FE%2F2021 should be in URL as invoiceNumber parameter (/ = %2F).
post data (required) object (body) Post data. The recordDate must be in format 2006-01-02.
Post Data Parameters
{
  "clearingTypeId": 0,
  "recordDate": "2021-03-11",
  "paymentTypeId": 0,
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "bankAccountId": 0
}
Responses
Code Description Links
200 InvoiceClearingRecord added. No links
default Unexpected Error. No links
Success Response 200: InvoiceClearingRecord added
{
  "id": 0,
  "clearingId": 0,
  "clearingTypeId": 0,
  "clearingTypeCodeName": "string",
  "recordDate": "2021-03-11",
  "paymentTypeId": 0,
  "paymentTypeName": "string",
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "status": "string",
  "statusDate": "2021-03-11T10:56:49.498Z",
  "revokeUserId": "string",
  "revokeUserName": "string",
  "revokeComment": "string",
  "bankAccountId": 0,
  "bankAccountName": "string",
  "bankAccountNumber": "string",
  "bankAccountIban": "string",
  "bankAccountSwiftBic": "string"
}
Error Response Unexpected Error: Default
{
  "Code": 0,
  "Message": "string"
}
GET/invoices-by-uid/{invoiceUid}/clearingrecords
Returns a list of invoice Clearing Records for a given invoiceUid.Up
Method Overview

The method returns a list of invoice clearing records for a given invoice UID.

Authorization privilege needed for this endpoint: finance-invoices.view.
Optional privilege used in this endpoint: finance-invoices-own.view.

Returned InvoiceClearingRecords belong to InvoiceClearing.
InvoiceClearing is created when Invoice status is changed to 'approved' and payment status is set to 'open'.
By default, only clearing records with active status will be returned.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

If clearing records with other statuses should be returned, it should be used query parameter status with operator in and value containing a comma separated list of statuses (in(status)=active,canceled). For the time being, only 'active' and 'canceled' status are available as clearing record status values.

Parameters
Name Type Description
invoiceUid (required) string (path) Invoice UID to get Clearing Records.
page_number integer (query) Page number. Default value: 1.
page_size integer (query) Page size. Default value: 10.
paging string (query) Paging options in form of &paging=page_num page_size e.g. paging=1,10.
operator(fieldName) string (query) Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: id, clearingId, clearingTypeId, clearingTypeCodeName, recordDate, paymentTypeId, paymentTypeName, amountIncrement, paidAmount, paymentReference, comment, status, statusDate, bankAccountId, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic, revokeUserId, revokeUserName, revokeComment.

  • If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted.
  • If the operator is in or notin, the field value must be a comma separated list of values.
  • If the operator is between or notbetween, the field value must be a comma separated list of two values representing the beginning and the end of a range.
  • Operator can be omitted and in that case it will be treated as operator is eq (Example: fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q' and operator is eq or omitted, the field value will be used in general search across multiple attributes.
q string (query) General search criteria.

Available fields: status, paymentReference, comment, revokeUserId, revokeUserName, revokeComment, clearingTypeCodeName, paymentTypeName, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic.

sort string (query) Sorting options in form of sort=-attribute1,attribute2,-attribute3.

Sorting available fields: id, clearingId, clearingTypeId, clearingTypeCodeName, recordDate, paymentTypeId, paymentTypeName, amountIncrement, paidAmount, paymentReference, comment, status, statusDate, bankAccountId, bankAccountName, bankAccountNumber, bankAccountIban, bankAccountSwiftBic, revokeUserId, revokeUserName, revokeComment.

Responses
Code Description Links
200 List of InvoiceClearingRecords. No links
default Unexpected Error. No links
Success Response 200: List of InvoiceClearingRecords
{
  "data": [
    {
      "id": 0,
      "clearingId": 0,
      "clearingTypeId": 0,
      "clearingTypeCodeName": "string",
      "recordDate": "2021-03-11",
      "paymentTypeId": 0,
      "paymentTypeName": "string",
      "amountIncrement": 0,
      "paidAmount": 0,
      "paymentReference": "string",
      "comment": "string",
      "status": "string",
      "statusDate": "2021-03-11T12:19:07.845Z",
      "revokeUserId": "string",
      "revokeUserName": "string",
      "revokeComment": "string",
      "bankAccountId": 0,
      "bankAccountName": "string",
      "bankAccountNumber": "string",
      "bankAccountIban": "string",
      "bankAccountSwiftBic": "string"
    }
  ],
  "meta": {
    "pagination": {}
  }
}
Error Response Unexpected Error: Default
{
  "Code": 0,
  "Message": "string"
}
POST/invoices-by-uid/{invoiceUid}/clearingrecords
Adds an invoice Clearing Record for a given invoiceUid.Up
Method Overview

The method adds an invoice clearing record for a given invoice UID.

Authorization privilege needed for this endpoint:
- finance-invoices.manage or
- finance-cust-invoices.manage or
- finance-supplier-invoices.manage or
- finance-netting-invoices.manage.

InvoiceClearing is created when Invoice status is changed to 'approved' and payment status is set to 'open'.
Approved supplier invoices with payment status 'on-hold', do not have clearing created. Clearing record for supplier invoice is created when a supplier invoice is approved for payment.
Invoice clearing record can not be added if an invoice does not have Clearing created.
When totalUnpaid is 0, invoice.paymentStatus is set to 'closed'.

clearingType type can be:
1 - Invoice = amount increment, is auto-generated when Invoice status is changed to 'approved',
2 - Payment = paidAmount - must be <> 0,
3 - Interest = amount increment - must be <> 0,
4 - Reminder = amount increment - must be <> 0.

paymentType type can be:
1 - Bank Transfer,
2 - Credit Card,
3 - PayPal,
4 - Cash.

If paymentType is '1 - Bank Transfer', bankAccountId greater than 0 must be sent, in other cases it should not be sent or can be 0.

status is set to 'active'.
comment is set to name of clearingType if omitted.
recordDate must be in format 2006-01-02.

If clearing record represents payment and invoice document class code name is CUSTOMER_INVOICE, payment will be automatically applied to billing balance.

Minimal Json body parameters
{
  "clearingTypeId": 2,
  "recordDate": "2016-08-05",
  "paymentTypeId": 1,
  "amountIncrement": 0,
  "paidAmount": 10,
  "paymentReference": "string"
}
Parameters
Name Type Description
invoiceUID (required) integer (path) Invoice UID to get Clearing Records.
post data (required) object (body) Post data. If it is used, status must be in (active, deleted). The recordDate must be in format YYYY-MM-DD.
Post Data Parameters
{
  "clearingTypeId": 0,
  "recordDate": "2021-03-11",
  "paymentTypeId": 0,
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "bankAccountId": 0
}
Responses
Code Description Links
200 InvoiceClearingRecord added. No links
default Unexpected Error. No links
Success Response 200: InvoiceClearingRecord added
{
  "id": 0,
  "clearingId": 0,
  "clearingTypeId": 0,
  "clearingTypeCodeName": "string",
  "recordDate": "2021-03-11",
  "paymentTypeId": 0,
  "paymentTypeName": "string",
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "status": "string",
  "statusDate": "2021-03-11T12:26:30.255Z",
  "revokeUserId": "string",
  "revokeUserName": "string",
  "revokeComment": "string",
  "bankAccountId": 0,
  "bankAccountName": "string",
  "bankAccountNumber": "string",
  "bankAccountIban": "string",
  "bankAccountSwiftBic": "string"
}
Error Response Unexpected Error: Default
{
  "Code": 0,
  "Message": "string"
}
GET/invoices/{invoiceid}/clearingrecords/{recordid}
Returns an invoice clearing record with given recordid, which belongs to an invoice identified with invoiceid.Up
Method Overview

The method returns an invoice clearing record with given recordid, which belongs to invoice identified with invoiceid.

Authorization privilege needed for this endpoint: finance-invoices.view.
Optional: privilege used in this endpoint is finance-invoices-own.view.

Parameters
Name Type Description
invoiceid (required) integer (path) Invoice ID.
recordid (required) integer (path) ID of invoiceClearingRecord to get.
Responses
Code Description Links
200 InvoiceClearingRecord returned successfully. No links
default Unexpected Error. No links
Success Response 200: InvoiceClearingRecord returned successfully
{
  "id": 0,
  "clearingId": 0,
  "clearingTypeId": 0,
  "clearingTypeCodeName": "string",
  "recordDate": "2024-01-23",
  "paymentTypeId": 0,
  "paymentTypeName": "string",
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "status": "string",
  "statusDate": "2024-01-23T12:32:51.796Z",
  "revokeUserId": "string",
  "revokeUserName": "string",
  "revokeComment": "string",
  "bankAccountId": 0,
  "bankAccountName": "string",
  "bankAccountNumber": "string",
  "bankAccountIban": "string",
  "bankAccountSwiftBic": "string"
}
Error Response Unexpected Error: Default
{
  "Code": 0,
  "Message": "string"
}
PUT/invoices/{invoiceid}/clearingrecords/{recordid}
Updates an existing InvoiceClearingRecord.Up
Method Overview

The method updates an existing InvoiceClearingRecord.

Authorization privilege needed for this endpoint:
- finance-invoices.manage or
- finance-cust-invoices.manage or
- finance-supplier-invoices.manage or
- finance-netting-invoices.manage.

After this operation, requested invoice clearing record will be marked as 'canceled' and new clearing record will be created and returned instead of the original.
InvoiceClearing value will be recalculated.
Canceled clearing records will be listed in the clearing records list, unlike deleted credit records, which are not listed.

If clearing record represents payment and invoice document class code name is CUSTOMER_INVOICE, payment will be applied to billing balance. When corrected payment value is less than original payment value, it may happen that applying payment change will result in block balance, because funds are already spent. In that case the following error with HTTP status code 409 will be returned.

{
  "error":
    {
      "code": "CHANGE_PAYMENT_BLOCK_BALANCE",
      "message": "after delete of edit payment balance will be blocked because of insufficient funds available"
    }
}

If the API user still wants to edit a payment, the same API call should be used but with the parameter force=yes, effectively forcing the payment deletion.

Parameters
Name Type Description
invoceid (required) integer (path) Invoice ID.
recordid (required) integer (path) ID of invoiceClearingRecord to update.
force string (query) Forces edit of a payment for customer invoices even if operation will lead to customer balance blocking.
Available values: yes, no.
Default value: no.
corrected clearing record data (required) object (body) Corrects clearing record date for a clearing. See below an example.

Example object for correcting clearing record date for a clearing:

{
  "clearingTypeId": 0,
  "recordDate": "2024-01-23",
  "paymentTypeId": 0,
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "revokeUserId": "string",
  "revokeUserName": "string",
  "revokeComment": "string",
  "bankAccountId": 0
}
Responses
Code Description Links
200 InvoiceClearingRecord updated successfully. No links
default Unexpected Error. No links
Success Response 200: InvoiceClearingRecord updated successfully
{
  "id": 0,
  "clearingId": 0,
  "clearingTypeId": 0,
  "clearingTypeCodeName": "string",
  "recordDate": "2024-01-23",
  "paymentTypeId": 0,
  "paymentTypeName": "string",
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "status": "string",
  "statusDate": "2024-01-23T12:44:02.373Z",
  "revokeUserId": "string",
  "revokeUserName": "string",
  "revokeComment": "string",
  "bankAccountId": 0,
  "bankAccountName": "string",
  "bankAccountNumber": "string",
  "bankAccountIban": "string",
  "bankAccountSwiftBic": "string"
}
Error Response Unexpected Error: Default
{
  "Code": 0,
  "Message": "string"
}
DELETE/invoices/{invoiceid}/clearingrecords/{recordid}
Deletes an invoice clearing record with given recordid.Up
Method Overview

The method deletes an invoice clearing record with given recordid.

Authorization privilege needed for this endpoint:
- finance-invoices.manage or
- finance-cust-invoices.manage or
- finance-supplier-invoices.manage or
- finance-netting-invoices.manage.

Deletion of Invoice Clearing records performs logical delete. Record's status will be set to delete. After this, clearing record will not be presented when listing.
InvoiceClearing value will be recalculated.
If clearing record represents payment and invoice document class code name is CUSTOMER_INVOICE, deleting payment will be applied to billing balance resulting decreasing balance amount and increasing unpaid amount. It may happen that applying payment change will result in blocking balance, because the funds are already spent. In that case, the following error with HTTP status code 409 and body will be returned:

{
  "error":
    {
      "code": "CHANGE_PAYMENT_BLOCK_BALANCE",
      "message": "after delete of edit payment balance will be blocked because of insufficient funds available"
    }
}

If the API user still wants to delete a payment, the same API call should be used but with the parameter force=yes effectively forcing the payment deletion. In that case, after a payment is deleted, balance and account will be blocked for use because of insufficient funds.

Parameters
Name Type Description
invoceid (required) integer (path) Invoice ID.
recordid (required) integer (path) ID of invoiceClearingRecord to be deleted.
force string (query) Forces deletion of a payment for customer invoices, even if operation will lead to customer balance blocking.
Available values: yes, no.
Default value: no.
Responses
Code Description Links
200 InvoiceClearingRecord deleted successfully. No links
default Unexpected Error. No links
Success Response 200: InvoiceClearingRecord deleted successfully
Error Response Unexpected Error: Default
{
  "Code": 0,
  "Message": "string"
}

3.3 Payment Type

The endpoint described in this section allows retrieving a list of payment types that can be used in invoices payment process.

The API endpoint belong to the Finance domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/finance/sit/v1

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

GET/payment-types
Returns a list of Payment TypesUp
Method Overview

The method returns a list of all available payment types.

Authorization privilege needed for this endpoint: finance-invoices.view.
Optional privilege used in this endpoint: finance-invoices-own.view.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

Parameters
Name Type Description
page_number integer (query) Page number. Default value: 1.
page_size integer (query) Page size. Default value: 10.
paging string (query) Paging options in form of &paging=page_num page_size e.g. paging=1,10.
operator(fieldName) string (query) Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: id, name, status, statusDt.

  • If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted.
  • If the operator is in or notin, the field value must be a comma separated list of values.
  • If the operator is between or notbetween, the field value must be a comma separated list of two values representing the beginning and the end of a range.
  • Operator can be omitted and in that case it will be treated as operator is eq (Example: fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q' and operator is eq or omitted, the field value will be used in general search across multiple attributes.
q string (query) General search criteria.

Available fields: name, status.

sort string (query) Sorting options in form of sort=-attribute1,attribute2,-attribute3.

Sorting available fields: id, name, status, statusDt.

Responses
Code Description Links
200 List of Payment Types. No links
default Unexpected Error. No links
Success Response 200: List of Payment Types
{
  "data": [
    {
      "id": 0,
      "name": "string",
      "status": "active",
      "statusDt": "2021-03-11T12:29:43.054Z"
    }
  ],
  "meta": {
    "pagination": {}
  }
}
Error Response Unexpected Error: Default
{
  "Code": 0,
  "Message": "string"
}

3.4 Total Balances

The following endpoints are used for listing Total Balances.

The API endpoint belongs to the Billing domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/bulk/billing/v2

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

GET/total-balances
Returns a list of total balances.Up
Method Overview

The method returns a list of total balances with filtering and pagination features. Balance amounts(balance, accountsTotal, usage, availableAmount) and smsCount run-time value instead of snapshot values.

Parameters
Name Type Description
all string (query) Returns all data for given criteria.
Available values: yes, no.
Default value: no
page_size integer (query) Page size. Default value: 10.
page_number integer (query) Page number. Default value: 1.
paging string (query) Paging options. The format is: &paging=page_num,page_size e.g. paging=1,10.
fields string (query) Comma separated list of attributes that needs to be returned in partial response.
sort string (query) Sort criteria:
Format propertyName for ASC sorting, -propertyName for DESC sorting.
Example:
name = "name ASC", -name = "name DESC".
Sort available properties: id, bizPartnerId, isDefault, currency, billingType, name, status, alertsPolicyId, alertsBaseAmount, amount, paidTotal, unpaidTotal, billedTotal, accountsTotal, smsCount, creditLimit, debitLimit, overdraftLimit, debitBalanceThreshold, bizPartnerName, bizPartnerShortName, usage, availableAmount, totalCredit, debitTotal, ownerId, ownerBpName, ownerBpBriefName, blockOnOutOfCredit.
operator(propertyName) string (query) Search criteria using following operators: isnull,isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and by following properties: id, bizPartnerId, isDefault, currency, billingType, name, status, alertsPolicyId, alertsBaseAmount, amount, paidTotal, unpaidTotal, billedTotal, accountsTotal, smsCount, creditLimit, debitLimit, overdraftLimit, debitBalanceThreshold, bizPartnerName, bizPartnerShortName, usage, availableAmount, totalCredit, debitTotal, ownerId, ownerBpName, ownerBpBriefName, blockOnOutOfCredit.

  • If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted.
  • If the operator is in or notin, the field value must be a comma separated list of values.
  • If the operator is between or notbetween, the field value must be a comma separated list of two values, representing the beginning and the end of the range.
  • Operator can be omitted and in that case it will be treated as operator is eq (Example: fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If propertyName is 'q' and operator is eq or omitted, the property value will be used in general search across multiple attributes.
Responses
Code Description Links
200 Total Balances collection. No links
default Unexpected Error. No links
Success Response 200: Total Balances Collection
{
  "data": [
    {
      "id": 0,
      "instanceId": 0,
      "bizPartnerId": 0,
      "isDefault": "string",
      "amount": 0,
      "currency": 0,
      "accountsTotal": 0,
      "billedTotal": 0,
      "creditTotal": 0,
      "paidTotal": 0,
      "unpaidTotal": 0,
      "billingType": 0,
      "status": "string",
      "name": "string",
      "smsCount": 0,
      "billingCreditLimit": 0,
      "billingDebitLimit": 0,
      "billingOverdraftLimit": 0,
      "billingDebitThreshold": 0,
      "alertsPolicyId": 0,
      "alertsPolicyName": "string",
      "alertsBaseAmount": 0,
      "billingTypeName": "string",
      "billingTypeCodeName": "string",
      "billingModeName": "string",
      "currencyCode": "string",
      "currencyName": "string",
      "bizPartnerName": "string",
      "bizPartnerShortName": "string",
      "debitLimitTotal": 0,
      "availableAmount": 0,
      "usage": 0,
      "totalCredit": 0,
      "lastOpenEventHistoryId": 0,
      "billingCycleUnitId": 0,
      "billingCycle": 0,
      "billingStartDate": "2024-04-23",
      "nextBillingDate": "2024-04-23",
      "lastBillingRecordId": 0,
      "billingTriggerAmount": 0,
      "limitsCurrency": 0,
      "creditLimit": 0,
      "overdraftLimit": 0,
      "disputePercent": 0,
      "disputeValue": 0,
      "paymentTermsDays": 0,
      "pricePackageMode": "on",
      "pricePackageId": 0,
      "orderedPrepaidMode": "on",
      "overdraftPriceListId": 0,
      "firstCreditRecordId": 0,
      "currentCreditRecordId": 0,
      "invoiceCreation": "off",
      "invoiceSending": "on",
      "blockOnOutOfCredit": "on",
      "minUsageAmount": 0,
      "reportCycleUnitId": 0,
      "reportCycleUnit": "string",
      "reportCycle": 0,
      "reportStartDate": "2024-04-23",
      "nextReportDate": "2024-04-23",
      "lastBillingReportId": 0,
      "invoiceSettings": {
        "extentNote": "string",
        "extentVatNote": "string",
        "extentAdditionalEmails": {
          "to": "string",
          "cc": "string",
          "bcc": "string"
        },
        "reminderMode": "disabled"
      },
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "alertsLanguage": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}
Error Response Unexpected Error: Default
{
  "code": 0,
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/valid-prepaid-total-balances
Returns a prepaid total balance list.Up
Method Overview

The method lists active and blocked prepaid total balances with filtering and pagination features.

URL Parameters
Name Type Description
all string (query) Returns all data for given criteria.
page_size integer (query) Page size. Default value is 10.
page_number integer (query) Page number. Default value is 1.
paging string (query) Paging options. The format is: &paging=page_num,page_size e.g. paging=1,10.
fields string (query) Comma separated list of attributes that needs to be returned in partial response.
sort string (query) Sort criteria:
Format propertyName for ASC sorting, -propertyName for DESC sorting.
Example:
name = "name ASC", -name = "name DESC".
Sort available properties: id, bizPartnerId, currency, name, status, alertsPolicyId, alertsBaseAmount, bizPartnerName, bizPartnerShortName, alertsPolicyName, paidTotal, unpaidTotal, billedTotal, overdraftLimit, debitBalanceThreshold, pricePackageMode, pricePackageId, overdraftPriceListId, ownerId, ownerBpName, ownerBpBriefName, alertsLanguage, amount, smsCount, accountsTotal, usage, availableAmount, totalCredit, isDefault.
operator(propertyName) string (query) Search criteria using following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and by following properties: id, bizPartnerId, currency, name, status, alertsPolicyId, alertsBaseAmount, bizPartnerName, bizPartnerShortName, alertsPolicyName, paidTotal, unpaidTotal, billedTotal, overdraftLimit, debitBalanceThreshold, pricePackageMode, pricePackageId, overdraftPriceListId, ownerId, ownerBpName, ownerBpBriefName, alertsLanguage, amount, smsCount, accountsTotal, usage, availableAmount, totalCredit, isDefault.

  • If operator is one of isnull, isnotnull, isempty, isnotempty, a field value can be omitted.
  • If operator is in or notin, a field value must be a comma separated list of values.
  • If operator is between or notbetween, a field value must be a comma separated list of two values, representing the beginning and the end of a range.
  • Operator can be omitted, and in that case, it will be treated as operator is eq (E.g.: fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q', and operator is eq or omitted, a field value will be used in general search across multiple attributes.
Success Response 200: Total Balances collection
{
  "data": [
    {
      "id": 0,
      "name": "string",
      "bizPartnerId": 0,
      "bizPartnerName": "string",
      "bizPartnerShortName": "string",
      "billingTypeCodeName": "PREPAID",
      "billingTypeName": "string",
      "status": "active",
      "smsCount": 0,
      "amount": 0,
      "accountsTotal": 0,
      "billedTotal": 0,
      "creditTotal": 0,
      "paidTotal": 0,
      "unpaidTotal": 0,
      "usage": 0,
      "totalCredit": 0,
      "availableAmount": 0,
      "currency": 0,
      "currencyCode": "string",
      "currencyName": "string",
      "overdraftLimit": 0,
      "billingCreditLimit": 0,
      "billingOverdraftLimit": 0,
      "limitsCurrency": 0,
      "billingDebitThreshold": 0,
      "disputePercent": 0,
      "disputeValue": 0,
      "paymentTermsDays": 0,
      "pricePackageMode": "on",
      "pricePackageId": 0,
      "overdraftPriceListId": 0,
      "invoiceSending": "on",
      "blockOnOutOfCredit": "on",
      "minUsageAmount": 0,
      "reportCycleUnit": "string",
      "reportCycle": 0,
      "reportStartDate": "2024-04-26T12:12:25.264Z",
      "nextReportDate": "2024-04-26T12:12:25.264Z",
      "lastBillingReportId": 0,
      "alertsBaseAmount": 0,
      "alertsPolicyId": 0,
      "alertsPolicyName": "string",
      "alertsLanguage": "string",
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "isDefault": "yes"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}
Error Response Unexpected Error: Default
{
  "code": 0,
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/valid-postpaid-total-balances
Returns a postpaid total balance list.Up
Method Overview

The method lists active and blocked postpaid total balances with filtering and pagination features.

URL Parameters
Name Type Description
all string (query) Returns all data for given criteria.
page_size integer (query) Page size. Default value is 10.
page_number integer (query) Page number. Default value is 1.
paging string (query) Paging options. The format is: &paging=page_num,page_size e.g. paging=1,10.
fields string (query) Comma separated list of attributes that needs to be returned in partial response.
sort string (query) Sort criteria:
Format propertyName for ASC sorting, -propertyName for DESC sorting.
Example:
name = "name ASC", -name = "name DESC".
Sort available properties: id, bizPartnerId, currency, name, status, alertsPolicyId, alertsBaseAmount, bizPartnerName, bizPartnerShortName, alertsPolicyName, paidTotal, unpaidTotal, billedTotal, overdraftLimit, debitBalanceThreshold, pricePackageMode, pricePackageId, overdraftPriceListId, ownerId, ownerBpName, ownerBpBriefName, alertsLanguage, amount, smsCount, accountsTotal, usage, availableAmount, totalCredit, isDefault.
operator(propertyName) string (query) Search criteria using following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and by following properties: id, bizPartnerId, currency, name, status, alertsPolicyId, alertsBaseAmount, bizPartnerName, bizPartnerShortName, alertsPolicyName, paidTotal, unpaidTotal, billedTotal, overdraftLimit, debitBalanceThreshold, pricePackageMode, pricePackageId, overdraftPriceListId, ownerId, ownerBpName, ownerBpBriefName, alertsLanguage, amount, smsCount, accountsTotal, usage, availableAmount, debitLimit, debitTotal, isDefault.

  • If operator is one of isnull, isnotnull, isempty, isnotempty, a field value can be omitted.
  • If operator is in or notin, a field value must be a comma separated list of values.
  • If operator is between or notbetween, a field value must be a comma separated list of two values, representing the beginning and the end of a range.
  • Operator can be omitted, and in that case, it will be treated as operator is eq (E.g.: fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q', and operator is eq or omitted, a field value will be used in general search across multiple attributes.
Success Response 200: Total Balances collection
{
  "data": [
    {
      "id": 0,
      "name": "string",
      "bizPartnerId": 0,
      "bizPartnerName": "string",
      "bizPartnerShortName": "string",
      "billingTypeCodeName": "PREPAID",
      "billingTypeName": "string",
      "status": "active",
      "smsCount": 0,
      "amount": 0,
      "accountsTotal": 0,
      "billedTotal": 0,
      "paidTotal": 0,
      "unpaidTotal": 0,
      "usage": 0,
      "debitLimitTotal": 0,
      "availableAmount": 0,
      "billingTriggerAmount": 0,
      "currency": 0,
      "currencyCode": "string",
      "currencyName": "string",
      "creditLimit": 0,
      "overdraftLimit": 0,
      "billingDebitLimit": 0,
      "billingOverdraftLimit": 0,
      "limitsCurrency": 0,
      "billingDebitThreshold": 0,
      "disputePercent": 0,
      "disputeValue": 0,
      "paymentTermsDays": 0,
      "pricePackageMode": "on",
      "pricePackageId": 0,
      "overdraftPriceListId": 0,
      "invoiceSending": "on",
      "blockOnOutOfCredit": "on",
      "minUsageAmount": 0,
      "billingCycleUnit": "string",
      "billingCycle": 0,
      "billingStartDate": "2024-04-26T12:12:25.277Z",
      "nextBillingDate": "2024-04-26T12:12:25.277Z",
      "lastBillingRecordId": 0,
      "alertsBaseAmount": 0,
      "alertsPolicyId": 0,
      "alertsPolicyName": "string",
      "alertsLanguage": "string",
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "isDefault": "yes"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}
Error Response Unexpected Error: Default
{
  "code": 0,
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

3.5 Credit Record Types

This endpoint is used to get all Credit Records Types.

The API endpoint belongs to the Billing domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/bulk/billing/v2

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

GET/credit-record-types
Returns a list of supported credit record types.Up
Method Overview

The method returns a list of supported credit record types

Parameters

No parameters.

Responses
Code Description Links
200 Credit Record Types Collection. No links
default Unexpected Error. No links
Success Response 200: Credit Record Types Collection
{
  "data": [
    {
      "id": 0,
      "typeUid": "string",
      "codeName": "string",
      "name": "string",
      "billingTypeId": 0,
      "createInvoice": "yes",
      "status": "active",
      "statusDt": "2024-04-22T08:53:30.940Z",
      "comment": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}
Error Response Unexpected Error: Default
{
  "code": 0,
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

3.6 Product Type Partners LOV

The endpoint described in this section allows retrieving a list of Product Type Partners LOV.

The API endpoint belong to the Biz-core domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/biz-core/v1

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

GET/product-type-partners-lov
Returns a list of Product Type Partners LOV.Up
Method Overview

The method returns a list of Product Type Partners LOV, i.e. all Business Partners associated with the product.

The required privileges: biz-core.view or biz-core.own.view.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

URL Parameters
Name Type Description
all string (query) Returns all data for a given criteria.
Available values: yes, no.
Default value: no.
page_size integer (query) Page size.
Default value: 10.
page_number integer (query) Page number.
Default value: 1.
paging string (query) Paging options in the form of &paging=page_num,page_size, e.g. paging=1,10.
sort string (query) Sort options in the form of sort=-attribute1,attribute2,-attribute3.
operator(fieldName) string (query) Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, includeIds and by following attributes: id, name, country, countryName, vatNumber, vatApply, regNumber, legalFormId, language, status, languageName, legalForm, briefName, industryId, companySizeId, eMail, phone, fax, taxExempt, dunsNumber, industryName, companySize, ownerBpId, ownerBpName, ownerBpBriefName, instanceRole.
Sort allowed attributes: id, name, country, countryName, vatNumber, vatApply, regNumber, legalFormId, language, status, languageName, legalForm, briefName, industryId, companySizeId, eMail, phone, fax, taxExempt, dunsNumber, industryName, companySize, ownerBpId, ownerBpName, ownerBpBriefName, instanceRole.

  • If operator is one of isnull, isnotnull, isempty, isnotempty, a field value can be omitted.
  • If operator is in or notin, a field value must be a comma separated list of values.
  • If operator is between or notbetween, a field value must be a comma separated list of two values, representing the beginning and the end of a range.
  • Operator can be omitted, and in that case, it will be treated as operator is eq (E.g.: fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q', and operator is eq or omitted, a field value will be used in general search across multiple attributes.
Responses
Code Description Links
200 A list of Product Type Partners LOV. No links
default Unexpected error. No links
Success Response 200: List of Product Type Partners LOV
{
  "data": [
    {
      "id": 0,
      "name": "string",
      "instanceRole": "string",
      "country": 0,
      "countryName": "string",
      "vatNumber": "string",
      "vatApply": "string",
      "regNumber": "string",
      "legalAddressId": 0,
      "status": "string",
      "parentId": 0,
      "legalFormId": 0,
      "language": "string",
      "languageName": "string",
      "legalForm": "string",
      "instanceOwnerName": "string",
      "briefName": "string",
      "detailsId": 0,
      "hasAttributes": "yes",
      "externalRefId": 0,
      "bizPartnerInstanceUid": "string",
      "statusActiveDt": "2021-01-26T09:51:36.318Z",
      "statusDt": "2021-01-26T09:51:36.318Z",
      "industryId": 0,
      "companySizeId": 0,
      "eMail": "string",
      "phone": "string",
      "fax": "string",
      "taxExempt": "string",
      "foundingD": "2021-01-26T09:51:36.318Z",
      "dunsNumber": "string",
      "industryName": "string",
      "companySize": "string",
      "ownerBpId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string",
      "selfOwner": "yes",
      "isIntercompany": "yes",
      "partnerTypeId": 0,
      "partnerTypeName": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "totalPages": 0,
      "currentPage": 0,
      "perPage": 0,
      "count": 0
    }
  }
}
Error Response Unexpected Error: Default
{
  "Code": 0,
  "Message": "string"
}

3.7 Platform Owner Bank Accounts

The following endpoint is used for listing data of platform owner bank accounts.

The API endpoint belong to the Settings domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/settings/v1

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

GET/platform-owner-bank-accounts
Returns a list of bank accounts of a platform owner or a co-owner.Up
Method Overview

The method returns a list of bank accounts of a platform owner or a co-owner.

Authorization privilege needed for this endpoint: biz-core.view.

This endpoint accepts query parameters for filtering data described on URL Filtering Guidelines page.

When co-owners are enabled on the platform level, coOwnerId parameter should be sent. If coOwnerId is not sent, bank accounts for platform owner will be returned. If co-owners are disabled, coOwnerId should not be sent.

Parameters
Name Type Description
all string (query) Returns all data for a given criteria.
Available values: yes, no. Default value: no.
page_number integer (query) Page number. Default value: 1.
page_size integer (query) Page size. Default value: 10.
paging string (query) Paging options in form of &paging=page_num page_size e.g. paging=1,10.
sort string (query) Sorting options in form of sort=-attribute1,attribute2,-attribute3.
operator(fieldName) string (query) Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: id, coOwnerId, bizPartnerId, bizPartnerName, bizPartnerBriefName, bizBankId, bizBankName, currency, currencyCode, currencyName, accountNumber, iban, isDefaultPerCurrency, status, name, swiftBic, accountType, countryName, ownerId, ownerBpName, ownerBpBriefName.

  • If the operator is one of isnull, isnotnull, isempty, isnotempty, the field value can be omitted.
  • If the operator is in or notin, the field value must be a comma separated list of values.
  • If the operator is between or notbetween, the field value must be a comma separated list of two values representing the beginning and the end of a range.
  • Operator can be omitted and in that case it will be treated as operator is eq (Example: fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q' and operator is eq or omitted, the field value will be used in general search across multiple attributes.
Responses
Code Description Links
200 List of bank accounts. No links
default Unexpected Error. No links
Success Response 200: List of bank accounts
{
  "data": [
    {
      "id": 0,
      "bizPartnerId": 0,
      "bizPartnerName": "string",
      "bizPartnerBriefName": "string",
      "bizBankId": 0,
      "bizBankName": "string",
      "currency": 0,
      "currencyCode": "string",
      "currencyName": "string",
      "accountNumber": "string",
      "iban": "string",
      "isDefaultPerCurrency": "yes",
      "status": "active",
      "statusDt": "2021-03-11T12:56:00.268Z",
      "name": "string",
      "swiftBic": "string",
      "accountType": "account number",
      "countryName": "string",
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0
    }
  }
}
Error Response Unexpected Error: Default
{
  "Code": 0,
  "Message": "string"
}

4. Data Models

Data Models define the structure of a JSON document and describe data related to the Top-Up API.

4.1 InvoiceCollection

InvoiceCollection object properties:

Name Type Description
data (required) array Array of Invoice objects.
meta (required) object CollectionMeta object.

4.2 Invoice

Invoice object properties:

Name Type Description
id integer Invoice ID.
invUid string Invoice UID.
instanceID integer Instance ID.
custID integer Customer ID.
custName string Customer name.
custShortName string Customer short name.
custAttn string Customer Attn. data.
custAddress string Customer address.
custAddress2 string Customer address2.
custPost string Customer address postcode.
custCity string Customer address city.
custCountry integer Customer address country.
custPOBox string Customer address PO Box.
customerType string Customer type.
custVatNumber string Customer VAT number.
invType integer Invoice type.
invTypeName string Invoice type name.
templateID integer Template ID.
invDate string($date) Invoice date.
invoicingDate string($date) Invoicing date.
invoicingDatePolicy string Possible values: delivery, creation, approval.
invNumberFix string The fixed part of the invoice number, based on this field system will define next invoice number.
invNumberNum integer The invoice number (variable part) - it counts invoices for the same invNumberFix.
invNumber string Invoice number.
invPeriod string Invoice period.
invDueDate string($date) Invoice due date.
overDueDate integer Number of days over due date.
ownerVatNumber string Owner VAT number.
currency integer Currency.
currencyCode string Currency code.
amountNoVat number($float) Invoice amount without VAT (net amount). It can be negative when selfBilling is 'yes'.
amountVat number($float) Invoice amount including VAT. It can be negative when selfBilling is 'yes'.
vatPercent number($float) VAT percent.
vat number($float) Value added tax.
rounding number($float) Difference between an invoice total and amount including VAT value.
total number($float) Invoice gross amount. It can be negative when selfBilling is 'yes'.
totalUnpaid number($float) Invoice unpaid amount.
totalPaid number($float) Invoice paid amount.
vatInPrice integer VAT in price.
vatInTotal integer VAT in total.
status string Invoice status. Possible values: draft, approved, rejected, deleted, misc, canceled, archived, imported.
insertDt string($date‑time) Date and time of insertion.
statusDt string($date‑time) Date and time of status.
deliveryDate string($date) Delivery date.
invPeriodStart string($date) Start of invoice period.
invPeriodEnd string($date) End of invoice period.
docsDeliveryStatus string Document delivery status.
docsDeliveryStatusDate string($date‑time) Document delivery status date and time.
docsDeliveryDlrStatus string Status of DLR.
docsDeliveryDlrStatusDate string($date‑time) DLR status date and time.
classCodeName string Class code name.
classDomain string Class domain.
classArea string Class area.
lang string Language.
paymentStatus string Possible values: none, open, on-hold, closed.
paymentStatusDate string($date‑time) Payment status date and time.
disputeStatus string DisputeStatus indicates whether the invoice is in dispute process or not.
disputeStatusDate string($date‑time) Dispute status date and time.
dataSourceId integer Data source ID.
dataSourceCodeName string Data source code name.
nettingInvoiceId integer Netting statement ID.
nettingInvoiceNumber string Netting statement number.
selfBilling string Indicator if an invoice is a credit note or not. If value is 'yes', when the document is in netting statement, it indicates that the document is in favor of a buyer, but issued by the seller. Also, if the document class is CREDIT_DEBIT_NOTE, it indicates that the document is a credit note, which is also in favor of buyer, but issued by the seller. Possible values: yes, no.
domainId integer Domain ID.
domainCodeName string Domain code name.
domainName string Domain name.
domainProduct integer Domain product.
accountManagerId integer Account manager ID.
accountManagerName string Account manager name.
disputeNextId integer Dispute ID.
collectionMode string Document collection mode. If member, the document is member of a collection. If lead, the document is a collection lead. By default collection mode is 'none', which indicates that the document is not a member of a collection nor collection lead. Possible values: none, member, lead.
collectionLeadId integer If document is a member of collection, this value contains id of collection lead document.
collectionLeadNumber string If document is a member of collection, this value contains number of collection lead document.
collectionLeadNettingInvoiceId integer Netting statement ID of collection lead. Returned when collection lead to whom current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoiceNumber string Netting statement number of collection lead. Returned when collection lead to whom current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoiceStatus string Netting statement status of collection lead. Returned when collection lead to whom current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoicePaymentStatus string Netting statement payment status of collection lead. Returned when collection lead to whom current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoiceTotal string Netting statement total amount of collection lead. Returned when collection lead to whom current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoiceTotalPaid string Netting statement total paid amount of collection lead. Returned when collection lead to whom current invoice belongs to, is a netting statement's member.
collectionLeadNettingInvoiceTotalUnpaid string Netting statement total unpaid amount of collection lead. Returned when collection lead to whom current invoice belongs to, is a netting statement's member.
processingStatus string Indicates processing status of document if document has been assigned recalculation task(s) or some other kind of processing tasks. Possible values: none, scheduled, running, done, canceled.
comment string Description or comment in case invoice is a credit or debit note. Comment is not available when the invoice list is returned as a result of request, regardless of invoice class code name.
nettingInvoiceStatus string If invoice netting statement's member, this property contains netting statement status. Possible values: draft, approved, rejected, deleted, misc, canceled, archived.
nettingPaymentStatus string If invoice is netting statement's member, this property is netting's payment status. Possible values: none, open, closed.
nettingTotal number($float) If invoice is netting statement's member, this property is netting's gross amount. It can be negative when selfBilling is 'yes'.
nettingTotalUnpaid number($float) If invoice is netting statement's member this property is netting's unpaid amount.
nettingTotalPaid number($float) If invoice is netting statement's member this property is netting's paid amount.
dtsSelectorId integer ID reference to DTS selector, e.g. for part payment invoice.
dtsSelectorCodeName string DTS selector code name.
sitInvoiceEmailImportId integer ID of an invoice email import.
billingBalance object BillingBalance object.
billingTypeName string Required and returned for control invoice.
smsCount integer Amount of messages. Required and returned for postpaid and control invoices.
syncStatus string SyncStatus is an invoice synchronization status. Possible values: none, waiting, syncing, done, error, misc, exported.
syncStatusDt string($date‑time) Synchronization status date and time.
syncMode string Synchronization mode. Possible values: disabled, primary, secondary.
reminderStatus string Reminder status. Possible values: enabled, disabled, open, closed, misc.
domesticCurrency integer Domestic currency.
domesticCurrencyCode string Domestic currency code.
domesticCurrencyAmountNoVAT number($float) Invoice amount in domestic currency without VAT.
domesticCurrencyAmountVAT number($float) Invoice amount in domestic currency with VAT.
domesticCurrencyTotal number($float) Invoice total amount in domestic currency.
domesticCurrencyRounding number($float) Invoice rounding, difference between domestic currency total and domestic currency amount with VAT.
domesticCurrencyRate number($float) Domestic currency rate is used to calculate domestic currency amounts.
industryName string Industry name.
ownerName string Owner name.
ownerId integer Owner ID.
ownerBpName string Owner business partner name.
ownerBpBriefName string Owner business partner brief name.
documentSync object An arbitrary JSON object, holding the document synchronization data. It is returned if syncStatus is done, error, misc, exported or invalid.
Example: "documentSync": { "propertyA": "value A", "propertyB": "value B" }.

4.3 BillingBalance

BillingBalance object properties:

BillingBalance is Invoice Conditions which an invoice is associated to.

Name Type Description
id integer ID is the unique key for the Invoice Condition.
name string Invoice Condition name.
resourceUrl string Billing API URL that should be used to load billing balance resource.

4.4 CreditRecordInvoice

CreditRecordInvoice object properties:

Name Type Description
id integer Invoice ID.
creditUid string Credit UUID.
balanceId integer Balance ID.
activationDate string($date) Activation date.
creationDate string($date) Date of creation.
amount number($double) Amount.
currency integer Currency.
creditAmount number($double) Credit amount.
conditionalAmount number($double) Conditional amount.
paidAmount number($double) Paid amount.
unpaidAmount number($double) Unpaid amount.
status string Status.
isAggregateRecord string If record is aggregate record.
aggregateFromDate string($date) From Date for aggregate record.
invoiceId integer Invoice ID.
bizPartnerName string Business partner name.
bizPartnerShortName string Business partner short name.
bizPartnerId integer Business partner ID.
balanceName string Balance name.
typeId integer Type ID.
billingRecordId integer Billing record ID.
type string Type.
typeName string Type name.
createInvoice string Possible values: yes, no.
billingType integer Billing type.
currencyCode string Currency code.
currencyName string Currency name.
orderingStatus string Possible values: off, available, in-use, used.
orderingStatusDt string($date‑time) Ordering status date-time.
selectedPriceListId integer Selected price list ID.
ownerId integer Owner ID.
ownerBpName string Owner Business Partner ID.
ownerBpBriefName string Owner Business Partner brief name.
description string Description.
comment string Comment.
invoice object Invoice object.

4.5 CreditRecordInvoiceCreate

CreditRecordInvoiceCreate object properties:

Name Type Description
balanceId (required) integer Balance ID.
amount (required) number($double) Amount.
comment string Comment.
payment object PaymentData object.

4.6 PaymentData

PaymentData object properties:

Name Type Description
fullyPaid boolean If invoice is fully paid.
paymentType integer Payment type can be 1 - bank transfer, 2 - credit card, 3 - PayPal, 4 - Cash.
bankAccountId integer Bank account.

4.7 InvoiceClearingRecordCollection

InvoiceClearingRecordCollection object properties:

Name Type Description
data (required) array Array of InvoiceClearingRecord objects.
meta (required) object CollectionMeta object.

4.8 InvoiceClearingRecord

InvoiceClearingRecord object properties:

Name Type Description
id integer Invoice ID.
clearingId integer Clearing ID.
clearingTypeId integer Clearing type ID. Possible values: 1, 2, 3, 4.
clearingTypeCodeName string Clearing type code name. Possible values: Invoice, Payment, Interest, Reminder.
recordDate string($date) Clearing record date.
paymentTypeId integer Payment type ID, reference to paymentTypeName. Possible values: 1, 2, 3, 4.
paymentTypeName string Payment type name. Possible values: Bank Transfer, Credit Card, Paypal, Cash.
amountIncrement number($float) Amount increment.
paidAmount number($float) Paid amount.
paymentReference string Payment reference.
comment string Comment.
status string Clearing record status.
statusDate string($date‑time) Status date.
revokeUserId string Revoke user ID.
revokeUserName string Revoke username.
revokeComment string Comment on revocation.
bankAccountId integer Reference to bank account.
bankAccountName string Bank account name.
bankAccountNumber string Bank account number.
bankAccountIban string Bank account IBAN.
bankAccountSwiftBic string Bank account SWIFT/BIC code.

4.9 InvoiceClearingRecordPost

InvoiceClearingRecordPost object properties:

Name Type Description
clearingTypeId integer Clearing type ID.
recordDate string($date) Clearing record date.
paymentTypeId integer Payment type ID.
amountIncrement number($float) Amount increment.
paidAmount number($float) Paid amount.
paymentReference string Payment reference.
comment string Comment.
bankAccountId integer Reference to bank account which money was received or paid to.

4.10 InvoiceClearingRecordUpdate

InvoiceClearingRecordUpdate object properties:

Name Type Description
clearingTypeId integer Clearing type ID.
recordDate string($date) Clearing record date.
paymentTypeId integer Payment type ID.
amountIncrement number($float) Amount increment.
paidAmount number($float) Paid amount.
paymentReference string Payment reference.
comment string Comment.
revokeUserId string Revoke user ID.
revokeUserName string Revoke username.
revokeComment string Comment on revocation.
bankAccountId integer Reference to bank account which money was received or paid to.
JSON Example
{
  "clearingTypeId": 0,
  "recordDate": "2024-01-23",
  "paymentTypeId": 0,
  "amountIncrement": 0,
  "paidAmount": 0,
  "paymentReference": "string",
  "comment": "string",
  "revokeUserId": "string",
  "revokeUserName": "string",
  "revokeComment": "string",
  "bankAccountId": 0
}

4.11 PaymentTypeCollection

PaymentTypeCollection object properties:

Name Type Description
data (required) array Array of PaymentType objects.
meta (required) object CollectionMeta object.

4.12 PaymentType

PaymentType object properties:

Name Type Description
id integer Payment type ID.
name string Payment type name.
status string Payment status. Possible values: active, inactive.
statusDt string($date‑time) Date and time of payment status.
JSON example
{
  "data": [
    {
      "id": 0,
      "name": "string",
      "status": "active",
      "statusDt": "2021-03-11T12:29:43.054Z"
    }
  ],
  "meta": {
    "pagination": {}
  }
}

4.13 CreditRecordTypeCollection

CreditRecordTypeCollection object properties:

Name Type Description
data (required) array Array of CreditRecordType objects.
meta (required) object CollectionMeta object.

4.14 CreditRecordType

CreditRecordType object properties:

Name Type Description
id (required) integer Credit Record Type ID.
typeUid (required) string Credit Record Type type UID.
codeName (required) string Credit Record Type code name.
name (required) string Credit Record Type name.
billingTypeId (required) integer Credit Record Type billing type ID.
createInvoice (required) string If Credit Record Type create an invoice. Possible values: yes, no.
status string Credit Record Type status. Possible values: active, inactive.
statusDt string($date‑time) Date and time of a status.
comment string Comment.
JSON example
{
  "data": [
    {
      "id": 0,
      "typeUid": "string",
      "codeName": "string",
      "name": "string",
      "billingTypeId": 0,
      "createInvoice": "yes",
      "status": "active",
      "statusDt": "2024-04-22T08:53:30.940Z",
      "comment": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

4.15 TotalBalancePrepaidCollection

TotalBalancePrepaidCollection object properties:

Name Type Description
data (required) array Array of Total Balance Prepaid objects.
meta (required) object CollectionMeta object.

4.16 TotalBalancePrepaid

TotalBalancePrepaid object properties:

Name Type Description
id integer Total Balance Prepaid ID.
name string Total Balance Prepaid name.
bizPartnerId integer Business partner ID.
bizPartnerName string Business partner name.
bizPartnerShortName string Business partner short name.
billingTypeCodeName string Billing type code name. Possible values: PREPAID, POSTPAID.
billingTypeName string Billing type name.
status string Possible values: active, blocked.
smsCount integer Amount of messages. Required and returned for postpaid and control invoices.
amount number($double) Amount.
accountsTotal number($double) Accounts total.
billedTotal number($double) Billed total.
creditTotal number($double) Credit total.
paidTotal number($double) Paid total.
unpaidTotal number($double) Unpaid total.
usage number($double) Usage.
totalCredit number($double) Total credit.
availableAmount number($double) Available amount.
currency integer Currency.
currencyCode string Currency code.
currencyName string Currency name.
overdraftLimit number($double) Overdraft limit.
billingCreditLimit number($double) Billing credit limit.
billingOverdraftLimit number($double) Billing overdraft limit.
limitsCurrency integer Limit currency.
billingDebitThreshold number($double) Billing debit threshold.
disputePercent number($float) Dispute percent.
disputeValue number($double) Dispute value.
paymentTermsDays integer Payment terms days.
pricePackageMode string Price package mode. Possible values: on, off.
pricePackageId integer Price package ID.
overdraftPriceListId integer Over draft price list ID.
invoiceSending string Invoice sending. Possible values: on, off.
blockOnOutOfCredit string Indicator if balance and corresponding accounts will be blocked on out of credit event. For prepaid balance default value is 'on' and for postpaid and other billing types, default value is 'off'. Possible values: on, off.
minUsageAmount number($double) Postpaid setting about minimum usage amount on total balance level (considering billing_record.amount). This is always positive value or zero, which means there is no min_usage_amount. If usage amount is less than min_usage_amount, then additional surcharge will be added on invoice to provide that invoice amount (without VAT) is not less than min_usage_amount. If there is min_usage_amount on total_balance level then all such amounts on billing accounts are ignored.
reportCycleUnit string Report cycle unit code name.
reportCycle integer The length of prepaid reporting cycle, the default is zero. This field goes in pair with reportCycleUnit, example 2 month(s), 1 week, etc.
reportStartDate string($date‑time) Represents start date of first prepaid reporting cycle. If both fields, reportCycle and reportCycleUnit are greater than 0 then prepaid reporting is turned ON, otherwise it is considered to be OFF. If value for reportStartDate is not supplied and prepaid reporting is ON, API will calculate report start date automatically based on reporting period.
nextReportDate string($date‑time) Represents date when next prepaid report should be crated for current balance.
lastBillingReportId integer ID of last created billing report.
alertsBaseAmount number($double) Alerts base amount.
alertsPolicyId integer Alerts policy ID.
alertsPolicyName string Alerts policy name.
alertsLanguage string alerts language.
ownerId integer Owner ID.
ownerBpName string Owner Business Partner name.
ownerBpBriefName string Business Partner brief name.
isDefault string Possible values: on, off.

4.17 TotalBalancePostpaidCollection

TotalBalancePostpaidCollection object properties:

Name Type Description
data (required) array Array of Total Balance Postpaid objects.
meta (required) object CollectionMeta object.

4.18 TotalBalancePostpaid

TotalBalancePostpaid object properties:

Name Type Description
id integer Total Balance Postpaid ID.
name string Total Balance Postpaid name.
bizPartnerId integer Business partner ID.
bizPartnerName string Business partner name.
bizPartnerShortName string Business partner short name.
billingTypeCodeName string Billing type code name. Possible values: PREPAID, POSTPAID.
billingTypeName string Billing type name.
status string Possible values: active, blocked.
smsCount integer Amount of messages. Required and returned for postpaid and control invoices.
amount number($double) Amount.
accountsTotal number($double) Accounts total.
billedTotal number($double) Billed total.
paidTotal number($double) Paid total.
unpaidTotal number($double) Unpaid total.
usage number($double) Usage.
debitLimitTotal number($double) Debit limit total amount.
availableAmount number($double) Available amount.
billingTriggerAmount number($double) Billing trigger amount.
currency integer Currency.
currencyCode string Currency code.
currencyName string Currency name.
creditLimit number($double) Credit limit.
overdraftLimit number($double) Overdraft limit.
billingDebitLimit number($double) Billing debit limit.
billingOverdraftLimit number($double) Billing overdraft limit.
limitsCurrency integer Limit currency.
billingDebitThreshold number($double) Billing debit threshold.
disputePercent number($float) Dispute percent.
disputeValue number($double) Dispute value.
paymentTermsDays integer Payment terms days.
pricePackageMode string Price package mode. Possible values: on, off.
pricePackageId integer Price package ID.
overdraftPriceListId integer Over draft price list ID.
invoiceSending string Invoice sending. Possible values: on, off.
blockOnOutOfCredit string Indicator if balance and corresponding accounts will be blocked on out of credit event. For prepaid balance default value is 'on' and for postpaid and other billing types, default value is 'off'. Possible values: on, off.
minUsageAmount number($double) Postpaid setting about minimum usage amount on total balance level (considering billing_record.amount). This is always positive value or zero, which means there is no min_usage_amount. If usage amount is less than min_usage_amount, then additional surcharge will be added on invoice to provide that invoice amount (without VAT) is not less than min_usage_amount. If there is min_usage_amount on total_balance level then all such amounts on billing accounts are ignored.
reportCycle integer The length of prepaid reporting cycle, the default is zero. This field goes in pair with reportCycleUnit, example 2 month(s), 1 week, etc.
billingCycle integer The length of postpaid billing cycle, the default is zero. This field goes in pair with billingCycleUnit, example 2 month(s), 1 week, etc.
billingStartDate string($date‑time) Represents start date of first postpaid billing cycle.
nextBillingDate string($date‑time) Represents date when next postpaid billing record should be crated for current balance.
lastBillingReportId integer ID of last created billing record.
alertsBaseAmount number($double) Alerts base amount.
alertsPolicyId integer Alerts policy ID.
alertsPolicyName string Alerts policy name.
alertsLanguage string alerts language.
ownerId integer Owner ID.
ownerBpName string Owner Business Partner name.
ownerBpBriefName string Business Partner brief name.
isDefault string Possible value: yes.

4.19 ProductTypePartnersLovCollection

ProductTypePartnersLovCollection object properties:

Name Type Description
data (required) array An array of ProductTypePartnersLov objects.
meta (required) object CollectionMeta object.

4.20 ProductTypePartnersLov

ProductTypePartnersLov object properties:

Name Type Description
id integer ProductTypePartnersLov ID.
name string ProductTypePartnersLov name.
instanceRole string Instance role.
country integer Country code.
countryName string Country name.
vatNumber string VAT number.
vatApply string Possible values: yes, no, unknown.
regNumber string Registration number.
legalAddressId integer Legal address ID.
status string Status.
parentId integer Parent ID.
legalFormId integer Legal form ID.
language string Language.
languageName string Language name.
legalForm string Legal form.
instanceOwnerName string Instance owner name.
briefName string Brief name.
detailsId integer Details ID.
hasAttributes string Possible values: yes, no.
externalRefId integer External reference ID.
bizPartnerInstanceUid string BizPartnerInstance UID.
statusActiveDt string($date‑time) Date of active status.
statusDt string($date‑time) Status date.
industryId integer Industry ID.
companySizeId integer Company size ID.
eMail string E-mail.
phone string Phone.
fax string Fax.
taxExempt string Tax exemption.
foundingD string($date‑time) Founding date.
dunsNumber string DUNS number.
industryName string Industry name.
companySize string Company size.
ownerBpId integer Owner business partner ID.
ownerBpName string Business Partner name.
ownerBpBriefName string Business Partner brief name.
selfOwner string Possible values: yes, no.
isIntercompany string Possible values: yes, no.
partnerTypeId integer Partner type ID.
partnerTypeName string Partner type name.

4.21 BankAccountCollection

BankAccountCollection object properties:

Name Type Description
data (required) array Array of BankAccount objects.
meta (required) object CollectionMeta object.

4.22 BankAccount

BankAccount object properties:

Name Type Description
id integer Bank account ID.
bizPartnerId integer Business partner ID. maxLength: 10.
bizPartnerName string Business partner name.
bizPartnerBriefName string Business partner brief name.
bizBankId integer Bank ID. maxLength: 10.
bizBankName string Bank name.
currency integer Currency. maxLength: 5.
currencyCode string Currency code.
currencyName string Currency name.
accountNumber string Account number. maxLength: 40.
iban string Account IBAN. maxLength: 50.
isDefaultPerCurrency string Determines if an account will be default for bizPartnerId and currency. Only one account can be default. Possible values: yes, no.
status string Bank account status.
statusDt string($date‑time) Bank account status date and time.
name string Bank account name.
swiftBic string Bank account SWIFT/BIC code. maxLength: 30.
accountType string Account type. Possible values: account number, iban.
countryName string Country name.
ownerId integer Owner ID.
ownerBpName string Owner business partner name.
ownerBpBriefName string Owner business partner brief name.
JSON example
{
  "data": [
    {
      "id": 0,
      "bizPartnerId": 0,
      "bizPartnerName": "string",
      "bizPartnerBriefName": "string",
      "bizBankId": 0,
      "bizBankName": "string",
      "currency": 0,
      "currencyCode": "string",
      "currencyName": "string",
      "accountNumber": "string",
      "iban": "string",
      "isDefaultPerCurrency": "yes",
      "status": "active",
      "statusDt": "2021-03-11T12:56:00.268Z",
      "name": "string",
      "swiftBic": "string",
      "accountType": "account number",
      "countryName": "string",
      "ownerId": 0,
      "ownerBpName": "string",
      "ownerBpBriefName": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0
    }
  }
}

4.23 Error

Error object properties:

Name Type Description
code (required) integer($int32) Error code.
message (required) string Error message.
JSON Example
{
  "Code": 0,
  "Message": "string"
}

4.24 CollectionMeta

CollectionMeta object properties:

Name Type Description
pagination (required) object CollectionMetaPagination object.

4.25 CollectionMetaPagination

CollectionMetaPagination object properties:

Name Type Description
total (required) integer Total number of rows.
count (required) integer A number of rows in the current page.
perPage (required) integer The maximum rows per page.
currentPage (required) integer The current page number.
totalPages (required) integer Total number of pages.
links (required) object CollectionMetaPaginationLinks object.

4.26 CollectionMetaPaginationLinks

CollectionMetaPaginationLinks object properties:

Name Type Description
first string Link to the first page.
last string Link to the last page.
prev string Link to the previous page.
next string Link to the next page.
JSON example
"meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }