Connect WooCommerce
MIDDAG Account uses WooCommerce as its commerce engine. WooCommerce handles the parts it already does well — product catalog, shopping cart, checkout, and payment processing. MIDDAG Account takes over after the purchase to manage the customer lifecycle: entitlements, licenses, contracts, services, and renewals.
This page explains how the two systems work together and what happens at each stage.
The bridge concept
Think of MIDDAG Account and WooCommerce as two layers:
WooCommerce answers: What products exist? How does the customer pay? Was the payment successful?
MIDDAG Account answers: Which organization bought it? What are they entitled to? When does it expire? What resources were provisioned?
Neither system replaces the other. WooCommerce continues to work exactly as before — your existing products, payment gateways, coupons, and tax settings are unaffected. MIDDAG Account adds a lifecycle layer on top.
Products map to Entitlement Classes
Every WooCommerce product (or product category) can be mapped to an Entitlement Class. This mapping tells MIDDAG Account what type of entitlement to create when a customer purchases that product.
| WooCommerce product | Entitlement Class | What gets created |
|---|---|---|
| "Pro Plugin License" | PLG (Plugin) | Entitlement + License key + Download access |
| "Managed Hosting - Standard" | ENV (Environment) | Entitlement + Environment instance |
| "Annual Support Plan" | SVC (Service) | Entitlement + Service contract |
| "Training Workshop" | EDU (Education) | Entitlement + Course access |
| "Partner Program" | AFL (Affiliate) | Entitlement + Affiliate tracking |
| "Custom Development Package" | ORD (Order) | Entitlement (general purpose) |
You configure this mapping in MIDDAG Account > Settings > Product Registry or during the Initial Setup wizard.
How mapping works
- You create a WooCommerce product as usual (name, price, description, images)
- In the product editor, a new MIDDAG Account panel appears
- Select the Entitlement Class for this product
- Optionally configure class-specific settings (license duration, environment tier, etc.)
- Save the product
When a customer purchases this product, MIDDAG Account reads the mapping and creates the appropriate entitlement automatically.
Orders create Entitlements
When a WooCommerce order reaches the Completed status, MIDDAG Account processes each line item:
- Identify the buyer's organization. The customer's WordPress account is linked to an organization. If no organization exists, one can be created automatically or the admin is notified.
- Check the product mapping. Each line item is checked for an Entitlement Class mapping.
- Create the entitlement. A new entitlement is created with a unique code (e.g.,
PLG-2026050001), linked to the organization, with status set to Active. - Provision downstream resources. Based on the Entitlement Class, MIDDAG Account creates the appropriate downstream resources — license keys, environment instances, service contracts, etc.
- Record the financial link. The entitlement is linked back to the WooCommerce order for audit and reference.
This entire flow is automatic. No manual intervention is needed for standard purchases.
What the admin sees
After an order completes:
- The Organization dashboard shows the new entitlement with its code, class, and status
- The Entitlement detail page links to the originating WooCommerce order
- The WooCommerce order page shows a reference to the created entitlement
Payment status drives entitlement lifecycle
MIDDAG Account monitors WooCommerce order status changes and updates entitlements accordingly:
| WooCommerce event | Entitlement action |
|---|---|
| Order completed | Entitlement created with Active status |
| Payment failed (subscription renewal) | Entitlement moves to Suspended |
| Payment recovered | Entitlement returns to Active |
| Order refunded | See Refunds and cancellations below |
| Subscription expired | Entitlement moves to Expired |
| Subscription cancelled | Entitlement moves to Cancelled |
The specific timing and behavior of these transitions is governed by the Policy Engine. For example, you can configure a grace period that keeps an entitlement active for 14 days after a failed payment, giving the customer time to update their payment method.
What happens on refund or cancellation
Full refund
When a WooCommerce order is fully refunded:
- All entitlements linked to that order are moved to Cancelled status
- Downstream resources are deactivated:
- License keys are revoked
- Environment access is suspended
- Service contracts are terminated
- The organization's dashboard reflects the change immediately
- If configured, an automated notification is sent to the organization
Partial refund
Partial refunds do not automatically change entitlement status. The admin can review and adjust entitlements manually, or configure automatic behavior through the Policy Engine.
Order cancellation (before payment)
If a WooCommerce order is cancelled before payment is completed, no entitlement is created (since entitlements are only created on order completion).
Voluntary cancellation (by customer)
When a customer cancels a subscription:
- The entitlement remains Active until the current billing period ends
- At the end of the period, the entitlement moves to Expired
- After the configured retention period, it moves to Cancelled
- Downstream resources follow the same timeline
The Cancellation Policy controls retention periods and whether a cancelled entitlement can be reactivated later (the "win-back" flow).
Renewals
For subscription-based products, WooCommerce handles the recurring billing. MIDDAG Account handles the entitlement lifecycle:
- Before expiration: The Renewal Policy can trigger reminder notifications to the organization (e.g., 30 days, 14 days, and 7 days before expiration).
- Payment succeeds: The entitlement's expiration date is extended. Status remains Active. No new entitlement code is generated — the same code persists across renewals.
- Payment fails: The entitlement enters a grace period (configurable via the Payment Recovery Policy). During the grace period, the entitlement stays Active or moves to Suspended depending on your configuration.
- Grace period expires: If payment is not recovered, the entitlement moves to Expired and downstream resources are deactivated.
Key points to remember
- WooCommerce stays in charge of commerce. Products, pricing, coupons, taxes, checkout, and payment processing remain in WooCommerce. Do not try to manage these in MIDDAG Account.
- MIDDAG Account stays in charge of lifecycle. Entitlements, organizations, licenses, contracts, and services are managed in MIDDAG Account. WooCommerce does not need to know about these.
- The link is the product mapping. The Entitlement Class assigned to each WooCommerce product is the bridge between the two systems.
- Automation is configurable. Every automatic behavior (entitlement creation, suspension, cancellation, notifications) can be tuned through the Policy Engine.
- Existing WooCommerce data is not modified. MIDDAG Account adds metadata to orders and products but does not alter existing WooCommerce data or behavior.
Next steps
- Initial Setup — Complete the Setup Wizard including WooCommerce connection
- Create your first Organization — Set up a customer organization
- Create your first Entitlement — See the entitlement lifecycle in action
- First Lifecycle — Walk through a complete purchase-to-renewal cycle