# ConveRact revenue workspace

The tenant **Revenue workspace** connects commerce records, customer recovery, offers, experiments, subscriptions, agency operations, plan reviews, and ConveRact AI knowledge improvement. Platform administrators use **Revenue & agencies** to manage commercial agreements and payouts.

Integration is free. ConveRact has no installation charge or one-time integration fee. Recurring subscriptions, metered usage, custom development, and external provider costs remain subject to their published terms.

## 1. Native store connections

Open Revenue workspace → Stores. Store credentials are encrypted at rest and are not returned by the API. Connection URLs must use public HTTPS. Redirects and private-network destinations are rejected. Saving a credential creates a configured connection; only a successful sync marks it connected.

### Shopify

1. Create an app with access to the merchant's store. Grant `read_products`, `read_inventory`, and `read_orders`. The app also needs permission to access protected customer data and abandoned checkouts. Older order history requires the corresponding Shopify approval.
2. Enter the permanent `https://your-store.myshopify.com` origin, Admin API access token, and app client secret as the webhook signing secret.
3. Sync the store. ConveRact uses the versioned **2026-07 GraphQL Admin API** to import product variants, stock, available inventory cost, orders, and abandoned checkouts. Permissions rejected by Shopify are shown as a sync error, not a successful empty import.
4. Subscribe the app to order creation/updates/payment/cancellation, product changes, checkout changes, and refunds. Use the webhook URL shown on the store connection. Shopify signs the raw JSON using `X-Shopify-Hmac-Sha256`.
5. Review imported records and create explicit identity links to conversations. Customer contact details do not automatically grant marketing permission.

Each sync processes bounded batches and persists pagination cursors. Further batches run in the background approximately every 15 minutes. Webhooks retrieve current order state instead of trusting a stale event body. Before a cart recovery is sent, ConveRact rechecks the checkout with Shopify. Refunds reduce experiment revenue. Test orders are excluded.

References: [Shopify abandoned checkout API](https://shopify.dev/docs/api/admin-graphql/latest/queries/abandonedCheckouts), [webhook verification](https://shopify.dev/docs/apps/build/webhooks/verify-deliveries), [order access](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order).

### WooCommerce

1. In WooCommerce → Settings → Advanced → REST API, create a key for an authorized store administrator. ConveRact imports products, product variations, orders, and the store currency through `/wp-json/wc/v3`.
2. Enter the HTTPS store origin and the credential in `consumer_key:consumer_secret` format. It is transmitted as HTTP Basic authentication over verified HTTPS.
3. Create order and product webhooks pointing to the connection URL. Enter the same signing secret in WooCommerce and ConveRact. Webhook JSON is verified with `X-WC-Webhook-Signature` before processing.
4. For abandoned checkout data, install the included **ConveRact Commerce Recovery** WordPress plugin. Standard WooCommerce order APIs do not expose abandoned session carts. The plugin provides that missing source.
5. In WooCommerce → ConveRact Commerce, save the webhook URL and signing secret. Configure a reliable WordPress cron runner so retry and retention jobs run when the store has little traffic.

The companion plugin supports the **classic WooCommerce checkout**. It adds an unchecked permission field for saving checkout details. It saves opted-in checkout snapshots for up to 30 days, coalesces frequent edits, retries transient webhook failures, and closes carts when the order is paid or cancelled. This permission concerns saving checkout details; record channel-specific marketing permission separately in ConveRact.

Checkout Blocks are not captured by this plugin version. Existing WooCommerce products and orders still sync independently of checkout style. Do not enable cart recovery for a Blocks store until a compatible cart source is connected.

The plugin's authenticated verification endpoint is `GET /wp-json/wc/v3/converact/carts/{id}`. Recovery URLs use expiring random tokens. Restoring a cart revalidates products and stock and uses current WooCommerce prices; it does not mark payment complete. A populated cart is preserved for customer review.

Source: `ChatBEV1/integrations/woocommerce/converact-commerce.php`. Download the ZIP from the developer page. [WooCommerce REST documentation](https://developer.woocommerce.com/docs/apis/rest-api/).

## 2. Recovery and repeat-purchase journeys

Open Recovery and record permission for the selected conversation and purpose: marketing or billing. Include when and how the customer agreed. Revoke it here if requested. A newer customer message containing an opt-out request suppresses a journey even if older permission exists.

Create a paused journey with one of four sources:

| Journey | Eligibility |
| --- | --- |
| Cart | An imported open checkout, a verified identity link, and a supported live conversation |
| Quote | An existing draft/sent quote, a linked conversation, valid pricing dates, and no linked live payment |
| Subscription | A live recurring payment marked past due; the provider must confirm a payable recovery invoice |
| Replenishment | A paid, non-refunded store order for selected replenishable products after the configured interval |

Choose up to three increasing delays, a contact cap, cooldown, and UTC quiet hours. `{{name}}` and `{{checkout_url}}` are supported in message text. A missing required checkout URL blocks delivery. Replenishment timing starts after the configured repeat interval. Select the products to which the cadence actually applies.

Review and approve each message by default. Automatic sending is a separate explicit setting, and a journey starts paused. Enable it after reviewing its complete configuration. The background worker evaluates enabled journeys every minute while the tenant is active. **Find eligible actions** generates the same approval queue on demand.

WhatsApp outside its service window requires a synced approved template and separately recorded WhatsApp opt-in. Use numbered text body parameters. Meta approval, channel windows, current consent, customer suppression, frequency limits, live provider readiness, and current source state are checked at delivery time. Other channels must support the existing conversation send workflow. Website follow-ups are visible when the customer returns to the same conversation; they are not email notifications.

Completed purchases, expired quotes, refunds, revoked identity links, cancelled jobs, and withdrawn permission stop future actions. Source failures block sending. Provider acceptance is distinct from a delivery receipt. Ambiguous or failed sends require review in Channels; they are not automatically replayed as fresh customer messages.

## 3. Margin-controlled offers and bundles

In Offers, record each product's unit cost in the same currency as its price. Choose products and quantities, discount, minimum product margin, and expiry. The server validates active fixed-price physical products, stock, costs, a single currency, and the minimum margin.

An administrator approves the resulting price and cost fingerprint. Creating a customer quote revalidates it; changed prices/costs or inadequate stock require review. The quote uses the existing quote and payment workflow. Approval does not reserve stock or charge the customer. Product margin excludes shipping, tax, provider fees, and returns.

## 4. Revenue experiments

Create and start an experiment, then attach it to a cart journey. Each eligible customer is assigned once using a private randomized seed to treatment or holdout. Holdout members receive no contact from that journey. Assignment is persisted so a retry cannot change the group.

Reports use imported orders created and paid during the customer's measurement window, subtract recorded refunds, and keep currencies separate. The comparison uses all assigned customers, including those who did not receive a message. Clicks, quotes, and opened checkouts are not purchases.

Reports show sample size, maturity, conversions, net recorded sales, and sales per assigned customer. The approximate interval is withheld until each group has at least 30 customers and every measurement window has matured. The interval uses a normal approximation and can be unreliable for highly skewed sales; it is directional evidence rather than proof. Other campaigns can contaminate the experiment. Stopping an experiment prevents further enrollment/sending and retains reporting.

## 5. Subscription payment recovery

Open Subscriptions and refresh an existing live recurring payment. ConveRact reads the current provider subscription/invoice and displays its recovery state, amount, hosted payment link, attempt count, and next attempt when available. Stripe and Razorpay remain responsible for their retry schedules and customer authentication. A recovery refresh does not attempt a new charge.

Create a subscription journey to schedule permitted billing assistance. Successful, cancelled, or otherwise unpayable subscriptions cannot receive a stale payment demand. Configure live payment credentials and webhooks before using this workflow. [Stripe recovery documentation](https://docs.stripe.com/billing/revenue-recovery/smart-retries).

## 6. Agency reseller operations

Platform administrators create an agency associated with an active tenant, then invite a different client workspace with the agreed commission percentage and commercial terms. The client administrator accepts or revokes the agreement from their Agency tab. Before acceptance, the agency receives no client operating metrics.

Agency administrators can delegate agency-summary access to active members of their own workspace. Agency operators see accepted clients' status, usage, opportunity counts, and verified payment summaries. They cannot impersonate clients or read client conversations through agency access.

Commissions are reconciled from **live paid ConveRact subscription invoices** after agreement acceptance, less post-payment credit notes. Each invoice has a stable ledger identity; later credits create reversing entries. Plan list prices, demo invoices, and pending payments do not earn commission. Revoked agreements earn no new invoices but existing entries remain eligible for reversals.

Prepare a payout per agency and currency. Preparation allocates unallocated ledger entries and does not transfer funds. After an actual external transfer, record the unique bank/provider settlement reference. Manual refunds outside provider invoice credit notes must be reconciled before settlement. The ledger distinguishes earned commissions, reversals, prepared payouts, and externally settled payouts.

## 7. Evidence-based plan offers

The Plan tab examines recorded monthly conversation and AI-request usage. At 80% of capacity, it can recommend an active plan with sufficient capacity. It does not estimate revenue uplift or automatically upgrade subscriptions.

The tenant requests review, the platform administrator offers or declines it, and the tenant explicitly accepts before opening secure billing. The billing provider's verified result controls the subscription. Clients should review recurring prices and terms on checkout.

## 8. ConveRact AI objection analysis

AI insights select recent customer excerpts relevant to price, trust, product fit, and timing. Contact details, numeric identifiers, links, and obvious credentials are redacted before analysis. The configured ConveRact AI produces a summary and knowledge suggestions with source message IDs. Unparseable or unsupported results fail without modifying knowledge.

An administrator reviews source conversations, edits the proposed answer to verified business facts, and confirms publication. Only then is a published FAQ created for the existing knowledge system. Analysis does not send a customer message or publish a model answer automatically.

## API and access

The Overview tab includes a setup checklist and counts of approvals, blocked or failed actions, and store errors. Store readiness requires a successful sync in the last 24 hours; permission checks use the latest decision. Optional offer and experiment milestones are useful when those workflows fit your business. A completed milestone does not authorize contact or guarantee provider delivery.

Revenue workspace endpoints use the existing authenticated session and CSRF protection. They are **not** part of the external API-key permission surface. Tenant identity is derived from the session; a query parameter cannot select another tenant. Tenant administrators configure stores, consent, journeys, offers, experiments, and knowledge. Staff can read their workspace and create a quote from an approved offer. Platform agency and plan-review endpoints require a platform administrator.

| API prefix | Purpose |
| --- | --- |
| `/api/v1/growth` | Tenant workspace, configuration, approvals, reports |
| `/api/v1/platform/growth` | Agency agreements, commissions, payouts, plan review |
| `/api/v1/commerce/webhooks/{storeId}` | Raw signed store event ingestion; no session required |

Download the [revenue API reference](https://www.converact.com/revenue-workspace.openapi.json) for the endpoint inventory, required request fields, enums, limits, defaults, and session authentication. Journey delays must also be strictly increasing. The webhook route verifies its signature independently of browser authentication. Do not expose store credentials or webhook secrets in browser scripts.

For an authenticated tenant administrator, a minimal paused quote journey request to `POST /api/v1/growth/journeys` is:

```json
{
  "name": "Quote assistance",
  "kind": "QUOTE",
  "enabled": false,
  "approvalRequired": true,
  "delayHours": [24, 72],
  "message": "Hello {{name}}, would you like help reviewing your quote?"
}
```

Send the session cookie and `X-CSRF-Token` obtained through the documented sign-in flow. After recording permission for each recipient, enable the journey with `PATCH /api/v1/growth/journeys/{id}` and `{"enabled":true}`. Planning creates approval records; an eligible scheduled action is sent only after required approval and fresh source/permission checks. Inspect the returned job status and reason when an action is blocked. Never interpret an HTTP 200 response from a planning or refresh endpoint as a completed sale or delivered customer message.