REST: Pro namespace

The Pro plugin registers its own REST namespace, buddynext-pro/v1, with 63 registered routes (across the controllers under includes/). This page is the route reference for developers building on the Pro surfaces: membership and billing, analytics, drip and broadcast campaigns, member labels and plans, moderation rules, AI assistance, scheduled posts, push, saved searches, the member portfolio, Learnomy course links, and the realtime + payment-gateway (Stripe / PayPal) webhook endpoints.

Contract

buddynext-pro/v1 follows the same envelope, error shape, pagination, and wp_rest nonce rules as Free - see the REST contract page (14-rest-contract) for the cross-surface conventions, and REST: Auth and Account (21-rest-auth-account) for the auth flows. Pro-specific points:

• The namespace is buddynext-pro/v1, not buddynext/v1. All paths below are prefixed with /wp-json/buddynext-pro/v1.
• Most routes are admin- or owner-gated. Campaign, moderation-rule, label-admin, analytics-overview, and AI-classify routes require an admin capability. Member-scoped routes (anything under /me/..., own subscriptions, saved searches, push) require login. A few are public reads.
• The payment-webhook routes are open at the permission layer but signed at the payload layer: /stripe/webhook, /stripe/membership-webhook, and /paypal/membership-webhook register permission_callback => __return_true and are authorised entirely by verifying the provider's signature on the payload. /realtime/auth is login-gated and additionally enforces per-channel access. See the highlight below - "open" does not mean "unauthenticated trust".

Source of truth: the controllers under includes/ in the Pro plugin - grep register_rest_route( for the buddynext-pro/v1 namespace.

Open-but-signed routes (read this first)

/stripe/webhook has no WordPress capability check because Stripe calls it server-to-server with no session; its trust comes entirely from the HMAC signature on the payload. /realtime/auth is login-gated and additionally enforces per-channel access before returning the signature, so a logged-in user cannot subscribe to a channel they are not entitled to.

Routes by domain

Membership: plans, checkout, subscriptions

Plans are the membership plans. Plan CRUD lives under /tiers; the buyer-facing checkout flow (plan list, gateway list, checkout, quote) lives under /membership/* in Membership/CheckoutController; subscriptions and the billing portal live in Membership/Controllers/SubscriptionsController.

The capabilities block on /me/subscriptions

Every row carries capabilities, and any client rendering a membership control should read it rather than deriving the rules again. That is not style advice: the same rules exist in the cancel endpoint, the plan-change service and the gateway registry, and every time a surface has re-derived them it has drifted - a Cancel button that 409'd on click, a Switch button that worked for a member billed by WooCommerce.

The response is a bare array (typed MySubscription[] by the mobile app), so the block is a key on each element rather than a sibling of the list; wrapping the list would break every installed copy.

Two rules that make the difference between a correct client and a plausible one:

• If a control is hidden, show reason. Silence reads as a broken screen. The string is the same sentence the endpoint would return if the member forced the request, so the explanation and the refusal cannot describe different rules.
• Never infer one key from another. can_update_payment is the clearest case: Offline is billed_by: gateway and still has no portal, so billed_by === 'gateway' is not a substitute.

Member plans vs labels

Analytics

Drip sequences

Broadcasts

Email preferences

Moderation rules and AI

Scheduled posts

Push notifications

Saved searches

Member portfolio

Learnomy course links

Course-space linking for the Learnomy integration (Integrations/Learnomy/LearnomyLinkController). Registered only when Learnomy is active.

Realtime and payment webhooks

Example: create a checkout session

curl -X POST https://example.com/wp-json/buddynext-pro/v1/membership/checkout \
  -H 'Content-Type: application/json' \
  -H 'X-WP-Nonce: <wp_rest nonce>' \
  --cookie 'wordpress_logged_in_...=...' \
  -d '{ "plan_id": 12, "gateway": "stripe" }'

The handler (Membership/CheckoutController::handle_checkout) takes a required plan_id (plus optional gateway, mode, coupon, country) and returns a gateway checkout URL for the current user to redirect to. After payment, the gateway calls back into its membership webhook (POST /stripe/membership-webhook or POST /paypal/membership-webhook), which verifies the signature and updates the user's subscription. The user can later open the billing portal with POST /me/billing-portal.

Notes

• Mixed-permission routes. /tiers, /tiers/{id}, and /labels register more than one method with different gates - the GET read is public or member-facing, the write (POST/PUT/DELETE) is admin. Treat the "Auth" column as per-method.
• Pro requires Free. These routes only register when Pro is active, and they read Free data (spaces, posts, follows, analytics tables) through Free services. The namespaces stay separate: Free is buddynext/v1, Pro is buddynext-pro/v1.
• Webhook secret is a setup precondition. /stripe/webhook returns stripe_webhook_secret_missing until the Stripe webhook secret is configured in the membership settings - that is required setup, not a fault.