Bitta Subscriptions reference
APIs and events
The Bitta Subscriptions API pages and actions, the errors, the integration and business events, webhooks for contract and device events, and Microsoft's APIs.
updated: applies-to: 1.3.5.0
Bitta Subscriptions publishes API pages for its lifecycle records and raises an event after every lifecycle action, so
CRM, e-commerce, data warehouse and workflow tools can read the lifecycle and start changes. Microsoft's own Subscription
Billing APIs (publisher microsoft, group subsBilling) stay the way to read contracts, subscriptions, lines and
billing; Bitta Subscriptions does not duplicate them.
Endpoint
/api/bittaApps/subscriptions/v1.0/companies({id})/<entity set>
Authenticate as for any Business Central API (Microsoft Entra ID, OAuth 2.0); the user or app needs the Bitta Subscriptions permission sets and, for writes, a licensed seat.
Conventions
- Names. Entity sets are plural and entities singular, in camelCase (
amendments,amendment). Field names are camelCase and spell words out:...Numberfor a number,...Codefor a code,...Datefor a date,...DateTimefor a date and time,numberOf...for a count,...Percentfor a percentage,...LCYfor an amount in local currency. - Keys. Every entity is keyed by
id, the record's SystemId, and haslastModifiedDateTime.contracts,subscriptionHeadersandsubscriptionLinesshare the id of Microsoft'scustomerContracts,serviceObjectsandserviceCommitments, so a client joins the two APIs onid. The one exception islifecycleEvents, a history that is built per request: it is keyed byentryNumberand has no id. - ETags. Every entity except
lifecycleEventsreturns@odata.etag. Send it inIf-Matchwith PATCH and DELETE. - Enum values are Business Central's enum names, with a space written as
_x0020_(for exampleSpecific_x0020_Date). - Read-only fields. Calculated fields and the fields an action sets are read-only. The fields of a POST request
that are not part of the record (for example
subscriptionNumberof an amendment) read back blank: the created record and its lines show what happened. - Bound actions are called with POST on
.../<entity set>({id})/Microsoft.NAV.<action>. Action names begin with a lower-case letter (resume,transferDevices,preview). Parameters go in a JSON body; every parameter is optional unless the table says otherwise, and a blank date means the date the page in Business Central would propose. An action without parameters takes an empty body. - Errors. A refused request answers HTTP 400 with Business Central's error body:
{"error": {"code": "...", "message": "..."}}. The message is the one a user sees in Business Central. A check that finds several problems lists all of them in one message, one per line, so a client can fix them in one go. A refused write writes nothing.
Entity sets
| Entity set | Read | Write |
|---|---|---|
amendments (+ amendmentLines) |
yes | POST changes one plan group: seats, plan, and add-ons (below); bound actions apply, cancel |
holds (+ holdLines) |
yes | POST places a hold on a contract or one subscription; bound actions resume (optional resumeDate), cancel |
terminations |
yes | POST terminates a contract or one subscription; bound action reopen |
contracts (+ lifecycleEvents) |
yes: Bitta Subscriptions' fields and lifecycle status of a contract | bound action transferDevices |
subscriptionHeaders (+ subscriptionLines), subscriptionLines |
yes: Bitta Subscriptions' fields, lifecycle status, serial number, trial, bundle | no |
devices (+ deviceIdentifiers) |
yes | bound actions activate, swap, transfer, processReturn, deactivate, setIdentifier |
deviceIdentifiers |
yes | POST, PATCH identifierValue, DELETE (below) |
oneTimeCharges |
yes | POST adds a charge; bound action cancel |
billingOperations |
yes | POST moves a subscription (type Move) or invoices now (type Invoice_x0020_Now) |
renewals |
yes | bound action recordAnswer |
escalationEntries, promotionRedemptions, renewalNotices |
yes | no |
catalogItems (+ catalogRules, priceTiers, bundleComponents) |
yes | no |
resellers, resellerStatements |
yes | no |
lifecycleEvents |
yes, with $filter=contractNumber eq '...' |
no |
installmentPlans (+ installmentLines), contractMilestones |
yes | see Installments and milestones |
prepaidBalances (+ prepaidEntries) |
yes | see Prepaid balances |
revenueAllocations, performanceObligations, revenueScheduleLines, standaloneSellingPrices |
yes | see Revenue recognition |
migrationBatches (+ migrationLines) |
yes | POST, PATCH and DELETE; bound actions preview and migrate (Migration kit) |
Writes
A write runs the same engine as the wizard or page in Business Central, with the same license check, the same checks and the same errors. Confirmations are never asked.
Holds and terminations
POST holdswithcontractNumber,holdFrom, and optionallyresumeOn,reasonCode,extendTerm,descriptionandsubscriptionNumber(only that subscription and its add-ons). The response is the created hold.holds({id})/Microsoft.NAV.resumeresumes on the date the hold page proposes, or on the date in the body{"resumeDate": "2026-12-15"}.POST terminationswithcontractNumber,effectiveDate, and optionallysettlement,feeMethod,feeValue,reasonCode,descriptionandsubscriptionNumber.
Amendments: seats, plans and add-ons
POST amendments names one subscription of a plan group in subscriptionNumber and any of these changes, which are
made together in one amendment:
| Field | Change |
|---|---|
newQuantity |
The new quantity of subscriptionNumber: the plan or an add-on |
newPlanItemNumber |
A new plan for the plan subscription; add-ons that the new plan does not allow end with it |
removeAddOn |
true ends the add-on subscriptionNumber on the effective date; not with newQuantity or newPlanItemNumber |
addOnItemNumber, addOnQuantity |
Adds an add-on of the catalog to the group (addOnQuantity defaults to 1), co-termed with the plan |
timing |
Immediately, Next_x0020_Billing_x0020_Date, End_x0020_of_x0020_Term or Specific_x0020_Date (with effectiveDate); blank = the setup's timing |
description |
The description of the amendment |
Charges and credits for days that are already billed are prorated exactly as in the amendment wizard; each line's
estimatedAmount shows them. The amendment applies at once when its date has come, is scheduled for the daily job
when the date is later, or waits for approval when an approval rule applies. Examples:
POST amendments {"subscriptionNumber": "SUB000101", "addOnItemNumber": "ADDON-STORAGE", "addOnQuantity": 5}
POST amendments {"subscriptionNumber": "SUB000102", "removeAddOn": true, "timing": "Next_x0020_Billing_x0020_Date"}
POST amendments {"subscriptionNumber": "SUB000102", "newQuantity": 15, "timing": "Immediately"}
Devices
contracts({id})/Microsoft.NAV.transferDevicesmoves several devices of the contract to another contract in one call:serialNumbers(required; separated by commas),newContractNumber(required),newCustomerNumber(blank = the customer of that contract),transferDate(blank = the work date),reasonCode. It is one run of the Transfer Devices wizard: one quantity change per service subscription on each side, with a credit and a charge for billed days. Every device and the locks of both contracts are checked first; the answer lists the problem of each device with its serial number, and then nothing moves.devices({id})/Microsoft.NAV.transfermoves one device;swap,processReturn,deactivate,activateandsetIdentifierwork on the device of the call.deviceIdentifierstakes an asset tag, a MAC address, an IMEI, a SIM number, a vehicle number (VIN) or any identifier type of Device Identifier Types, with the rules of Load Identifiers: only on a device in use (active or awaiting activation), with a known type, a value that is not blank, and a value of a unique type on one device in use only.POST devices({id})/deviceIdentifiers {"identifierTypeCode": "ASSET-TAG", "identifierValue": "AT-1042"}adds an identifier of a type the device has no value of yet (alsoPOST deviceIdentifierswithdeviceEntryNumber).PATCH deviceIdentifiers({id}) {"identifierValue": "..."}corrects the value. The device and the type cannot change: delete the identifier and add one of the right type.DELETE deviceIdentifiers({id})removes a wrong identifier.
Events
After each change is written, Bitta Subscriptions raises an integration event in AL and an external business event:
| Moment | Integration event | Business event |
|---|---|---|
| Amendment applied | OnAfterAmendmentApplied |
amendmentApplied |
| Hold placed | OnAfterHoldPlaced |
holdPlaced |
| Hold resumed | OnAfterHoldResumed |
holdResumed |
| Termination finished | OnAfterTerminationApplied |
terminationApplied |
| Termination reopened | OnAfterTerminationReopened |
terminationReopened |
| Renewal notice sent | OnAfterRenewalNoticeSent |
renewalNoticeSent |
| Price increase applied | OnAfterPriceIncreaseApplied |
priceIncreaseApplied |
| Promotion redeemed | OnAfterPromotionRedeemed |
promotionRedeemed |
| Reseller statement posted (payout created) | OnAfterResellerStatementPosted |
resellerStatementPosted |
| Devices transferred | OnAfterDevicesTransferred |
devicesTransferred |
Integration events are in the public codeunit BAA Subscr. Integration Events; extensions subscribe to them. Business events are in the category Bitta Subscriptions, so Power Automate ("When a business event occurs"), Dataverse and webhooks can subscribe. They are sent when the transaction commits; a change that is rolled back sends nothing. Business events are a preview feature of Business Central. The full list of events is in the extensibility guide for partners.
Webhooks
A webhook sends signed messages to an HTTPS address of another system, such as a CRM, a customer portal, a data warehouse or a provisioning platform, when something happens to a contract or, in companies that sell devices, to a device. Every subscription business can use the contract events; the device events appear only with Sell Devices (Device register).
| Event | Sent when | event |
Effective date |
|---|---|---|---|
| Contract Started | the first subscription line is assigned to a customer contract | contractStarted |
the line's start date |
| Contract Amended | an amendment (seats, upgrade, downgrade, add-on) takes effect | contractAmended |
the amendment's effective date |
| Hold Started | a hold is placed on a contract or some of its subscriptions | holdStarted |
Hold From |
| Hold Ended | a held contract or subscription is resumed | holdEnded |
the resume date |
| Contract Terminated | a termination is applied | contractTerminated |
the termination's effective date |
| Contract Renewed | a posted renewal order renews lines of the contract (one message per contract and order) | contractRenewed |
the start of the new term |
| Device Shipped, Activated, Swapped, Returned, Transferred | see Device register | deviceShipped, ... |
the date of the change |
To set up a webhook:
- Search for Webhooks, and choose New.
- Enter a Code, a Description and the URL. It must be an HTTPS address that the internet can reach. Addresses of the local network, loopback addresses and plain HTTP are refused.
- Enter a Signing Secret of at least 16 characters. It is stored encrypted and never shown again. Every message is
signed with it (HMAC-SHA256 of the body in the
X-Bitta-Signatureheader), so the receiver can check that it comes from you. - In Contract Events (and Device Events), choose what the webhook receives. New webhooks receive every event.
- Choose Send Test Message. The receiver's answer is shown, and nothing is logged.
- Turn on Enabled. This schedules the job queue entry that sends the messages every few minutes.
A message is written in the same transaction as the change, so a change that is rolled back sends nothing. The job sends the due messages of each webhook and event in batches of up to 100, in one JSON body:
{
"event": "holdStarted",
"deliveryId": "4b0c...",
"sentAt": "2026-11-15T10:05:00Z",
"company": "CRONUS USA, Inc.",
"contracts": [
{
"event": "holdStarted",
"eventDate": "2026-12-01",
"contractId": "9f3e...",
"contractNumber": "CUC000123",
"customerNumber": "10000",
"documentNumber": "HLD000017",
"subscriptionNumbers": ["SUB000101", "SUB000102"],
"messageId": 4711
}
]
}
Device events list their devices under devices instead, with the serial number, item, status, identifiers and, for a
swap or a transfer, the unit and contract before it. The headers X-Bitta-Event and X-Bitta-Delivery name the event
and the batch.
Webhook Messages lists every message with its Event, Contract No., Source Document No., Status
(Pending, Sent or Failed), Attempts, Next Attempt At, Last HTTP Status and Last Error.
Failed deliveries are retried after 1, 5, 15, 60 and 240 minutes. When every retry has failed, the message is
Failed and counts in the Failed Webhook Messages cue: fix the receiver, select the messages and choose
Retry. Show Payload shows the JSON the receiver gets; each message has a messageId, so the receiver can
recognize a message that arrives twice. Send Pending Messages Now sends without waiting for the job queue.
Limits
lifecycleEventsis built per request and needs a contract filter.- One
POST amendmentsadds one add-on. A group with a scheduled amendment takes no second one, so add several add-ons on a later date in one amendment in Business Central. transferDevicesmoves devices of one contract; transfer the devices of each contract with its own call.- Device identifiers through the API are set one at a time; many devices load faster with Load Identifiers.
- Webhooks are set up in Business Central only; the API has no webhook endpoint. A webhook sends a contract event when Bitta Subscriptions or Microsoft's contract renewal makes the change; a contract line that is deleted or edited directly sends nothing.
- The automatic term extension of evergreen lines by Microsoft's daily job has no event, so it sends no Contract Renewed.