Skip to content
Bitta Apps

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: ...Number for a number, ...Code for a code, ...Date for a date, ...DateTime for a date and time, numberOf... for a count, ...Percent for a percentage, ...LCY for an amount in local currency.
  • Keys. Every entity is keyed by id, the record's SystemId, and has lastModifiedDateTime. contracts, subscriptionHeaders and subscriptionLines share the id of Microsoft's customerContracts, serviceObjects and serviceCommitments, so a client joins the two APIs on id. The one exception is lifecycleEvents, a history that is built per request: it is keyed by entryNumber and has no id.
  • ETags. Every entity except lifecycleEvents returns @odata.etag. Send it in If-Match with PATCH and DELETE.
  • Enum values are Business Central's enum names, with a space written as _x0020_ (for example Specific_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 subscriptionNumber of 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 holds with contractNumber, holdFrom, and optionally resumeOn, reasonCode, extendTerm, description and subscriptionNumber (only that subscription and its add-ons). The response is the created hold.
  • holds({id})/Microsoft.NAV.resume resumes on the date the hold page proposes, or on the date in the body {"resumeDate": "2026-12-15"}.
  • POST terminations with contractNumber, effectiveDate, and optionally settlement, feeMethod, feeValue, reasonCode, description and subscriptionNumber.

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.transferDevices moves 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.transfer moves one device; swap, processReturn, deactivate, activate and setIdentifier work on the device of the call.
  • deviceIdentifiers takes 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 (also POST deviceIdentifiers with deviceEntryNumber).
    • 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:

  1. Search for Webhooks, and choose New.
  2. 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.
  3. 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-Signature header), so the receiver can check that it comes from you.
  4. In Contract Events (and Device Events), choose what the webhook receives. New webhooks receive every event.
  5. Choose Send Test Message. The receiver's answer is shown, and nothing is logged.
  6. 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

  • lifecycleEvents is built per request and needs a contract filter.
  • One POST amendments adds 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.
  • transferDevices moves 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.

Next step

Ready to try Bitta Subscriptions?