Historic payables data
APHistoricalData provides accounts payable history by company, branch, account, subaccount, currency, supplier and financial period. The APHistoricalData query and APHistoricalData type are available in the GraphQL reference for the schema contract.
Availability depends on deployment and the required historical backfills. Seeing the API model in the schema does not activate the ETL or confirm that supplier history is populated.
Keys and balances
Each AP history row is identified by these fields:
| Dimension | Field |
|---|---|
| Company | companyId |
| Branch | branchId |
| Account | accountId |
| Subaccount | subaccountId |
| Currency | currencyId |
| Supplier | supplierId |
| Financial period | finPeriodId |
Financial periods use the ERP YYYYPP format. PP is the configured financial-period number, so it must not be treated as a calendar month without checking the company's financial-period setup.
beginningBalance and endingBalance are base-currency values. beginningBalanceInCurrency and endingBalanceInCurrency are the corresponding values in the currency identified by currencyId. revaluedGainLoss is supplied in base currency only; there is no corresponding revaluedGainLossInCurrency field.
An AP history row is a snapshot for its selected financial period. Its ending balance is the balance at that period's end, not a current balance after later activity. For example, in a single currency, a year-end row with a beginning balance of 100000 and a reduction of 10000 can show 100000 - 10000 = 90000. This illustrates the period snapshot only; it does not define sign handling or establish parity with a complete ERP report.
Open prepayments
Visma.net ERP keeps released prepayments that are not yet applied outside the supplier balance: endingBalance does not include them, and the rows of a prepayment account show 0 there. Their amount is in endingPrepaymentBalance (base currency) and endingPrepaymentBalanceInCurrency (the currency identified by currencyId). A positive value is an open prepayment to the supplier. When the prepayment is applied, the amount moves out of these fields.
The supplier balance that ERP reports such as AP630500 show is endingBalance - endingPrepaymentBalance, and the same with the InCurrency fields.
Periods without a row
ERP writes an AP history row only for a period with activity, so a supplier has no row for a period in which nothing was posted. Balances for every period describes a query that returns the missing periods for you. To read a balance for period P yourself, take the latest row at or before P with the same companyId, branchId, accountId, subaccountId, currencyId and supplierId (the key without finPeriodId). Its endingBalance and endingPrepaymentBalance apply until the next row for that key. The lookup includes branchId: a supplier with activity in two branches has two independent series.
Balances that do not carry over
DataMart returns the AP history exactly as Visma.net ERP stores it. In rare cases the ERP history of a supplier is inconsistent: a period's beginningBalance does not equal the endingBalance of the previous row with the same companyId, branchId, accountId, subaccountId, currencyId and supplierId (the key without finPeriodId), and the later balances differ from the general ledger. The carried periods of Balances for every period then repeat that difference. To repair it, run Validate Supplier Balances (AP509900) in Visma.net ERP for the affected supplier, starting from the first period that does not match. The corrected rows reach DataMart as updated rows, so read them through updatedInDataMartDateTime like any other change.
Updates and deletions
History rows are not deleted, so the AP history query has no includeDeleted argument and the APHistoricalData type has no deletedDatabaseRecord field. A company's history is removed only when the company itself is removed from DataMart. Rows are not immutable: a release, a revaluation or a balance validation in ERP updates the period's row and later rows in place. Read changes through updatedInDataMartDateTime, as described in Incremental fetching, and overwrite the stored row by its key.
The query accepts cursor and update-window arguments, not a where argument. For example, this page request selects the complete history key and balance fields:
query APHistoryPage(
$lastId: String
$updatedInDataMart: DateTime
$updatedInDataMartTo: DateTime
$pageSize: Int! = 5000
) {
apHistoricalData(
lastId: $lastId
updatedInDataMart: $updatedInDataMart
updatedInDataMartTo: $updatedInDataMartTo
pageSize: $pageSize
) {
companyId
branchId
accountId
subaccountId
currencyId
supplierId
finPeriodId
beginningBalance
endingBalance
beginningBalanceInCurrency
endingBalanceInCurrency
revaluedGainLoss
endingPrepaymentBalance
endingPrepaymentBalanceInCurrency
}
}
The authorized request context supplies the company scope. companyId is returned as part of each history key; it is not a query argument.
Balances for every period
The apHistoricalDataForwardByGroup query fills in the periods without a row for you. It returns one row per financial period for each group (branch, account, subaccount, currency and supplier), from the group's first period with activity up to periodsUpTo. Without periodsUpTo the series runs to the current open financial period; when the company's financial calendar does not reach the current date yet, it runs to the latest period the calendar defines, so the last row is then not today's balance. Pass periodsUpTo to set the end yourself. The periods follow the company's financial calendar, including an adjustment period where the calendar has one, and continue across year ends: AP balances do not reset at the end of a fiscal year.
hasActivityistruefor a period that has an ERP history row. That row is returned unchanged.- A period with
hasActivity: falseis carried forward from the last period with activity:beginningBalanceequalsendingBalance(the previous ending balance), the same applies to theInCurrencyfields,endingPrepaymentBalanceis carried as it is, andrevaluedGainLossis0. It returns theidof the row it is carried from. - No rows are returned before a group's first period with activity.
Nothing is stored for the carried periods: they are calculated when you read, so a back-dated release or a balance validation in ERP is reflected on the next read.
The query is paginated by group. pageSize is the maximum number of groups (default and maximum 1000), and every group on a page is complete. Read lastGroupKey and hasMore from the response and pass lastGroupKey back to get the next page; continue until hasMore is false.
With updatedInDataMart, only groups that have a row updated after that time are returned, each starting at its earliest changed period. The balance carried into that period still comes from the earlier rows. A group with no new row is not returned, so after a new financial period opens, fetch all groups again, or extend your own series to the new period.
A periodsUpTo that is not a period of the company's financial calendar is rejected with an INVALID_ARGUMENT error, and a company without a financial calendar gets an error instead of data.
query APHistoryByPeriod($lastGroupKey: String, $periodsUpTo: String) {
apHistoricalDataForwardByGroup(lastGroupKey: $lastGroupKey, periodsUpTo: $periodsUpTo) {
lastGroupKey
hasMore
items {
branchId
accountId
subaccountId
currencyId
supplierId
finPeriodId
hasActivity
beginningBalance
endingBalance
endingPrepaymentBalance
revaluedGainLoss
}
}
}
Relating history to documents and applications
AP history is sourced from CuryAPHistory. To relate supplier documents and payment applications, keep the company in every join.
Supplier documents
The natural key of a supplierDocuments record is:
companyId + documentType + referenceNumber
The four document fields to read from the linked supplier document are released, voided, prebooked and installmentCntr.
Supplier payments
The natural key of a supplierPayments record is:
companyId + documentType + refNbr
It matches the payment side of a payment line: documentType = paymentDocType and refNbr = paymentRefNbr, within the same companyId.
Supplier payments expose five header fields for historic payables:
| Field | Meaning |
|---|---|
paymentDate | The document date of the payment. |
financialPeriod | The financial period the payment was posted in, in the YYYYPP format. |
branchId | The ID of the branch. |
paymentAmountInBaseCurrency | The payment amount in the company's base currency. The existing paymentAmount stays in the payment's document currency. |
voided | Indicates if the payment has been voided. |
financialPeriod is the payment's own financial period. It is nullable: it is always set for active payments, but a deleted payment that was removed from ERP before the field was introduced returns null. It differs from the existing applicationPeriod and applicationDate fields, which describe the application. Those two are also nullable: they are always set for active payments, but a deleted payment whose payment record was removed in ERP returns null.
Payment applications
On supplierPaymentLines, link the adjusted supplier document with the exact keys:
| Supplier document | Supplier payment line |
|---|---|
companyId | companyId |
documentType | invoiceDocType |
referenceNumber | invoiceRefNbr |
The full natural key of a supplier payment-line application is companyId + paymentDocType + paymentRefNbr + invoiceDocType + invoiceRefNbr + adjNbr. The payment side is paymentDocType + paymentRefNbr; the adjusted-document side is invoiceDocType + invoiceRefNbr; and adjNbr identifies the individual application.
The ten application fields are released, voided, postPeriodId, amountApplied, amountAppliedInCurrency, cashDiscountApplied, cashDiscountAppliedInCurrency, withholdingTaxApplied, withholdingTaxAppliedInCurrency and voidAdjNbr. postPeriodId is the financial period of the application. It matches postPeriod on the payment lines of the Visma.net REST API supplierPayment endpoint, and has the same value as applicationPeriod. It is nullable: it is always set for active lines, but a line that has not been backfilled yet, or a deleted line that was removed from ERP before the field was introduced, returns null.
The ...InCurrency application amounts belong to the adjusted document's currency. The corresponding fields without InCurrency are base-currency amounts. For the adjusted document's own financial period, read financialPeriod on the linked supplier document.
Currencies, dates and voids on a payment line:
amountApplied,cashDiscountApplied,withholdingTaxAppliedandrgolAmtare in base currency.rgolAmtis the realized exchange gain or loss of the application.amountPaidis in the payment currency, so for a cross-currency payment it differs fromamountAppliedInCurrency.dateis the application date.applicationPeriodandpostPeriodIdare both the financial period of that date.- Voiding a payment creates a voiding application for each original one. Once the voiding application is released, both the original and the voiding line are
releasedandvoided, each with its owndate. On the voiding line,voidAdjNbrholds theadjNbrof the original application.
Aggregate AP history at the intended reporting grain before joining currency slices or raw supplier documents and applications. A one-to-many join before aggregation can repeat the same base balance, so do not multiply base balances by joining those rows to history before aggregating.