Bitta Apps

Bitta Commission reference

API reference

Reference for the Bitta Commission API pages and queries, the insert-only commissionSourceEvents endpoint, the three subscribable events and public codeunits.

updated: applies-to: 1.1.2.0

This reference lists every integration surface that Bitta Commission provides: the Business Central API pages and API queries, the one endpoint that accepts data, the events other extensions can subscribe to, the public codeunits and the permission set for integration users. The integration surface is deliberately narrow. Use it to report on commission data and to stage external sales events; configuration happens in the Business Central pages described in the guide.

Endpoint basics

Every endpoint uses the same API route:

Property Value
API publisher bittaApps
API group commission
API version v1.0
Key id (the record SystemId)

Build the URL from your tenant, environment and company:

GET https://api.businesscentral.dynamics.com/v2.0/{tenant}/{environment}/api/bittaApps/commission/v1.0/companies({companyId})/commissionEarnings

NOTE

The Bitta Commission APIs are read-only except commissionSourceEvents, which is insert-only. No endpoint modifies or deletes Bitta Commission data.

API pages for reading data

These 12 API pages have InsertAllowed, ModifyAllowed and DeleteAllowed set to false.

Entity set Page Source Access rule
commissionParticipants 73570720 Participants Filtered to the caller's reporting scope.
commissionPlans 73570721 Commission plans All plans.
commissionPlanVersions 73570722 Plan versions All plan versions.
commissionEarnings 73570723 Earning entries Filtered to the caller's reporting scope.
commissionBalances 73570724 Balance entries Filtered to the caller's reporting scope.
commissionSettlements 73570725 Settlement headers Filtered to the caller's reporting scope.
commissionSettlementLines 73570726 Settlement lines Filtered to the caller's reporting scope.
commissionStatements 73571238 Statements Filtered to the statements the caller may see.
commissionDisputes 73571234 Disputes Filtered to the disputes the caller may see.
commissionPostingProposals 73570612 Posting proposals Finance-wide access required.
commissionPostingProposalLines 73570613 Posting proposal lines Finance-wide access required.
commissionAccountingEntries 73570611 Accounting entries Finance-wide access required.

A caller without finance-wide access receives BAA-FINANCE-SCOPE, for example "Finance-wide access is required to read commission accounting entries." Reads of participants, plans, plan versions, earnings, balances, settlements, settlement lines and the four API queries are recorded as export evidence, with the entity set, filters, row count and high-water mark. Review them on Commission Export Evidence.

Fields per entity set

Entity set Fields
commissionParticipants id, participantId, number, displayName, participantType, status, defaultCurrencyCode, languageCode, countryRegionCode, externalId, lastModifiedAt, rowVersion
commissionPlans id, planId, code, description, status, defaultCurrencyCode, defaultCalendarCode, allowMultipleAssignments, reviewDate, lastModifiedAt, rowVersion
commissionPlanVersions id, planId, versionNumber, versionId, effectiveFrom, effectiveTo, status, definitionHash, publishedAt, activatedAt, lastModifiedAt, rowVersion
commissionEarnings id, entryNumber, participantId, planVersionId, componentId, periodId, businessDate, finalEarningAmount, deltaAmount, currencyCode, commissionModel, currentBaseValue, baseUnitCode, resolvedRate, correctionRootId, correctionSequenceNumber, runId, sourceFactId, entryHash, lastModifiedAt, rowVersion
commissionBalances id, entryNumber, participantId, earningEntryId, eligibilityEntryId, periodId, businessDate, fromBucket, toBucket, signedAmount, currencyCode, settlementHeaderId, settlementLineId, holdId, holdReasonCode, disputeId, correctionRootId, entryHash, lastModifiedAt, rowVersion
commissionSettlements id, settlementId, number, periodId, settlementTypeCode, status, currencyCode, cutoffDate, asOfDate, selectedAmount, heldAmount, recoveryAmount, payableAmount, lineCount, frozenAt, frozenHash, approvedAt, closedAt, stateVersionNumber, lastModifiedAt, rowVersion
commissionSettlementLines id, settlementId, lineNumber, participantId, paymentMethod, currencyCode, selectedAmount, recoveryAmount, netAmount, holdReasonCode, payPeriodCode, firstBalanceEntryNumber, lastBalanceEntryNumber, frozenAt, lineHash, lastModifiedAt, rowVersion
commissionStatements id, statementId, number, participantId, periodId, versionNumber, status, currencyCode, earningAmount, eligibleAmount, heldAmount, recoveryAmount, settledAmount, generatedAt, approvedAt, deliveredAt, deliveryChannelCode, deliveryResultCode, lineCount, stateVersionNumber, statementHash, lastModifiedAt
commissionDisputes id, disputeId, number, participantId, statementId, statementLineNumber, financialScopeCode, categoryCode, priorityCode, status, requestedAmount, heldAmount, currencyCode, openedAt, dueAt, resolvedAt, closedAt, stateVersionNumber, evidenceHash, lastModifiedAt
commissionPostingProposals id, proposalId, number, eventScopeCode, status, settlementId, periodId, postingDate, postingDateRule, journalTemplateName, journalBatchName, sourceCode, currencyCode, exchangeRateDate, exchangeRateFactor, debitAmount, creditAmount, debitAmountLCY, creditAmountLCY, lineCount, authorityVersionNumber, predecessorProposalId, payloadHash, approvalEvidenceHash, createdAt, approvedAt, postedAt, stateVersionNumber, correlationId, lastModifiedAt
commissionPostingProposalLines id, proposalId, lineNumber, accountingEntryNumber, accountTypeCode, accountNumber, accountRoleCode, documentTypeCode, documentNumber, description, amount, amountLCY, currencyCode, dimensionSetId, dimensionPolicyCode, resolvedPostingDate, originalPostingDate, originalPeriodId, priorPeriodAdjustment, participantId, planVersionId, componentId, sourceFactEntryNumber, frozenAt, lineHash, correlationId, lastModifiedAt
commissionAccountingEntries id, entryNumber, postingDate, accountingEventType, accountRoleCode, glAccountNumber, signedAmount, amountLCY, processingCurrencyCode, exchangeRateDate, exchangeRateFactor, dimensionSetId, businessDate, originalPostingDate, originalPeriodId, priorPeriodAdjustment, sourceAccountingEntryNumber, deferredScheduleId, fringeLoadPercent, periodId, earningEntryId, settlementEntryId, settlementLineId, settlementHeaderId, sourceFactId, correctionRootId, correctionSequenceNumber, accountMappingId, accountingPolicyCode, accountingPolicyVersionNumber, dimensionPolicyCode, participantVersionNumber, engineVersion, hashSchemaVersion, entryHash, correlationId, lastModifiedAt

Example request and an abbreviated response row:

GET https://api.businesscentral.dynamics.com/v2.0/{tenant}/{environment}/api/bittaApps/commission/v1.0/companies({companyId})/commissionEarnings?$filter=businessDate ge 2026-09-01&$select=entryNumber,participantId,businessDate,finalEarningAmount,deltaAmount,sourceFactId
{
  "value": [
    {
      "entryNumber": 1042,
      "participantId": "6f1c2a7e-3b9d-4c51-9e0a-2d8b7f4a1c33",
      "businessDate": "2026-09-14",
      "finalEarningAmount": 125.5,
      "deltaAmount": 125.5,
      "sourceFactId": "0b7e5d21-8c4f-4a2e-b6d9-5f3a1e8c2d47"
    }
  ]
}

API queries for reporting

Four API queries join entries with participant, plan and period data for reporting tools such as Power BI. They are read-only by nature and filtered to the caller's reporting scope.

Entity set Query Fields
commissionEarningFacts 73570575 id, entryNumber, participantId, planVersionId, componentId, periodId, businessDate, finalEarningAmount, deltaAmount, currencyCode, commissionModel, currentBaseValue, baseUnitCode, correctionRootId, entryHash, lastModifiedAt, rowVersion, participantNumber, participantName, componentCode, planId, planVersionNumber, periodCode, periodStartDate, periodEndDate
commissionBalanceFacts 73570576 id, entryNumber, participantId, earningEntryId, periodId, businessDate, fromBucket, toBucket, signedAmount, currencyCode, settlementHeaderId, holdId, holdReasonCode, disputeId, entryHash, lastModifiedAt, rowVersion, participantNumber, participantName
commissionSettlementFacts 73570577 id, entryNumber, settlementHeaderId, settlementLineId, balanceEntryId, participantId, periodId, businessDate, settlementStatus, selectedAmount, exportedAmount, paidAmount, rejectedAmount, remainingAmount, currencyCode, actualPayDate, paymentReference, exportBatchId, entryHash, lastModifiedAt, rowVersion, settlementNumber, settlementDocumentStatus, participantNumber, participantName
commissionStatementFacts 73570578 id, statementId, number, participantId, periodId, versionNumber, status, currencyCode, earningAmount, eligibleAmount, heldAmount, recoveryAmount, settledAmount, generatedAt, deliveredAt, lineCount, statementHash, lastModifiedAt, rowVersion, participantNumber, participantName, periodCode, periodStartDate, periodEndDate

The commissionSourceEvents staging endpoint

commissionSourceEvents (page 73570871) is the only endpoint that accepts data. It is insert-only: InsertAllowed is true, and ModifyAllowed and DeleteAllowed are false. Each POST stages one external event, which then passes the same late data, data quality and acceptance steps as other non-native rows. See External sources.

Before you post events:

  1. Turn on External Events Enabled on Commission Source Capture Setup. Otherwise every insert is refused with BAA-SRC-EXT-DISABLED.
External sources group on Commission Source Capture Setup with External Events Enabled switched on for the commissionSourceEvents endpoint
External Events Enabled must be on before events can be staged.
  1. Assign the Bitta Commission Integration permission set to the integration user.
Field Rule
sourceSystemCode Required. Upper-cased. Codes starting with NATIVE- are refused (BAA-SRC-EXT-RESERVED).
idempotencyKey Required (BAA-SRC-EXT-KEY). Identifies the event within its source system and schema version.
sourceFactTypeCode Required (BAA-SRC-EXT-TYPE), for example EXTERNAL-TRANSACTION, MANUAL-ADJUSTMENT or SUBSCRIPTION-EVENT.
businessDate, postingDate At least one is required (BAA-SRC-EXT-DATE). A missing one takes the value of the other.
sourceEventTypeCode Defaults to IMPORTED.
providerCode, schemaVersion Default to EXTERNAL and EXT-1.
sourceCurrencyCode, sourceExchangeRateFactor A foreign currency event needs a positive exchange rate factor (BAA-SRC-EXT-CURRENCY). Blank currency uses factor 1.
payloadHash Optional. If supplied it must be a 64-character SHA-256 hex value (BAA-SRC-EXT-HASH); otherwise it is calculated.
attributes Optional. A JSON object of attribute code to value, sent as a string. Codes are upper-cased; numbers and true/false keep their type.
rawPayloadReference Optional storage reference. It must not contain a signature, token, key or password (BAA-SRC-EXT-PAYLOAD-REF).
batchReference Optional. Defaults to the idempotency key.

The other writable fields are externalEventId, eventAt, documentDate, sourceSystemRecordId, sourceDocumentTypeCode, sourceDocumentNo, sourceDocumentLineNo, customerNo, vendorNo, contactNo, itemNo, variantCode, resourceNo, projectNo, serviceItemNo, salespersonCode, externalOwnerId, locationCode, responsibilityCenterCode, territoryCode, storeCode, registerCode, quantity, baseQuantity, unitCode, weight, duration, points, grossAmount, discountAmount, netAmount, taxAmount, expectedCostAmount, actualCostAmount, sourceExchangeRateDate, inclusionStatusCode, inclusionReasonCode, originalExternalEventId, correctionTypeCode and correctionReasonCode. A quantity needs a unitCode. The fields id, status, resultCode, validationErrorCode, validationMessage, appliedSourceFactId, batchId, lineNo and correlationId are read-only.

POST https://api.businesscentral.dynamics.com/v2.0/{tenant}/{environment}/api/bittaApps/commission/v1.0/companies({companyId})/commissionSourceEvents
Content-Type: application/json
{
  "sourceSystemCode": "POS",
  "idempotencyKey": "POS-STORE12-20261005-000981-1",
  "sourceFactTypeCode": "EXTERNAL-TRANSACTION",
  "businessDate": "2026-10-05",
  "sourceDocumentNo": "000981",
  "sourceDocumentLineNo": 1,
  "customerNo": "10000",
  "itemNo": "1896-S",
  "salespersonCode": "JO",
  "storeCode": "STORE12",
  "quantity": 2,
  "unitCode": "PCS",
  "netAmount": 1250.0,
  "attributes": "{\"CHANNEL\":\"STORE\"}"
}

The acceptance result is one of these codes:

Result Meaning
ACCEPTED A new source fact was created.
DUPLICATE-IDENTICAL An identical source fact already exists. No second fact is created.
REJECTED-CONFLICT The event key already exists with different source evidence.
HELD The row is held for review, for example by a late data policy.
EXCLUDED The row is excluded by its inclusion status.
INVALID The row failed validation; see validationErrorCode and validationMessage.

Held and invalid rows are worked on Commission Source Review.

Events other extensions can subscribe to

Three events are published for other extensions. Each passes the same nine parameters: ContractVersion: Integer; OperationId: Guid; CompanyId: Guid; EntityId: Guid; EntityVersion: BigInteger; OccurredAt: DateTime; CorrelationId: Guid; EvidenceHash: Text[64]; OutcomeCode: Code[50]. All three are isolated, so an error in a subscriber does not roll back the Bitta Commission operation.

Event Publisher codeunit Raised when
OnPlanVersionPublishedV1 "BAA Comm Plan Mgt." (73570700) A plan version is published, after the commit. OutcomeCode is PUBLISHED.
OnImplementationAppliedV1 "BAA Commission Feature Mgt." (73570576) ApplyImplementationV1 completes. OutcomeCode is APPLIED.
OnSetupReadinessEvaluatedV1 "BAA Commission Feature Mgt." (73570576) EvaluateReadinessV1 runs. OutcomeCode is READY or BAACOMM-PUB-INPUT-PATH-001. 
codeunit 50100 "Commission Event Handler"
{
    [EventSubscriber(ObjectType::Codeunit, Codeunit::"BAA Comm Plan Mgt.", 'OnPlanVersionPublishedV1', '', false, false)]
    local procedure HandlePlanVersionPublished(ContractVersion: Integer; OperationId: Guid; CompanyId: Guid; EntityId: Guid; EntityVersion: BigInteger; OccurredAt: DateTime; CorrelationId: Guid; EvidenceHash: Text[64]; OutcomeCode: Code[50])
    begin
        // EntityId is the published plan version ID.
    end;
}

All other event publishers in Bitta Commission are local or internal and cannot be subscribed to by other extensions.

Public codeunits

Three codeunits have Access = Public. Their public procedures are versioned with a V1 suffix.

Codeunit Public procedures
"BAA Commission Feature Mgt." (73570576) GetContractVersionV1, EvaluateReadinessV1(PathCode, Diagnostics), ApplyImplementationV1(ImplementationId, IdempotencyKey, ExpectedSystemRowVersion)
"BAA Comm Plan Mgt." (73570700) ValidateVersionV1, SubmitVersionV1, PublishVersionV1, SuspendVersionV1, CreateSuccessorV1
"BAA Comm Organization Mgt." (73570627) PrepareCalendarProrationV1, PrepareWorkingProrationV1, ProrateV1

The public procedures apply the same rules as the pages. SubmitVersionV1 submits a valid Draft plan version and creates its approval request. PublishVersionV1 only publishes a version whose status is Approved and whose definition matches the approved request. ApplyImplementationV1 needs an idempotency key and an implementation in Ready status. EvaluateReadinessV1 accepts the implementation path codes SIMPLE_PERCENTAGE, DISTRIBUTION_MARGIN, CASH_COLLECTED, QUOTA_TIER, EXTERNAL_AGENT, SUBSCRIPTION_RECURRING, SERVICE_PROJECT, RETAIL_POS and ADVANCED_ENTERPRISE.

Integration permission set

The Bitta Commission Integration permission set (BAA Comm Integration, 73570578) is assignable. It gives full access to source batches and source staging, read access to source facts and source attributes, and execute permission on "BAA Commission Feature Mgt.". It also includes the accounting, sources, organization and reporting extension sets and the sources edit set, so the integration user can maintain source setup, import mappings, G/L source rules and recurring contracts. See Permission sets.

What the integration surface does not include

  • No endpoint changes plans, participants, earnings, statements, settlements or postings.
  • No ready-made connectors to third-party systems. The staging endpoint is the documented entry point for integrations you build.
  • Statements are delivered inside Business Central, and payroll is handled by a file-based payroll-ready export. See Payroll-ready export and Known limitations.
// next step

Ready to try Bitta Commission?

Request a 30-day trial codeTalk to us