# WallaB.AI — full developer index

> WallaB.AI is an AI-powered subscription-retention app for Shopify — a cancel-save concierge (WallaB), a passwordless self-serve shopper portal, dunning recovery, win-back, and a read-only developer data API.

WallaB Developer Platform API v1.0.0. Base URL: https://wallab.ai/api/external/v1. OpenAPI: https://wallab.ai/api/external/v1/openapi.json.

## Key pages

- [WallaB.AI (home)](https://wallab.ai/): The product overview — WallaB, a guardrailed AI cancel-save concierge, plus dunning recovery, a passwordless self-serve customer portal, win-back campaigns, build-a-box bundles, and churn analytics for Shopify subscriptions.
- [Pricing](https://wallab.ai/pricing): The full plan ladder — monthly and annual prices, the included subscription-revenue, AI-conversation, and marketing-email allowances, and what each plan adds.
- [WallaB.AI vs Recharge, Skio, Loop, and Appstle](https://wallab.ai/compare): A dated comparison of what each app does at the cancel moment, how each prices, how easy it is to leave — and where WallaB.AI is behind.
- [About — what WallaB.AI stands for](https://wallab.ai/about): The product principles: honest retention, no dark patterns, no lock-in (self-serve data export), and secure-by-default engineering.
- [FAQ](https://wallab.ai/faq): Answers to common questions about pricing, the AI concierge, subscriptions and build-a-box, security and privacy, and migrating from another subscription app.
- [Migrations — switching to or away from WallaB.AI](https://wallab.ai/migrations): How subscribers move in from another subscription app (column-mapping CSV importer, readiness report before anything commits, billing hold so nothing charges twice) and how they can be exported back out.
- [Learn — do you need a subscription app beyond Shopify's free one?](https://wallab.ai/learn): A decision guide for judging whether Shopify's free Subscriptions app is still enough for a store, and when staying put is the right call.
- [Documentation](https://wallab.ai/docs): The docs hub: the merchant guide, the shopper portal guide, and the developer reference.

## Pricing

- Free: $0/mo.
- Starter: $9.99/mo, or $99/yr billed once yearly (save 17%).
- Growth: $49.99/mo, or $499/yr billed once yearly (save 17%).
- Pro: $99.99/mo, or $999/yr billed once yearly (save 17%).
- Enterprise Plus: $999.99/mo, or $9,999/yr billed once yearly (save 17%).
- Prices are in USD and charged through Shopify billing.
- Paid plans include a 14-day free trial.
- The AI concierge is included on every plan, with no per-message fees.
- Plan details and allowances: https://wallab.ai/pricing

## Authentication

Create a key in Settings → WallaB Developer Platform (owner-only). Keys look like `wlb_your_key_here` and are shown once at creation. Send them as `Authorization: Bearer <key>`. Available on the Growth plan or higher; below that, requests are refused with 403. Any missing, malformed, unknown, or revoked key returns an identical 401 `{"success": false, "message": "Unauthorized"}`.

## MCP server

- Endpoint: `POST https://wallab.ai/api/mcp` — the read-only v1 surface mirrored as Model Context Protocol tools (JSON-RPC 2.0 over Streamable HTTP). Stateless: no sessions, no server-to-client stream; GET and DELETE return 405.
- Auth: the same `Authorization: Bearer <key>` `wlb_` API key as the REST API, Growth plan or higher. Auth, plan-gate, and rate-limit failures are HTTP 401/403/429, not JSON-RPC errors.
- Rate limits: shared with the REST API — per key, by plan.
- Protocol revisions: 2026-07-28 and 2025-06-18 — the newer one is stateless (per-request `_meta`, `server/discover`), the older one uses the `initialize` handshake. JSON-RPC batching is not supported.
- Tools (`tools/list` is filtered to the calling key's scopes):
  - `get_entitlements` (scope: `read:entitlements`) — Get customer entitlements.
  - `list_subscriptions` (scope: `read:subscriptions`) — List subscriptions.
  - `get_subscription` (scope: `read:subscriptions`) — Get subscription detail.
  - `get_metrics_summary` (scope: `read:metrics`) — Get metrics summary.
  - `list_plans` (scope: `read:plans`) — List selling plans.
  - `list_cancellations` (scope: `read:metrics`) — List cancellation outcomes.

## Overview

- Base URL: https://wallab.ai/api/external/v1 (v1)
- Auth: `Authorization: Bearer <key>` with a `wlb_` API key (created in Settings, owner-only). Growth plan or higher.
- Rate limits: per key, by plan — Growth 60/min, Pro 300/min, Enterprise Plus uncapped; 429 + `Retry-After` on exceed.
- Scopes:
  - `read:entitlements` — Read customer entitlement status (active-subscription checks).
  - `read:subscriptions` — Read subscription records and their status.
  - `read:metrics` — Read aggregate retention and revenue metrics.
  - `read:plans` — Read selling-plan definitions.
- Endpoints:
  - `GET /api/external/v1/entitlements` (scope: `read:entitlements`) — Check a customer's live entitlement status
  - `GET /api/external/v1/subscriptions` (scope: `read:subscriptions`) — List the shop's subscriptions
  - `GET /api/external/v1/subscriptions/{id}` (scope: `read:subscriptions`) — Get one subscription with its line items
  - `GET /api/external/v1/metrics/summary` (scope: `read:metrics`) — Get the dashboard KPI summary
  - `GET /api/external/v1/plans` (scope: `read:plans`) — List the shop's selling plans
  - `GET /api/external/v1/cancellations` (scope: `read:metrics`) — List cancel-save concierge outcomes

## Errors

Every non-2xx response is `{ "success": false, "message": "..." }`. Status codes: 400 (invalid input), 401 (auth failure), 403 (plan gate or missing scope), 404 (subscription detail only — no id oracle), 429 (rate limited; see `Retry-After`), 500 (server error, safe to retry).

## Pagination

List endpoints are cursor-paginated: pass `limit` (1–100, default 50) and `cursor` (an opaque token from the previous response's `nextCursor`). `nextCursor` is a string when more rows remain, or null on the last page.

## Endpoints

### GET /api/external/v1/entitlements

Returns one entry per subscription the customer has in your shop, each with an `isEntitled` boolean derived from the subscription status. A customer id that does not exist, has no subscriptions, or belongs to another shop returns an empty array (never a 404) so the endpoint can not be used to probe which ids exist. `customerId` is WallaB.AI's internal numeric customer id — deliberately not an email.

- Required scope: `read:entitlements`
- Paginated: no
- Parameters:
  - `customerId` (query, required) — WallaB.AI's internal numeric customer id (a positive integer).

Example response:

```json
{
  "subscriptions": [
    {
      "subscriptionId": 42,
      "planId": 7,
      "planName": "Coffee Club Monthly",
      "planType": "physical",
      "status": "active",
      "isEntitled": true
    }
  ]
}
```

### GET /api/external/v1/subscriptions

Cursor-paginated list of the shop's subscriptions. No customer PII is returned — `customerId` is an opaque, shop-scoped internal id.

- Required scope: `read:subscriptions`
- Paginated: yes (cursor)
- Parameters:
  - `limit` (query, optional) — Page size, 1–100 (default 50). An out-of-band value returns 400.
  - `cursor` (query, optional) — Opaque forward cursor from a previous response's `nextCursor`. Treat it as a token, not a value to construct. An invalid cursor returns 400.
  - `status` (query, optional) — Optional status filter.

Example response:

```json
{
  "subscriptions": [
    {
      "subscriptionId": 501,
      "customerId": 1042,
      "status": "active",
      "planId": 7,
      "planName": "Coffee Club Monthly",
      "planType": "physical",
      "currentPrice": 24.5,
      "nextBillingDate": "2026-08-01T00:00:00.000Z",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "nextCursor": "NTAx"
}
```

### GET /api/external/v1/subscriptions/{id}

One subscription's detail plus its line items. A missing, non-numeric, or another shop's id all return the identical 404 (no id-existence oracle). Line items carry the shop's own catalog fields — that is merchant data, not customer PII.

- Required scope: `read:subscriptions`
- Paginated: no
- Parameters:
  - `id` (path, required) — The numeric subscription id.

Example response:

```json
{
  "subscription": {
    "subscriptionId": 501,
    "customerId": 1042,
    "status": "active",
    "planId": 7,
    "planName": "Coffee Club Monthly",
    "planType": "physical",
    "currentPrice": 24.5,
    "nextBillingDate": "2026-08-01T00:00:00.000Z",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "lineItems": [
      {
        "lineId": 9,
        "productId": 100,
        "productTitle": "Dark Roast",
        "variantId": 200,
        "variantTitle": "12 oz",
        "quantity": 2,
        "currentPrice": 12.5
      }
    ]
  }
}
```

### GET /api/external/v1/metrics/summary

The dashboard KPIs, programmatically — the exact same figures the admin dashboard shows (same engine, so they can never disagree). Aggregate numbers only; no per-customer rows. Money values are in the shop's currency; rates are fractions in [0, 1].

- Required scope: `read:metrics`
- Paginated: no
- Parameters: none

Example response:

```json
{
  "summary": {
    "activeSubscribers": 128,
    "pausedSubscribers": 12,
    "mrr": 3200,
    "revenue30d": 2980,
    "newSubscribers30d": 18,
    "cancelled30d": 4,
    "churnRate30d": 0.031,
    "saveRate": 0.62,
    "cancelSessions30d": 21,
    "dunningActive": 3,
    "recoveryRate": 0.75,
    "failedPayments30d": 2,
    "avgSubscriptionValue": 25,
    "upcomingRenewals7d": 30,
    "upcomingRenewalsValue7d": 740,
    "generatedAt": "2026-07-08T00:00:00.000Z"
  }
}
```

### GET /api/external/v1/plans

The shop's selling plans (your subscribe-and-save cadences), each with a pricing summary, active flag, and product count. Plans per shop are bounded, so the full set is returned unpaginated.

- Required scope: `read:plans`
- Paginated: no
- Parameters: none

Example response:

```json
{
  "plans": [
    {
      "id": 7,
      "name": "Monthly",
      "groupName": "Coffee Club",
      "intervalUnit": "month",
      "intervalCount": 1,
      "active": true,
      "productCount": 4,
      "pricing": {
        "discountType": "percentage",
        "discountValue": 15,
        "summary": "15% off"
      }
    }
  ]
}
```

### GET /api/external/v1/cancellations

Cursor-paginated cancel-save concierge outcomes (the retention audit). Governed by `read:metrics` — the same scope the retention KPIs use, no separate scope to grant. Opaque by construction: `sessionId` is an opaque id and no customer PII is emitted.

- Required scope: `read:metrics`
- Paginated: yes (cursor)
- Parameters:
  - `limit` (query, optional) — Page size, 1–100 (default 50). An out-of-band value returns 400.
  - `cursor` (query, optional) — Opaque forward cursor from a previous response's `nextCursor`. Treat it as a token, not a value to construct. An invalid cursor returns 400.
  - `outcome` (query, optional) — Optional resolved-outcome filter.

Example response:

```json
{
  "cancellations": [
    {
      "sessionId": 88,
      "detectedReason": "too expensive",
      "outcome": "saved",
      "offerType": "offer_discount",
      "createdAt": "2026-06-01T00:00:00.000Z"
    }
  ],
  "nextCursor": null
}
```

## Documentation

- [Getting started](https://wallab.ai/docs/merchants/getting-started): From install to your first subscriber: the self-tracking setup guide.
- [Plans & pricing wizard](https://wallab.ai/docs/merchants/plans-pricing): Selling plans, tiered intro pricing, volume discounts, build-a-box bundles, and prepaid.
- [WallaB concierge & guardrails](https://wallab.ai/docs/merchants/concierge): Configuring the AI cancel-save concierge: allowed actions, discount caps, moderation, and auditability.
- [Win-back & campaigns](https://wallab.ai/docs/merchants/winback-campaigns): Single win-back offers and paced bulk campaigns for cancelled subscribers.
- [Dunning & card-expiry warnings](https://wallab.ai/docs/merchants/dunning-card-expiry): The failed-payment retry ladder and proactive card-expiry emails.
- [Email Studio & sending domains](https://wallab.ai/docs/merchants/email-studio): Customizing every outbound email and verifying your own sending domains.
- [Branding & white-label](https://wallab.ai/docs/merchants/branding): Present the portal, concierge, and emails under your own brand — the three portal-branding controls, email branding, the Pro white-label toggle, and what never changes for shoppers.
- [Integrations: Shopify Flow, Klaviyo & PostHog](https://wallab.ai/docs/merchants/integrations): Fanning subscription lifecycle events out to Flow, Klaviyo, and PostHog.
- [SMS & the consent model](https://wallab.ai/docs/merchants/sms): The concierge over SMS: dual-level consent and carrier keywords.
- [Bulk actions](https://wallab.ai/docs/merchants/bulk-actions): Plan-wide pause, resume, skip, price, and variant changes — preview first.
- [Importing subscribers](https://wallab.ai/docs/merchants/importer): Migrate from any subscription app: a confirmed column mapping, a read-only readiness report, preserved prices and addresses, and a billing hold for a safe cutover.
- [Billing plans & support](https://wallab.ai/docs/merchants/billing-support): WallaB.AI's own pricing ladder, trials, and support SLAs.
- [Performance fees (Retain & Recover)](https://wallab.ai/docs/merchants/performance-fees): How the 1% saved/recovered-revenue fee works: what's credited, the prepaid rule, your monthly cap, and disputing a credit.
- [Skip limits](https://wallab.ai/docs/merchants/skip-limits): Optional merchant caps on how often a subscriber can skip and how far a skip can move the next billing date.
- [Over-Deliver: delight campaigns & Moments](https://wallab.ai/docs/merchants/delight-campaigns): Unadvertised $0 surprise-gift campaigns and tenure-milestone Over-Deliver Moments — generosity that's never a save-offer.
- [Your subscription portal](https://wallab.ai/docs/shoppers/portal): Passwordless sign-in and self-serve skip, pause, swap, cancel, and more.
- [Talking to WallaB](https://wallab.ai/docs/shoppers/talking-to-wallab): What the AI concierge can offer you, and how you stay in control.
- [Text-message keywords](https://wallab.ai/docs/shoppers/sms-keywords): STOP, HELP, and START — what each does, exactly.
- [Developer platform overview](https://wallab.ai/docs/developers/overview): What the WallaB Developer Platform is, what you can build, and where to start.
- [Quickstart](https://wallab.ai/docs/developers/quickstart): Create a key and make your first authenticated API call in under a minute.
- [Authentication & API keys](https://wallab.ai/docs/developers/authentication): Bearer keys, the Growth-plan requirement, scopes, rotation, and keeping keys safe.
- [API reference (v1)](https://wallab.ai/docs/developers/api-reference): The complete v1 reference: base URL, versioning, rate limits, errors, pagination, and every endpoint.
- [MCP server](https://wallab.ai/docs/developers/mcp-server): Connect an AI assistant over the Model Context Protocol: the read-only MCP mirror of the v1 API, with the same keys, scopes, and rate limits.
- [Entitlements API](https://wallab.ai/docs/developers/entitlements-api): Key-authenticated, read-only subscription status lookups for your own systems.
- [Quick-action links & webhooks](https://wallab.ai/docs/developers/quick-action-links): How single-use email action tokens behave, and where webhooks fit.
- [Platform reliability & monitoring](https://wallab.ai/docs/developers/platform-monitoring): How WallaB.AI monitors its own production health — durable event logging, job-queue retries, and automated operator alerting.
- [What is dunning?](https://wallab.ai/docs/glossary/what-is-dunning): Dunning is the automated retry-and-recovery process for a failed subscription payment — and how WallaB's dunning ladder and card-expiry warnings work.
- [What is a cancel-save flow?](https://wallab.ai/docs/glossary/what-is-a-cancel-save-flow): A cancel-save flow offers a subscriber alternatives the moment they try to cancel — and how WallaB's guardrailed AI concierge runs one without dark patterns.
- [Involuntary vs. voluntary churn](https://wallab.ai/docs/glossary/involuntary-vs-voluntary-churn): The difference between churn from a failed payment and churn from an active decision to cancel — and which WallaB features address each.
- [What are prepaid subscriptions?](https://wallab.ai/docs/glossary/what-are-prepaid-subscriptions): Prepaid subscriptions are paid up front for several cycles at once — and how WallaB handles prepaid billing, balance exhaustion, and forfeiture.
- [What is a subscription one-off?](https://wallab.ai/docs/glossary/what-is-a-subscription-one-off): A subscription one-off is a one-time extra item added to a shopper's next scheduled delivery, billed and shipped with that order — and how WallaB handles it on pay-as-you-go subscriptions.