Sellxora API Documentation

API version: v1 for new contracts; existing unversioned /api endpoints remain available for compatibility.

Base URL: https://your-domain.example/api

Content type: application/json

Important security statement

Sellxora APIs are not a back door around the application’s subscription, ownership, role, or publication rules. A request can be authenticated and still be rejected because the account does not have the required SaaS product group, the requested record belongs to another account, the user is not an administrator, or the relevant provider or asset is not in a valid state.

Never place passwords, API keys, OAuth secrets, payment credentials, wallet addresses, webhook signing secrets, private customer exports, or provider access tokens in a URL, query string, log message, public page, or client-side source bundle.

1. Access classes

Access class	Meaning	Typical response
Public	Safe for an unauthenticated browser or public integration	200, 201, 404, 422, or throttling response
Authenticated	Requires a valid Laravel Sanctum bearer token	401 when missing or invalid
Owner-scoped	Authenticated access is restricted to the current account’s records	404 for a record outside the account, where practical
SaaS-gated	Requires authentication plus an active product-group subscription	403 with the required group and upgrade URL
Administrator-only	Requires authentication and administrator authorization	403 for non-admin users
Signed provider webhook	Public network endpoint, but accepted only after provider signature and idempotency checks	401, 403, 409, or provider-specific response

2. Authentication

Protected endpoints use Laravel Sanctum bearer tokens. Send the token in the Authorization header:

Authorization: Bearer {sanctum-token}
Accept: application/json
Content-Type: application/json

Tokens are issued by the existing authentication endpoints. Tokens should be treated like passwords, stored only in a protected client credential store, assigned a meaningful device name, and revoked when a device is lost or access is no longer required.

Public authentication endpoints

Method	Endpoint	Purpose	Privacy
POST	/api/auth/register	Create an account	Public; validate and rate-limit all input
POST	/api/auth/login	Issue a Sanctum token	Public; never disclose whether an email exists beyond the documented response
POST	/api/auth/forgot-password	Start password recovery	Public; do not expose account existence
POST	/api/auth/reset-password	Complete password recovery	Public with reset token

Protected account endpoints

Method	Endpoint	Purpose	Access
POST	/api/auth/logout	Revoke the current token	Authenticated
GET	/api/auth/me	Return the current user profile	Authenticated, self only
PUT	/api/auth/profile	Update permitted profile fields	Authenticated, self only
PUT	/api/auth/change-password	Change the current password	Authenticated, self only
POST	/api/auth/push-token	Register a push token	Authenticated, self only; token is write-only in spirit
DELETE	/api/auth/push-token	Revoke the current push token	Authenticated, self only

The response from /api/auth/me must not be interpreted as permission to access every module. Use the entitlement contract below and expect each module endpoint to apply its own server-side gate.

3. Versioned platform contracts

GET /api/v1/modules

Returns a public catalog of Sellxora product groups. It contains labels, included product areas, and whether a group is an anchor. It does not contain internal controller names, private plan settings, provider keys, customer data, or administrator configuration.

Example:

{
  "success": true,
  "api_version": "v1",
  "data": [
    {
      "key": "landing_page",
      "label": "Landing Page",
      "modules": ["Landing Page", "Forms", "Website Builder", "File Manager"],
      "anchor": true,
      "subscription_required": true
    }
  ]
}

GET /api/v1/account

Returns only the current account’s safe identity fields and product-group entitlement summary. It does not return passwords, session secrets, user settings, plan settings, customer data, payment metadata, wallet details, provider credentials, or raw ledger entries.

Example:

{
  "success": true,
  "api_version": "v1",
  "data": {
    "user": {
      "id": 12,
      "name": "Example User",
      "email": "[email protected]",
      "country": "NG",
      "currency": "NGN",
      "role": "user"
    },
    "product_groups": [
      {
        "key": "ecommerce",
        "label": "Ecommerce",
        "active": true,
        "legacy_access": false,
        "package": {"id": 4, "title": "Store Pro"},
        "billing_cycle": "monthly",
        "currency": "NGN",
        "starts_at": "2026-08-23T10:00:00+00:00",
        "ends_at": "2026-09-23T10:00:00+00:00"
      }
    ]
  }
}

4. FAQ API

FAQ content is public only after an administrator publishes it. Draft, archived, and administrator-only FAQ records are not returned.

Method	Endpoint	Purpose	Access
GET	/api/v1/faq	Search and list published FAQs	Public
GET	/api/v1/faq/{slug}	Read one published FAQ	Public

Supported query parameters for the collection endpoint are q, category, and per_page. The server clamps page size to a safe range. FAQ answers are published content; do not use the endpoint to transmit private support conversations or tenant-specific data.

5. SaaS, pricing, and billing

The existing SaaS endpoints remain available for pricing and the current user’s billing state.

Method	Endpoint	Purpose	Access
GET	/api/saas/packages	List active package prices; supports currency	Public
GET	/api/saas/packages/{id}	Read one active package	Public
GET	/api/saas/subscription	Read current subscription and feature summary	Authenticated, self only
GET	/api/saas/gateways	List gateways available for the current currency	Authenticated, self only
GET	/api/saas/billing	Read current user payment history	Authenticated, self only
GET	/api/saas/billing/{id}	Read one current-user payment	Authenticated, self only

Package responses may include public prices and documented feature summaries. They must not expose gateway secret keys, private administrator settings, other users’ subscriptions, or raw payment-provider payloads.

6. Landing Page and Website Builder

Landing Page and Website Builder APIs are protected by the Landing Page anchor subscription group. Requests are also owner-scoped by the authenticated user. Custom domains, custom code, branding removal, AI usage, export, and other limits are separately checked where applicable.

Module	Endpoint family	Access
Landing Page	/api/landing-pages, /api/landing-pages/{code}, and page lifecycle/builder endpoints	Authenticated + Landing Page subscription + owner-scoped
Website Builder	/api/websites, /api/websites/{code}, page lifecycle, SEO, AIEO, and audit endpoints	Authenticated + Landing Page subscription + owner-scoped
Public landing forms	/api/pages/{code}/submit where configured for a published page	Public submission; no private builder access

Builder APIs accept page content only for the authenticated owner. Do not return unpublished page content to public callers. Public form submission must validate the published page, strip reserved fields, enforce the configured field rules, and avoid returning stored lead details.

7. Forms and leads

Method	Endpoint	Purpose	Access
GET	/api/leads	List current-user leads	Authenticated, owner-scoped
GET	/api/leads/{id}	Read one current-user lead	Authenticated, owner-scoped
PUT	/api/leads/{id}	Update permitted lead field values	Authenticated, owner-scoped
DELETE	/api/leads/{id}	Delete a current-user lead	Authenticated, owner-scoped
POST	/api/pages/{code}/submit	Submit a published page form	Public submission only

Lead APIs contain personal data. They must never return another user’s leads, allow arbitrary owner identifiers, or include private credentials. Data export remains subject to the applicable SaaS feature flag.

8. Ecommerce

Ecommerce APIs require auth:sanctum, the ecommerce SaaS product group, and owner scoping. Ecommerce product, category, and order resources are private to the store owner unless a specific storefront route documents otherwise.

Method	Endpoint	Purpose	Access
GET	/api/products	List current-user products	Authenticated + Ecommerce subscription
POST	/api/products	Create a product	Authenticated + Ecommerce subscription + plan limits
GET	/api/products/{id}	Read current-user product	Authenticated + Ecommerce subscription + owner-scoped
PUT	/api/products/{id}	Update current-user product	Authenticated + Ecommerce subscription + owner-scoped
DELETE	/api/products/{id}	Delete current-user product	Authenticated + Ecommerce subscription + owner-scoped
GET	/api/categories	List current-user categories	Authenticated + Ecommerce subscription
GET	/api/orders	List current-user store orders	Authenticated + Ecommerce subscription + owner-scoped
GET	/api/orders/{id}	Read current-user order	Authenticated + Ecommerce subscription + owner-scoped
PATCH	/api/orders/{id}/status	Change permitted order status	Authenticated + Ecommerce subscription + owner-scoped
PATCH	/api/orders/{id}/paid	Change payment state where permitted	Authenticated + Ecommerce subscription + owner-scoped
DELETE	/api/orders/{id}	Delete an order where permitted	Authenticated + Ecommerce subscription + owner-scoped

Order responses may contain buyer personal information because they are private merchant records. They must not expose gateway secrets, complete webhook payloads, unmasked payment credentials, or another store’s order data. Public checkout and payment webhook routes must validate store ownership, currency/gateway availability, signatures, idempotency, inventory, and final payment state.

9. Creator

Creator is a free product area, but it is still authenticated and owner-scoped for private management APIs. A free module must not be interpreted as a public data API.

Method	Endpoint	Purpose	Access
GET	/api/v1/creator/products	List the current creator’s product summaries	Authenticated, owner-scoped
GET	/api/v1/creator/orders	List the current creator’s order and payout-status summaries	Authenticated, owner-scoped

The Creator API intentionally omits buyer identity, delivery destinations, protected grant tokens, gateway credentials, internal metadata, and full payout destinations from these summary responses. Product creation, buyer checkout, delivery, and payment webhooks remain subject to their specific web/API contracts and state checks.

Physical products belong in Ecommerce rather than the Creator product workflow. Creator checkout still requires buyer name, email, and phone with country code, plus any product-specific fields defined by the creator.

10. Blog

Public Blog JSON APIs return only published publications and posts. Drafts, scheduled posts, unpublished connected blogs, private settings, owner details, and standalone administration data are excluded.

Method	Endpoint	Purpose	Access
GET	/api/v1/blogs	List published publications	Public
GET	/api/v1/blogs/{slug}	Read one published publication and its published-post summaries	Public

Standalone Blog creation and management remains administrator-restricted under the web workflow. Site users’ connected Blog operations remain owner-scoped and subject to the Blog prerequisites and subscription rules.

11. Content Hub

Content Hub APIs require Sanctum authentication, the content_hub SaaS group, and owner scoping.

Method	Endpoint	Purpose	Access
GET	/api/v1/content-hub/channels	List connected-channel metadata	Authenticated + Content Hub subscription + owner-scoped
GET	/api/v1/content-hub/posts	List content-post scheduling metadata	Authenticated + Content Hub subscription + owner-scoped

Channel responses never include access tokens, refresh tokens, client secrets, private callback data, or full credential objects. Post responses omit private body metadata and storage internals unless an endpoint explicitly documents a safe representation. Creating, updating, deleting, scheduling, AI generation, credit metering, and publishing actions must apply the same owner, quota, provider, and credit rules as the web workflow.

12. Advertising

Advertising APIs require Sanctum authentication, the advertising SaaS group, and owner scoping.

Method	Endpoint	Purpose	Access
GET	/api/v1/advertising/overview	Read provider, destination, and campaign status summaries	Authenticated + Advertising subscription + owner-scoped

The overview includes provider names, non-secret account identifiers, destination labels and status, campaign objective/status/mode, and safe budget fields. It never returns access tokens, refresh tokens, provider secrets, raw targeting payloads, webhook secrets, or another account’s destination. Provider mutation, AI generation, creative upload, and autopilot actions remain explicitly gated and must fail closed if the provider adapter is not configured.

13. Affiliate

Affiliate access does not become a license to read another affiliate’s financial records. The summary API is private and scoped to the current authenticated affiliate.

Method	Endpoint	Purpose	Access
GET	/api/v1/affiliate/summary	Read current affiliate balance, status, code, and safe payout-profile state	Authenticated, current affiliate only

The response does not return wallet addresses, country-specific payout details, full ledger entries, provider transaction metadata, customer identity, or administrator-only commission controls. Affiliate attribution continues to use trusted validated referral state rather than buyer-submitted affiliate identifiers. Payout requests remain subject to profile verification, balance, suspension, asset, network, and administrator-review rules.

14. File Manager and media

Method	Endpoint	Purpose	Access
GET	/api/v1/files	List current-user file metadata	Authenticated + Landing Page anchor subscription + owner-scoped

The API returns file metadata and a usable file URL where the configured storage policy allows it. It does not return internal storage paths, another user’s files, private disk credentials, or server filesystem locations. Upload and delete actions must enforce the same MIME allowlist, blocked-extension rules, quota, R2/storage, and owner checks as the web workflow.

15. Marketing, CRM, Contacts, Teams, and Settings

These existing route groups predate the new versioned contracts and remain available while their clients migrate. Their access class is summarized below.

Area	Existing endpoint family	Access boundary
Marketing leads and contact upsert	/api/marketing/...	Authenticated with Marketing/Sales group gate; owner-scoped
WhatsApp inbox	/api/marketing/inbox/whatsapp/...	Authenticated with Marketing/Sales group gate; owner-scoped
Marketing tags	/api/marketing/tags	Authenticated with Marketing/Sales group gate; owner-scoped
Marketing provider/chatbot webhooks	/api/marketing/... webhook routes	Public network endpoint only with provider signature, event validation, and idempotency
Public contact form	/api/contact	Public input; rate-limited and validated; no admin data returned
Contact administration	/api/contacts	Administrator-only; contact PII must not be returned to ordinary users
Teams	/api/teams	Sanctum; owner/team permission checks; universal plan member limit
Legacy Staff alias	/api/staff	Sanctum; retain only for compatibility; use Teams for new clients
Application settings	/api/app-info and /api/settings/...	Public endpoint returns safe bootstrap data only; private settings require authenticated owner/admin rules

Marketing and CRM APIs can contain contact PII, message content, invoice data, provider configuration, and automation details. Do not expose full settings objects, SMTP passwords, API tokens, webhook secrets, or unredacted provider responses.

16. Legacy and placeholder API routes

Some older module files still contain placeholder or legacy-style auth:api routes. They should not be used for new integrations because the current contract is Sanctum plus explicit SaaS and ownership checks. The following areas require migration or review before being treated as production API contracts:

Area	Current state	Guidance
BlocksLandingPage, ModulesManager, PagesWebsite, Install, and Themes placeholders	Legacy auth:api or placeholder route behavior	Do not build new clients against these stubs; migrate to a documented Sanctum endpoint before production use
Template APIs	Route file exists but no mature public contract	Keep private until a specific safe resource contract is implemented
Blog, Content Hub, Advertising, Affiliate, Creator, File Manager	New safe summary contracts added under /api/v1	Use the versioned routes documented above

A route’s presence in route:list is not proof that the endpoint is safe or complete. Every endpoint must be backed by a controller contract, tests, ownership checks, and a documented response shape.

17. Error contract

Clients should handle errors by HTTP status and the stable fields that are present, not by matching translated message text.

{
  "message": "The request could not be completed.",
  "errors": {
    "field": ["The field is invalid."]
  },
  "error_code": "validation_failed"
}

Status	Meaning
200	Successful read or update
201	Successful creation or accepted public submission
400	Malformed request or invalid state transition
401	Missing, expired, or invalid authentication
403	Authenticated but not entitled, not an owner, suspended, or not an administrator
404	Resource is not visible to this caller or does not exist
409	Idempotency or state conflict, such as a repeated provider event
422	Field validation failed
429	Rate limit exceeded
500/503	Temporary service or provider failure; do not treat as a successful payment or publication

For SaaS-gated JSON requests, the response should include an upgrade URL and group key when available:

{
  "error": "This module requires an active Content Hub subscription.",
  "upgrade_url": "https://your-domain.example/billing/upgrade?group_key=content_hub",
  "group_key": "content_hub"
}

18. Rate limiting, pagination, and idempotency

API routes use the application API throttle group. Clients should use exponential backoff after 429, avoid aggressive polling, and cache public catalogs. Collection endpoints support pagination where documented; do not request unbounded records.

For payment, webhook, credit, payout, commission, and external-publication operations, clients must preserve and resend the documented idempotency or provider event identifier when retrying. A timeout does not mean that the operation failed. Query the resulting status before retrying a financial or externally mutating action.

19. Privacy and data-handling rules

The safe default is to return the minimum fields required for the documented use case. Responses must be owner-scoped by server-side queries rather than by trusting a user_id supplied by the caller. Public endpoints must return published or deliberately public records only.

The following fields are private or write-only unless a narrowly scoped endpoint explicitly documents their use: passwords, password reset tokens, Sanctum tokens, push tokens, SMTP credentials, OAuth access and refresh tokens, payment gateway secrets, webhook signing keys, wallet addresses, country-specific payout details, internal ledger metadata, raw provider payloads, customer exports, storage disk credentials, and server filesystem paths.

Administrators may see additional operational data only through administrator-authorized endpoints. Administrator status must be enforced on the server; hiding a button in a client does not create authorization.

20. Integration workflow

A responsible integration should first call the public module catalog, authenticate, call /api/v1/account, and then use only the endpoint families allowed by the returned account state. The client must still handle 403 because entitlements may expire or change between requests.

# Public discovery
curl -sS https://your-domain.example/api/v1/modules

# Authenticate using the existing login contract, then call the private account contract
curl -sS https://your-domain.example/api/v1/account \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_SANCTUM_TOKEN'

# Read only the current user's Content Hub metadata when entitled
curl -sS 'https://your-domain.example/api/v1/content-hub/posts?per_page=20' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_SANCTUM_TOKEN'

Do not put bearer tokens in shell history, screenshots, analytics, support tickets, or source control. Rotate a token immediately if it is exposed.

21. Versioning and deprecation policy

New contracts use /api/v1. Existing unversioned routes are retained for compatibility but may have older response shapes, middleware names, or field conventions. New clients should not depend on undocumented routes or placeholder endpoints.

A future breaking change should use /api/v2, keep the old contract during a stated migration period, document the deprecation date, and provide a migration table. Renaming a field, changing currency semantics, changing a status value, or changing whether a record is public is a breaking API change.

22. Operational checklist for administrators

Before enabling an API client in production, confirm that the client has a documented purpose, uses Sanctum or the appropriate signed provider mechanism, requests only the minimum data, handles 401, 403, 404, 409, 422, and 429, respects the relevant SaaS plan, and never stores private response fields in logs.

Before enabling a new module API, confirm that every query is owner-scoped, every mutation has authorization and CSRF-independent API authentication, every SaaS requirement is enforced server-side, every sensitive field is excluded from serialization, every external callback is signed and idempotent, and the endpoint has feature tests for both an entitled owner and an unauthorized or unentitled user.

References

This document is the canonical Sellxora API contract for the current application implementation. The public HTML version is available at /api/docs.