API set up + Automated Order Management (AOM) + Automated Usage Reporting

part 1 automated order management (aom) part 1 automated order management (aom) author dick dijkstra | version 0 8 | date march 7, 2025 1\ introduction 📖 api reference https //apidocs wetransact io/openapi/subscriptions when marketplace publishers have an automated provisioning process, most of them would like to plug in the marketplace purchase channel with that process through the wetransact platform that can be achieved by following this guide 2\ order process when selling through the microsoft commercial marketplace, microsoft dictates the order flow when aom is enabled, wetransact acts as the middleware between azure marketplace and your order management system how it works customer makes a purchase → redirected to the wetransact landing page purchaser clicks confirm purchase → order sent to the wetransact portal wetransact sends a createsubscription event to your event grid endpoint your system provisions and activates the subscription wetransact notifies azure marketplace to confirm activation subsequent lifecycle events — after activation, wetransact also forwards these event description cancellation customer cancels; service ends at end of commitment term suspension microsoft couldn't collect payment; consider suspending service reinstatement payment collected after suspension; reinstate service renewal subscription renewed manually or via auto renew plan change customer changed plan tier (e g basic → standard) seat quantity change customer changed number of users (per user plans only) 3\ integration setup wetransact sends events to the event grid topic endpoint you configure in settings in the wetransact portal 3 1 api access 📖 api reference https //apidocs wetransact io/openapi/subscriptions if you want to control activation programmatically, you need an api key to generate a key go to settings → scroll to the api access section click generate copy the key immediately and store it in a secrets manager ⚠️ the key is only visible once after leaving the page it won't be shown again if compromised, generate a new one to invalidate the old key 3 2 subscription activation publishers must activate a subscription within 30 days or microsoft will cancel it automatically 🚨 30 day window set up monitoring and alerts on your order queue to avoid missing this deadline there are three ways to activate option 1 — manual (portal) go to orders → click take action → approve or reject option 2 — auto approve go to product listing → order approval → enable automatically approve new orders option 3 — via api (recommended for aom) receive the createsubscription event, complete provisioning, then call the api to activate 3 3 activation via api method post url https //\[your subdomain] wetransact io/api/v1 0/subscriptions/\[subscription id]/actions/activate header x api key \[your api key] responses 200 ok — processed successfully 500 — failed, contact wetransact support ℹ️ a 200 does not guarantee activation if it fails downstream, wetransact will send an activatesubscriptionfailed event asynchronously contact support if this happens 4\ events & messages 4 1 createsubscription sent when a subscription is created contains everything needed for provisioning and activation field type description marketplacesubscriptionid guid microsoft assigned id use as your unique identifier created datetime timestamp of subscription creation companyname string name of the purchasing company marketplaceofferid string product id in partner center marketplaceplanid string plan (sku) id in partner center seatquantity string (optional) number of seats — per user plans only termunit string p1m / p1y / p2y / p3y initialuseremail string email of the purchaser additionaldetails string (optional) extra landing page fields, as json channel string direct or indirect (csp) beneficiaryemail string (optional) end user email — differs from purchaser when via csp json { "marketplacesubscriptionid" "a1fabe21 7904 4c2f 932d 5253a35e97d0", "created" "2025 03 07t12 34 56 7892", "companyname" "endcustomer", "marketplaceofferid" "offer 123", "marketplaceplanid" "plan premium", "seatquantity" "10", "termunit" "p1y", "initialuseremail" "purchasing\@contoso com", "additionaldetails" "{}", "channel" "indirect", "beneficiaryemail" "user\@endcustomer io", "resellername" "contoso"} 4 2 cancelsubscription sent when a customer cancels service stays active until the end of the committed term field type description marketplacesubscriptionid guid id of the cancelled subscription json { "marketplacesubscriptionid" "a1fabe21 7904 4c2f 932d 5253a35e97d0" } 4 3 suspendsubscription sent when microsoft cannot collect payment consider suspending the service or contacting the customer field type description marketplacesubscriptionid guid id of the suspended subscription json { "marketplacesubscriptionid" "a1fabe21 7904 4c2f 932d 5253a35e97d0" } 4 4 reinstatesubscription sent when microsoft collects payment after a suspension reinstate the service if it was suspended field type description marketplacesubscriptionid guid id of the subscription to reinstate json { "marketplacesubscriptionid" "a1fabe21 7904 4c2f 932d 5253a35e97d0" } 4 5 renewsubscription sent when a subscription is renewed manually or via auto renew field type description marketplacesubscriptionid guid id of the renewed subscription json { "marketplacesubscriptionid" "a1fabe21 7904 4c2f 932d 5253a35e97d0" } 4 6 changeplan sent when a customer changes plan tier update feature flags, entitlements, or resource allocations field type description marketplacesubscriptionid guid id of the affected subscription marketplaceplanid string id of the new plan (sku) json { "marketplacesubscriptionid" "a1fabe21 7904 4c2f 932d 5253a35e97d0", "marketplaceplanid" "plan premium"} 4 7 changeseatquantity sent when a customer changes seat count per user plans only update compute/resource allocations accordingly field type description marketplacesubscriptionid guid id of the affected subscription seatquantity string new total seat count json { "marketplacesubscriptionid" "a1fabe21 7904 4c2f 932d 5253a35e97d0", "seatquantity" "150"} 4 8 activatesubscriptionfailed sent when activation fails downstream after an api call returned 200 ok contact wetransact support immediately field type description marketplacesubscriptionid guid id of the subscription that failed to activate json { "marketplacesubscriptionid" "a1fabe21 7904 4c2f 932d 5253a35e97d0" } 5\ message routing all messages include a subject field for filtering in your event grid subscription subject trigger createsubscription new order placed cancelsubscription customer cancelled suspendsubscription payment failure reinstatesubscription payment resolved renewsubscription subscription renewed changeplan plan tier changed changeseatquantity seat count changed activatesubscriptionfailed activation failed downstream part 2 automated usage reporting part 2 automated usage reporting 6 introduction 📖 api reference https //apidocs wetransact io/openapi/subscriptions some marketplace publishers have a need to report usage through an api this is a necessity when the reporting frequency is high (more than once a month) this section explains how the wetransact api is used to report usage the reporting of usage always needs to happen against an active subscription, which is uniquely identifiable by a guid when that guid is obtained, the publisher can report usage by defining the amounts per meter all api documentation lives at https //apidocs wetransact io/openapi this api specification describes all other related api details, including sample request and response messages section 7 1 explains how to get access to the wetransact api in step 1 the publisher’s reporting system fetches the right subscription id (exact field name marketplacesubscriptionid) by first getting all subscriptions via the get /subscriptions endpoint to include information about meters that are valid for the subscription, the query parameter includemeters=true should be added if the subscription id and meter details are already stored, this step can be skipped in step 2 , the system on the publisher’s end needs to make a charge against the subscription id this is done by calling the post /subscriptions/{id}/charge endpoint here the system defines the subscription id to charge against, as well as the meter id and the amount the wetransact platform takes care of the message exchange with the microsoft marketplace ( step 3 ) 7 1 api access when publishers want to automate usage reporting, api access is needed if no api key has been created, the settings section will show a generate button