# WeTransact API Documentation ## ๐Ÿš€ Introduction Welcome to the **WeTransact Platform API** โ€” your gateway to managing subscriptions, products, financials, deal registration, and marketplace leads for offers listed on the Azure Marketplace. As a publisher, this API lets your system interact with WeTransact in real-time. You can: - **Retrieve subscriptions** your customers have purchased and inspect their meters - **Activate** or **reject** new subscriptions based on your own business logic - **Charge** for usage when your product includes metered dimensions - **Retrieve products and plans** you've published - **Retrieve financial details** for your publisher account - **Look up companies** to support deal registration workflows - **Retrieve marketplace leads** captured from your listings and offers Think of this as the control panel behind the curtain โ€” allowing your software to handle marketplace operations automatically, reliably, and safely. --- ## ๐ŸŽฏ What You Can Do ### ๐Ÿ“ฆ Subscriptions `GET /api/v1.0/subscriptions`, `GET /api/v1.0/subscriptions/{subscriptionId}` โ€” list and retrieve subscriptions. Pass `includeMeters=true` to hydrate the metering dimensions on each subscription. #### โœ… Activate When a customer purchases your product, WeTransact doesn't activate the subscription automatically. You're in control. Use `POST /api/v1.0/subscriptions/{subscriptionId}/actions/activate` to approve and activate once you're ready (e.g., after internal provisioning). #### โŒ Reject Not the right fit? Use `POST /api/v1.0/subscriptions/{subscriptionId}/actions/reject` to explicitly reject a subscription before activation โ€” for example, if the customer doesn't meet prerequisites or passes fraud checks. #### ๐Ÿ’ฐ Charge For offers with custom dimensions (i.e., usage-based pricing), `POST /api/v1.0/subscriptions/{subscriptionId}/actions/charge?dimensionId=...&quantity=...&effectiveStartTime=...` reports usage, which leads to the customer being billed through Microsoft. `dimensionId` is the **Partner Center dimension id**; `GET /subscriptions?includeMeters=true` returns it as `MeterId` (and `PartnerCenterMeterId`) on each meter. `effectiveStartTime` is optional (ISO 8601 UTC, defaults to now) and names the usage hour being reported; it must not be in the future or older than 24 hours. > **Behind the scenes:** WeTransact relays these charges to the [Microsoft Commercial Marketplace Metering API](https://learn.microsoft.com/en-us/azure/marketplace/partner-center-portal/marketplace-metering-service-apis) โ€” and those charges end up directly on the customer's invoice. ### ๐Ÿงฉ Products `GET /api/v1.0/products`, `GET /api/v1.0/products/{productId}`, `GET /api/v1.0/products/bypartnercenterofferid/{partnerCenterOfferId}` โ€” list your products or retrieve one by WeTransact product ID or by the Partner Center offer ID. Product responses include associated plans, pricing configuration, and metadata such as screenshots, videos, and supporting files. ### ๐Ÿ’ต Financials `GET /api/v1.0/financials` โ€” every revenue line Microsoft reports for your account (one row per purchase line per month, refreshed nightly from Partner Center), for payout reconciliation. Join `AssetId` to your SaaS `MarketplaceSubscriptionId`; use `PurchaseRecordId` + `LineItemId` for a single purchase line. Amounts come in three currencies (CC customer, PC your payout currency, USD) and the expected payout is `estimatedRevenuePC ร— incentiveRate / 100`. See the endpoint reference for every column. `GET /api/v1.0/usage?subscriptionId=...&from=...&to=...` โ€” Microsoft's usage report: daily metered usage per subscription and meter dimension (`MeterId` is the dimension id you charge with; for SaaS the subscription id is in `ReferenceId`). Rows are daily aggregates, not individual usage events, so reconcile daily totals per dimension against what you sent through the charge endpoint. Filters are optional; without them you get the full history. ### ๐Ÿค Deal Registration `GET /api/v1.0/dealregistration/findcompany?countryCode=...&companyName=...` โ€” look up a company by ISO country code and name to support deal registration workflows. ### ๐Ÿ“จ Marketplace Leads `GET /api/v1.0/marketplaceleads`, `GET /api/v1.0/marketplaceleads/{marketplaceLeadId}` โ€” retrieve leads captured from your Azure Marketplace listings and offers. Use the optional `since` query parameter (ISO-8601 UTC timestamp) to fetch only recent leads. > **Consuming WeTransact events?** The public API is pull-only. If you need event-driven integration (subscription purchased, cancelled, renewed, etc.), use the **WeTransact Zapier app** or contact support for an alternative integration path. --- ## โš ๏ธ Charging: Use with Care When you submit a usage charge, you're triggering a **real financial transaction** on your customer's Azure bill. Because of this, we **strongly recommend** testing your integration thoroughly. ### ๐Ÿงช Test Like a Pro To validate your charging logic without real financial impact: 1. **Create a test product** on Azure Marketplace with a price of **$0.01 per unit** 2. Add one or more **custom dimensions**, each priced at **$0.01** 3. Use this offer to test your charging flows end-to-end โ€” including retries, rollbacks, and reporting ### ๐Ÿ” Duplicate Detection & Safe Retries Microsoft accepts **one usage event per subscription, dimension and hour** (the hour of `effectiveStartTime`). WeTransact applies the same rule before calling Microsoft, but only against reports Microsoft has **accepted** โ€” a failed attempt never blocks its own retry. That makes retries safe: after a timeout, a `429` or a `502`, resend the **same** `effectiveStartTime` and you get one of two answers, never a double charge: | HTTP | Meaning | Retry? | |------|---------|--------| | `200` | Microsoft accepted the usage event. `Microsoft.UsageEventId` is Microsoft's id. | No | | `400` | Invalid input (`quantity`, `dimensionId`, `effectiveStartTime` unparsable / future / older than 24h). | Fix first | | `404` | Subscription or dimension unknown. | Fix first | | `409` | Already reported for this hour โ€” by an earlier accepted call, or Microsoft answered `Duplicate`. Body carries the original `UsageReportEventId` and `Microsoft.UsageEventId`. | No | | `422` | Microsoft rejected the event (`ResourceNotActive`, `InvalidDimension`, `Expired`, `BadArgument`, ...). See `Microsoft.Status`. | Fix first | | `429` | Too many concurrent charges. | Yes, same `effectiveStartTime` | | `502` | Microsoft unreachable, timed out or 5xx. Outcome unknown; resending the same hour cannot double charge. `retryable` is `true`. | Yes, same `effectiveStartTime` | Every response from the endpoint includes `retryable`, `effectiveStartTime` and Microsoft's own verdict under `Microsoft`, so your reconciliation can tie each report to what Microsoft actually recorded. The `429` from the concurrency limiter carries no body. Still, it's your responsibility to make sure your integration is idempotent and stable. --- ## ๐Ÿ” Authentication: Using Your API Key To authenticate with the WeTransact API, include your **API key** in every request using the `x-api-key` header. ### ๐Ÿ”ง How to Generate Your API Key 1. Log in to your WeTransact portal: `https://{your-subdomain}.wetransact.io/Settings` 2. Navigate to the **Settings** section 3. Generate your API key and store it securely โ€” you won't be able to retrieve it again later ### ๐Ÿ“ฌ Example Request ```http GET /api/v1.0/subscriptions HTTP/1.1 Host: yoursubdomain.wetransact.io x-api-key: YOUR_API_KEY_HERE ``` > โš ๏ธ **Security Note**: Treat your API key like a password. Don't expose it in client-side code, public repos, or logs. If you suspect it's been compromised, rotate it immediately. --- ## ๐Ÿ“ˆ Rate Limits & Throttling To keep the platform stable and fair for all users, WeTransact enforces API rate limits. ### ๐Ÿ“ฆ Subscription Retrieval - **Limit**: 10 requests per 60 seconds per client - **Overages**: Requests beyond this will be throttled or temporarily blocked - **Tip**: Cache subscription data where possible, especially in burst scenarios ### โš™๏ธ Charge Action - **Concurrent Limit**: Up to 10 active charge requests at a time - **Queue Buffer**: Up to 5 additional requests may queue if things get busy - **Overload Handling**: Requests beyond the queue limit are rejected with `429` โ€” retry later with the **same** `effectiveStartTime` This ensures the underlying billing system remains performant and reliable โ€” because nobody wants their customer's bill delayed (or wrong). --- ## ๐Ÿงญ What's Next? You're ready to build. Here's what we suggest: - Start with **subscription retrieval** to list and inspect active subscriptions - Hook up the **activation and rejection** logic to your onboarding workflow - Integrate **usage metering** only after you've validated everything in a test environment - Pull **products**, **financials**, and **marketplace leads** to surface marketplace data in your own dashboards Need example code or help setting up? Let us know.