Access and manage invoices, PDFs, credits, and payment risk.
Upload Invoice Data
Uploads invoice data for processing and import. The payload is validated before import. Duplicate imports identified by import ID are rejected.
If a supplier billing type is specified, the invoice is processed as a Pass-Through Invoicing (PTI) import and routed to the PTI import container. Otherwise, the invoice is uploaded to standard import storage and queued for processing.
Upload Invoice Data › Request Body
tenantIdmandatory - the Tenant id
importIdmandatory - The id of the import - mandatory. Will be used to check if the import has been imported before
customerNameoptional/mandatory - name of the customer - used to look up customer. If IsSupplierInvoice=true then this is a mandatory field
customerGuidoptional - UC guid of the customer - used to look up customer
customerSSNorgoptional/mandatory - UC ssnorg of the customer - used to look up customer. If IsSupplierInvoice=true then this is a mandatory field
customerBirthoptional - Birt of the customer - used to look up customer. Date only ex. 2001-12-31
serviceTypeNamemandatory - service type name. Ex is NO_EL, FI_EL, SE_EL, DH_FO, DC_FO, NO_DP
supplierBillingType0 (Invoice), 1 (CreditNote).
paymentIdentificationoptional - The Payment identification (KID). If IsSupplierInvoice=true then this is a mandatory field
dueDateoptional - Any invoice due date
Array of lines to import
pdfFileoptional - Pdf file as Base64String
emailoptional - Used in distribution to better identify customer
phoneoptional - Used in distribution to better identify customer
mobileoptional - Used in distribution to better identify customer
Upload Invoice Data › Responses
File validated and uploaded
Credit Invoices
Submits credit requests for a list of invoices. Each request must include an ERP/invoice ID and may specify whether the credit note should be distributed, a reason, a comment, and whether a refund should be executed.
query Parameters
forceSet to 'fireatwill' to force crediting regardless of validation rules.
Credit Invoices › Request Body
erpIdErp Id of the invoice
toBeDistributedIf credit note should be distributed to end customer
commentComment for the credit
executeRefundEnd customer should be refund directly
Credit Invoices › Responses
Credit requests submitted
List Customer Invoices
Returns invoices for the specified customer. Results can be filtered to a specific invoice group (invoice collection/account) using accountguid. Results are paginated; page size depends on the ERP system. Credited invoices are included by default.
path Parameters
guidThe customer ID.
query Parameters
accountguidThe invoice group ID.
pageThe page number to retrieve. The first page is 1.
removeCreditedSet to true to exclude credited invoices from the response.
List Customer Invoices › Responses
Success
erpIdaccountGuidaccountErpIdnamedefaultAccountbalancestateMessageaccountTimestampadministrationFeecustomerOnHoldaccountOnHoldinvoiceIntervalprintfeehasPrintFeesecretLocationmanualApprovaldistributionChannelprincipleptihasGridInvocingpaymentTermsGet Invoice Details
Returns detailed information for a single invoice. Either the ERP/invoice ID or the invoice number must be provided to identify the invoice. Invoice lines can optionally be merged in the response. Response is cached for 15 minutes.
query Parameters
erpidThe ERP/invoice ID.
numberThe invoice number.
showMergedSet to true to merge invoice lines in the response.
Get Invoice Details › Responses
Success
invoicenumberinvoiceIdinvoicedateduedatelastPaymentDateoriginalduedatekidamountoriginalAmountvatbalancepaidAmountlossclosedOutstatusdistributionStatus0 (Unknown), 10 (Initialized), 20 (New), 30 (Sent), 40 (Trying), 50 (Failed), 60 (Rejected), 70 (NotToBeDistributed).
erpStatusdistributionchanneldistributiondatereceiverEndpointisCrediterpIdCanceledinvoiceNumberCanceleddistributionLogdirectDebittypeerpCustomerIddebtCaseIddebtCaseSentdebtCaseLinkdebtCaseCommentreminderStepoverDueStatus0 (Unknown), 1 (Loss), 2 (NextInvoice), 3 (Alert), 5 (Reminder), 6 (Debt), 7 (DebtResolved), 10 (Dunned).
journalEntryIdpaymentAgreement0 (Created), 10 (Active), 20 (Completed), 30 (Incompleted), -1 (Deleted).
creditCommentstopRemindersstopInterestDownload Invoice PDF
Downloads the PDF document for the specified invoice.
Note: A Base64-encoded token can be provided as an alternative to supplying tenant and customer ID directly. For internal tenants and non-production environments without a distribution test system, a generated preview PDF is returned instead of the original distribution file.
path Parameters
guidThe customer ID.
query Parameters
numberThe invoice number.
tokenA Base64-encoded token containing tenant and customer identifiers. Used as an alternative to providing tenant and customer ID directly.
originalfromreminderSet to true to return the original invoice PDF when the invoice was created from a reminder.
originalOnlySet to true to return only the original invoice PDF.
localeThe country code used to determine the language of the PDF preview, for example no, fi, or se. Defaults to the tenant country code.
Download Invoice PDF › Responses
Success
Update Invoice Due Date
Updates the due date for the specified invoice. The request body must include the ERP/invoice ID and the new due date. For UtilityCloud Ledger, interest calculation on late payment can optionally be stopped.
Update Invoice Due Date › Request Body
erpIddueDatestopInterestUpdate Invoice Due Date › Responses
OK
Update Invoice Overdue Process
Starts or stops the overdue process for the specified invoice.
The request body must include the ERP/invoice ID and the StopOverdue flag. A comment and the number of days to pause the process can optionally be included.
Update Invoice Overdue Process › Request Body
erpIdstopOverduecommentnumberOfDaysUpdate Invoice Overdue Process › Responses
OK
Get Customer Payment Risk Assessment
Returns a payment risk assessment for the specified customer based on invoice data in UtilityCloud.
The response includes overdue, dunned, and loss invoice counts and amounts.
The CreditCheckPassed flag indicates whether the customer has breached any of the payment thresholds configured for the tenant.
Get Customer Payment Risk Assessment › Responses
Success
numberOfOverdueInvoicesNumber of invoices past their due date and still unpaid.
amountOfOverdueInvoicesTotal amount outstanding across all overdue invoices.
numberOfDunnedInvoicesNumber of invoices sent to debt collection.
numberOfLossInvoicesNumber of invoices written off as a loss, meaning the company no longer expects to recover the amount.
amountOfLossInvoicesTotal amount written off across all loss invoices.
creditCheckPassedIndicates whether the customer has breached the tenant's configured payment history thresholds. False means the customer has overdue, dunned, or written-off invoices that exceed the configured limits.
Search Invoices
Returns a paginated list of invoices matching the specified search criteria. Results can optionally be sorted with the newest invoices first.
query Parameters
pageThe page number to retrieve. The first page is 1.
sizeThe number of results per page.
Search Invoices › Request Body
startRowendRowcustomerGuidaccountGuidcustomerNamecustomerIdentificationNumberdueDateFromdueDateToinvoiceDayFrominvoiceDayTodistributionDayFromdistributionDayToinvoiceNumberFromcustomerNumberFromdistributionStatusdistributionChannelinvoiceStatusoverdueStatusamountFromamountTodirectDebitisCreditaccountingPointIdupdatedFromUtcSearch Invoices › Responses
Success
erpIdcustomerGuidcustomerNamecustomerType0 (Private), 1 (Corporate).
accountGuidinvoiceNumberisCreditcreditCommenterpIdCanceledisCanceledcustomerIdentificationNumbercurrencyinvoiceDatetimestampUtcdueDateoriginalDueDateinvoiceStatus0 (Unknown), 1 (InProcessing), 2 (Sent), 5 (Partial), 6 (Paid), 7 (Closed), 9 (Reminder), 10 (Dunned), 15 (Loss), 16 (PaymentLoss), 17 (PartialLoss), 20 (Draft).
distributionDatedistributionChanneldistributionLogdistributionStatus0 (Unknown), 10 (Initialized), 20 (New), 30 (Sent), 40 (Trying), 50 (Failed), 60 (Rejected), 70 (NotToBeDistributed).
overDueStatus0 (Unknown), 1 (Loss), 2 (NextInvoice), 3 (Alert), 5 (Reminder), 6 (Debt), 7 (DebtResolved), 10 (Dunned).
statusMessageotherPayeraccountPeriodtotalAmountIncVatinvoicedAmountIncVatrestAmounttotalVatAmountprintFeecustomerNumberdirectDebitreminderRestAmountreminderTotalAmountjournalEntryIdstopRemindersstopInterestsentNotificationsentNotificationUtcperiodStartperiodEndcreatedpaidlastPaymentDatelossclosedOutconsumptionfirstInvoicereminderStepdebtCaseIddebtCaseUrldebtCaseCommentdebtCaseDate