Recspert Partner Integration Specification

Audience: Provider integration engineers building API endpoints for Recspert to consume.

Purpose: Documents the API surface Recspert needs from a partner provider system in order to integrate inventory, registrations, and transaction lifecycle.

Status: v1.1 — informed by Recspert's existing partner integrations as of 2026-05-20. Optional capabilities are marked.

Table of Contents

1. Integration Model Overview
2. Authentication
3. Conventions
4. Catalog APIs (Inventory)
5. User & Member APIs
6. Pricing & Checkout APIs
7. Registration APIs (C & P)
8. Package APIs (K)
9. Membership APIs
10. Roster & Reporting
11. Transaction Lifecycle & Source Tracking
12. Webhooks (Optional but Strongly Preferred)
13. Error Handling
14. Rate Limits & SLAs
15. Sandbox / Test Environment
16. Onboarding Checklist
17. Appendix A — End-to-End Flow Walkthroughs
18. Appendix B — Field Reference Quick-Lookup
19. Appendix C — Glossary

1. Integration Model Overview

Recspert is a discovery and registration aggregator. We pull a provider's full activity inventory into our search index, render it on web and mobile, and pass user registrations back to the provider's source-of-truth system in real time. The provider remains the system of record for activities, registrations, packages, and payment.

We classify all activity inventory into three entity types:

A complete integration supports all three. Partial integrations (e.g. C+P only, no K) are viable but limit user value.

Integration phases

This spec describes the Packages tier. Catalog-only is a valid subset that requires only Section 4.

2. Authentication

Recspert authenticates to your APIs server-to-server.

Required: OAuth 2.0 client credentials grant

POST {auth_base}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=...
&client_secret=...
&scope=catalog.read registrations.write packages.write users.write

Response:

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600
}

All subsequent API calls carry Authorization: Bearer {access_token}.

Scopes Recspert will request

Token lifecycle expectations

• Tokens valid for ≥ 30 minutes. Shorter token lifetimes increase request overhead and may degrade user-facing latency.
• Refresh on 401 — Recspert will request a new token and retry once.
• Per-club credentials. Each partner-side organization gets its own client_id/client_secret. Do not require Recspert to broker tokens between organizations.

Alternative: API key

Acceptable for catalog-read-only integrations, not for write paths.

3. Conventions

IDs

• All entity IDs are strings in JSON. Integer IDs are acceptable as long as they round-trip as strings without loss.
• IDs are opaque — Recspert does not parse, compose, or guess them.
• IDs are stable across the entity's lifetime. A renamed class keeps its ID. A deleted-and-recreated class gets a new ID.

Dates & times

• Dates: ISO-8601 YYYY-MM-DD (e.g. 2026-05-19)
• Timestamps: ISO-8601 with timezone, preferably UTC with offset: 2026-05-19T14:30:00-04:00 or 2026-05-19T18:30:00Z
• Class/program local times must also be exposed with the location's IANA timezone (e.g. America/New_York) so Recspert can render correctly across DST and timezones. Returning local time without a timezone is ambiguous and unacceptable.

Currency

• All monetary values in USD cents as integers (e.g. 2500 = $25.00), OR as decimal strings ("25.00"). Pick one and be consistent across the API. Avoid floats.
• Include a currency: "USD" field on every price object even if USD-only — future-proofs multi-currency.

Pagination

• Cursor-based preferred (?cursor=...&limit=100) over offset (?page=2).
• Return nextCursor: null (or omit) on the final page.
• Default page size 100, max 500.

Locale

• All user-facing strings (titles, descriptions, instructor names) returned in a single locale. If you support multiple locales, accept Accept-Language header.

4. Catalog APIs (Inventory)

These endpoints feed Recspert's search index. Recspert polls them on a schedule and caches results (cadence configurable per partner; webhook-driven sync per Section 12 is preferred where supported).

4.1 List clubs

GET /clubs

A "club" is a top-level partner organization (e.g. a Y branch, a fitness studio chain, a campus rec department). One credential set may grant access to one or many clubs.

Response:

{
  "clubs": [
    {
      "id": "12345",
      "name": "Cleveland State University Recreation Center",
      "shortName": "CSU Rec",
      "websiteUrl": "https://www.csurec.com",
      "imageUrl": "https://...",
      "phone": "+1-216-555-0100",
      "email": "rec@csu.edu",
      "address": {
        "street1": "2420 Chester Ave",
        "city": "Cleveland",
        "state": "OH",
        "zip": "44115",
        "country": "US"
      },
      "active": true
    }
  ]
}

4.2 List locations / facilities

GET /clubs/{clubId}/locations

Locations are the physical facilities within a club where activities happen. A program lists one location; a class lists one location and timezone.

Response:

{
  "locations": [
    {
      "id": "loc-456",
      "clubId": "12345",
      "name": "Main Pool",
      "address": { /* same shape as club */ },
      "geo": { "lat": 41.5017, "lng": -81.6792 },
      "timezone": "America/New_York",
      "imageUrl": "https://..."
    }
  ]
}

4.3 List categories

GET /clubs/{clubId}/categories

Categories are how partners group activities (Aquatics, Group Fitness, Personal Training, Youth Sports, etc.). Recspert uses these for filter chips.

Response:

{
  "categories": [
    { "id": "cat-1", "name": "Aquatics", "parentId": null },
    { "id": "cat-2", "name": "Swim Lessons", "parentId": "cat-1" }
  ]
}

4.4 List classes (entityType C)

GET /clubs/{clubId}/classes?from=2026-05-19&to=2026-08-19

Returns scheduled occurrences — one row per class instance. Recurring classes expand into N rows. Recspert calls this with a forward-looking date window.

Response (per class instance):

{
  "classes": [
    {
      "id": "class-789",
      "clubId": "12345",
      "name": "Sunrise Yoga",
      "description": "All-levels yoga to start your day.",
      "categoryIds": ["cat-3"],
      "locationId": "loc-456",
      "instructors": [
        { "id": "instr-1", "name": "Jane Doe", "imageUrl": "https://..." }
      ],
      "startTimestamp": "2026-05-20T10:00:00Z",
      "endTimestamp": "2026-05-20T11:00:00Z",
      "startTimeOfDay": "06:00",
      "endTimeOfDay": "07:00",
      "capacity": 20,
      "availableSpots": 14,
      "status": "open",
      "registrationOpensAt": "2026-05-13T04:00:00Z",
      "registrationClosesAt": "2026-05-20T09:45:00Z",
      "pricing": {
        "memberFee": "0.00",
        "nonMemberFee": "15.00",
        "currency": "USD"
      },
      "imageUrl": "https://...",
      "tags": ["all-levels", "morning"]
    }
  ],
  "nextCursor": null
}

Required fields: id, clubId, name, locationId, startTimestamp, endTimestamp, status, pricing.

4.5 List programs (entityType P)

GET /clubs/{clubId}/programs?from=2026-05-19&to=2026-12-31

Programs are multi-session enrollments. Recspert ingests the program-level record plus its child sessions.

Response:

{
  "programs": [
    {
      "id": "prog-321",
      "clubId": "12345",
      "name": "Learn-to-Swim Level 2 (Tues/Thurs)",
      "description": "...",
      "categoryIds": ["cat-2"],
      "locationId": "loc-456",
      "instructors": [ /* same shape as class */ ],
      "startDate": "2026-06-02",
      "endDate": "2026-07-09",
      "registrationOpensAt": "2026-05-01T04:00:00Z",
      "registrationClosesAt": "2026-06-01T23:59:00Z",
      "pricing": { /* same shape as class */ },
      "capacity": 12,
      "availableSpots": 8,
      "sessions": [
        {
          "id": "sess-1",
          "startTimestamp": "2026-06-02T22:00:00Z",
          "endTimestamp": "2026-06-02T22:45:00Z"
        }
      ],
      "ageRange": { "min": 6, "max": 8 },
      "tags": ["youth", "swim"]
    }
  ]
}

4.6 List packages (entityType K)

GET /clubs/{clubId}/packages

Packages are bundles of redemptions a user pre-buys. They link to one or more activities (Group Ex) or are appointment-based (PT, semi-private).

Response:

{
  "packages": [
    {
      "id": "pkg-654",
      "clubId": "12345",
      "name": "10-Class Group Ex Pass",
      "description": "...",
      "packageType": 1,
      "packageTypeName": "Group Exercise",
      "rates": [
        {
          "id": "rate-1",
          "sessionCount": 1,
          "price": "25.00",
          "currency": "USD"
        },
        {
          "id": "rate-2",
          "sessionCount": 10,
          "price": "200.00",
          "currency": "USD"
        }
      ],
      "memberPrice": "200.00",
      "nonMemberPrice": "250.00",
      "currency": "USD",
      "canExpire": true,
      "expirationPolicy": "12 months after purchase",
      "includedActivities": [
        {
          "seasonName": "Season 2026",
          "activities": ["Sunrise Yoga", "HIIT Bootcamp", "Spin Class"]
        }
      ],
      "imageUrl": "https://..."
    }
  ]
}

packageType values:

• 1 — Group Exercise (redeemable against class registrations)
• 2 — Individual / Personal Training (redeemed via in-person appointment)

includedActivities is required for packageType=1 so users can confirm coverage before purchase.

4.7 List instructors

GET /clubs/{clubId}/instructors

Recspert renders instructor cards on program/class detail pages.

Response:

{
  "instructors": [
    {
      "id": "instr-1",
      "name": "Jane Doe",
      "bio": "...",
      "imageUrl": "https://...",
      "certifications": ["RYT-200", "CPR"]
    }
  ]
}

4.8 Get program details (optional, for deeper enrichment)

GET /clubs/{clubId}/programs/{programId}

Returns the full program record including waiver content, custom field definitions, prerequisites.

5. User & Member APIs

Recspert maintains its own user accounts. When a Recspert user registers at your club for the first time, we create a corresponding user record on your system and store the partnerUserId linkage on our member record.

5.1 Search for an existing user

POST /clubs/{clubId}/users/search

{
  "email": "user@example.com",
  "firstName": "Sam",
  "lastName": "Smith",
  "dateOfBirth": "1990-04-15"
}

Recspert calls this before creating a new user, to avoid duplicates when a Recspert user already has an account at the club from a prior in-person visit.

Field semantics: email is the primary lookup. firstName, lastName, and dateOfBirth are optional search criteria sent when available. Recspert does not collect dateOfBirth from all users (it is not required at Recspert account creation), so the search endpoint must support email-only matches as well as combined-criteria matches. Partners should not reject the search request when only email is provided.

Response:

{
  "users": [
    {
      "id": "user-9999",
      "clubId": "12345",
      "email": "user@example.com",
      "firstName": "Sam",
      "lastName": "Smith",
      "isMember": true,
      "membershipExpiresAt": "2026-12-31",
      "dependents": [
        { "id": "user-9998", "firstName": "Kid", "relationship": "child" }
      ]
    }
  ]
}

5.2 Create a guest user (no membership)

POST /clubs/{clubId}/users

{
  "email": "user@example.com",
  "firstName": "Sam",
  "lastName": "Smith",
  "dateOfBirth": "1990-04-15",
  "phone": "+1-555-555-5555",
  "address": { /* standard address */ },
  "emergencyContact": { "name": "...", "phone": "..." }
}

Required fields: email, firstName, lastName.

Optional fields: dateOfBirth, phone, address, emergencyContact. Recspert sends these when the user has provided them, but does not require them at Recspert signup. Partners must accept user-creation requests when these fields are absent. Partners may legitimately reject downstream actions that depend on the missing data (e.g., registration for an age-gated program where dateOfBirth is required) at the checkout/preview step — see Section 6 — but the user record itself must be creatable without them.

Response:

{ "id": "user-9999", "created": true }

5.3 Add a dependent

POST /clubs/{clubId}/users/{userId}/dependents
{ "firstName": "Kid", "lastName": "Smith", "dateOfBirth": "2018-03-01", "relationship": "child" }

Field semantics: Same optionality as Section 5.2 — firstName and lastName required; dateOfBirth and relationship recommended but optional. Partners may require dateOfBirth at registration time for dependent eligibility checks (e.g., age-gated youth programs).

5.4 List payment methods on file

GET /clubs/{clubId}/users/{userId}/payment-methods

Response:

{
  "paymentMethods": [
    {
      "id": "pm-111",
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "expMonth": 12,
      "expYear": 2028,
      "isDefault": true
    }
  ]
}

5.5 Add a payment method (optional)

POST /clubs/{clubId}/users/{userId}/payment-methods

{ /* PCI-safe tokenized card representation from your payment processor */ }

If you don't expose this, Recspert can only use cards added by the user directly on your portal.

6. Pricing & Checkout APIs

The preview / checkout endpoint is the single most important write-path endpoint. It validates a proposed registration before money moves and returns a confirmed line-item breakdown.

6.1 Preview a class registration

POST /clubs/{clubId}/classes/{classId}/checkout

{
  "classDate": "2026-05-20",
  "userIds": ["user-9999", "user-9998"]
}

Response:

{
  "checkout": {
    "registrants": [
      {
        "userId": "user-9999",
        "name": "Sam Smith",
        "isMember": true,
        "price": "0.00",
        "discounts": [],
        "fees": [],
        "waiversRequired": ["waiver-abc"],
        "customFieldsRequired": ["cf-1"],
        "eligible": true
      }
    ],
    "subtotal": "0.00",
    "tax": "0.00",
    "total": "0.00",
    "currency": "USD",
    "requiredPayment": false,
    "warnings": []
  }
}

Critical fields:

• eligible: false on any registrant — explain why (reason, code) so Recspert can surface a clear error.
• requiredPayment: true — Recspert will require a payment method on the next step.
• waiversRequired, customFieldsRequired — Recspert collects these before submitting.

6.2 Preview a program registration

POST /clubs/{clubId}/programs/{programId}/checkout
{ "startDate": "2026-06-02", "userIds": [...] }

Same shape. Program previews include all sessions in scope.

6.3 Preview a package purchase

POST /clubs/{clubId}/packages/{packageId}/checkout

{
  "userId": "user-9999",
  "rateId": "rate-2"
}

Response:

{
  "checkout": {
    "packageId": "pkg-654",
    "packageName": "10-Class Group Ex Pass",
    "rateId": "rate-2",
    "sessionCount": 10,
    "price": "200.00",
    "tax": "0.00",
    "total": "200.00",
    "currency": "USD"
  }
}

7. Registration APIs (C & P)

7.1 Create a class registration

POST /clubs/{clubId}/classes/{classId}/registrations

{
  "classDate": "2026-05-20",
  "userIds": ["user-9999"],
  "paymentMethodId": "pm-111",
  "waiverSignatures": [
    { "waiverId": "waiver-abc", "signedAt": "2026-05-19T18:00:00Z", "signatureBase64": "..." }
  ],
  "customFieldValues": [
    { "fieldId": "cf-1", "value": "Vegetarian" }
  ]
}

Response:

{
  "registration": {
    "id": "reg-555",
    "classId": "class-789",
    "classDate": "2026-05-20",
    "status": "confirmed",
    "participantList": [
      { "userId": "user-9999", "name": "Sam Smith", "status": "confirmed" }
    ],
    "total": "0.00",
    "paymentMethodId": "pm-111",
    "createdAt": "2026-05-19T18:00:00Z"
  }
}

Failure modes:

• 409 — class is full / no longer eligible. Include code and message for user display.
• 422 — missing waivers, custom fields, or payment method.
• 402 — payment declined. Include processor decline reason.

7.2 Create a program registration

POST /clubs/{clubId}/programs/{programId}/registrations
{ /* same shape; startDate instead of classDate */ }

7.3 Cancel a registration

DELETE /clubs/{clubId}/registrations/{registrationId}

7.4 Get user's upcoming registrations

GET /clubs/{clubId}/users/{userId}/registrations?from=2026-05-19

8. Package APIs (K)

8.1 Buy a package

POST /clubs/{clubId}/users/{userId}/packages

{
  "packageId": "pkg-654",
  "rateId": "rate-2",
  "startDate": "2026-05-19",
  "paymentMethodId": "pm-111"
}

Critical: Reject the request with 422 if paymentMethodId is missing. At least one existing partner API exhibits the failure mode of accepting package buys without a payment method and silently creating an unpaid house-charge against the user's account. This has caused real operational issues. Do not replicate this behavior.

Response:

{
  "packageInstance": {
    "id": "pkginst-777",
    "packageId": "pkg-654",
    "userId": "user-9999",
    "sessionsTotal": 10,
    "sessionsRemaining": 10,
    "purchasedAt": "2026-05-19T18:00:00Z",
    "expiresAt": "2027-05-19",
    "total": "200.00",
    "paymentMethodId": "pm-111",
    "status": "active"
  }
}

8.2 List a user's packages

GET /clubs/{clubId}/users/{userId}/packages

Response:

{
  "packages": [
    {
      "id": "pkginst-777",
      "packageId": "pkg-654",
      "name": "10-Class Group Ex Pass",
      "sessionsTotal": 10,
      "sessionsRemaining": 7,
      "purchasedAt": "2026-05-19T18:00:00Z",
      "expiresAt": "2027-05-19",
      "status": "active",
      "redemptions": [
        { "registrationId": "reg-555", "redeemedAt": "2026-05-20T10:00:00Z" }
      ]
    }
  ]
}

8.3 Apply a package to a class registration

Two acceptable patterns; pick one and document it:

Pattern A (preferred): Auto-apply. When a class registration is created and the user owns an eligible package, the package is automatically debited. Surface this in the registration response (packageApplied: { packageInstanceId, sessionsDebited }).

Pattern B: Explicit. Recspert sends redemption: { packageInstanceId } in the registration body.

Existing partner integrations use Pattern A (with an opt-in keyword on the registration request to redeem a package). Pattern A is simpler to integrate and is preferred.

9. Membership APIs (Optional)

Lets Recspert sell memberships at signup, not just registrations. Skip if memberships are sold only in person.

GET /clubs/{clubId}/membership-groups
POST /clubs/{clubId}/users/{userId}/memberships

Full payload shape covers agreements, signature collection, and dependent-included pricing. Recspert can share its reference implementation against existing partner APIs during integration onboarding.

10. Roster & Reporting

10.1 Class / program roster

GET /clubs/{clubId}/classes/{classId}/roster?date=2026-05-20
GET /clubs/{clubId}/programs/{programId}/roster

Returns participants by user ID. Recspert uses this to render "Who's coming" features and check-in tools.

10.2 Provider stats / audit (optional)

GET /clubs/{clubId}/reports/registrations?from=...&to=...&source=recspert

Lets either party reconcile Recspert-facilitated registrations against the partner's records. Useful for partnership reporting and dispute resolution. Requirement level depends on the commercial model agreed between Recspert and the partner (see Section 11).

11. Transaction Lifecycle & Source Tracking

This section covers two related but distinct capabilities: transaction lifecycle visibility (required for any write integration) and source tracking (recommended; specific contractual requirement depends on the commercial model). Recspert supports multiple commercial models and the integration spec is intentionally model-agnostic.

11.1 Transaction Lifecycle Visibility — REQUIRED

Required for any partner integration that includes registration or package writes. Recspert needs to know, with reasonable confidence and timeliness, the lifecycle state of every transaction it facilitates.

11.1.1 Synchronous confirmation on write

Every write endpoint (registration create, package buy, cancellation) must return a synchronous response confirming the operation's outcome and returning the canonical record. Recspert does not commit downstream actions (charging a service fee, issuing a Wallet pass, sending a confirmation email) until this confirmation is received. See Section 7 and Section 8 for required response shapes.

11.1.2 Cancellation / refund notification

Recspert must be able to learn that a previously confirmed registration has been cancelled or refunded. Acceptable mechanisms:

• Preferred: webhook event registration.cancelled (Section 12)
• Acceptable: GET /clubs/{clubId}/users/{userId}/registrations?modifiedSince=... polled by Recspert
• Acceptable: Status field on the registration object that flips to cancelled (Recspert reconciles via periodic read)

Required to enable Recspert to issue corresponding refunds, remove items from My Schedule, and update Wallet passes.

11.1.3 Registration lookup by reference

Recspert must be able to retrieve a registration record by its partner-issued ID or by a Recspert-supplied reference. Required for user-support escalations, dispute handling (where Recspert needs to evidence to a payment processor that a registration occurred), and reconciliation.

GET /clubs/{clubId}/registrations/{registrationId}

11.2 Source Tracking — RECOMMENDED

Recspert supports multiple commercial models with its partners:

• Platform/technology fee model: Recspert collects its fee directly from the end user via its own payment processor (Stripe) at point of transaction. Partner is not financially involved in Recspert's revenue.
• Revenue share model: Partner pays Recspert a contractually agreed share of Recspert-facilitated registration revenue, settled periodically.
• Hybrid / per-partner negotiated: Mixed approaches.

Source tracking is contractually required only when the commercial model depends on it (revenue share, hybrid arrangements with revenue-share components). Under a pure platform-fee model, source tracking is strongly recommended but not contractually required, because Recspert's fee is collected at point-of-transaction and does not depend on partner-side reconciliation.

Independent of the commercial model, source tracking provides operational value to both parties:

• For the partner: ROI visibility on the Recspert relationship ("Recspert drove $X in registrations to my facility this quarter") — useful for partnership renewal and expansion conversations
• For Recspert: Channel and funnel analytics
• For both: Faster user-support escalations (the partner's CS team can see the registration originated from Recspert and route accordingly)

11.2.1 Recommended: accept a source parameter on every write endpoint

POST /clubs/{clubId}/classes/{classId}/registrations
{
  /* ... */
  "source": "recspert",
  "sourceMetadata": {
    "recspertMemberId": "rsm-12345",
    "recspertReferralCode": "..."
  }
}

11.2.2 Recommended: persist source on the registration / package record

The source should appear on:

• The registration record (queryable in partner reporting)
• Any exported report (CSV, BI feed)
• Webhook payloads (Section 12)

11.2.3 Recommended: filter by source in reports

GET /clubs/{clubId}/reports/registrations?source=recspert

Enables independent reconciliation by either party.

11.2.4 Optional: referral identifier per Recspert user

If the partner system can store a recspertMemberId on the user record (in addition to per-registration), even better — it preserves attribution across the user's lifetime at the partner, not just per-transaction.

11.3 Commercial Model Decision

The choice between platform-fee, revenue-share, or hybrid is made in the commercial agreement between Recspert and the partner, not in this integration spec. If the agreed model is revenue-share or hybrid, all 11.2 items become required rather than recommended, and the report endpoint in Section 10 is the contractual reconciliation surface.

12. Webhooks (Optional but Strongly Preferred)

Polling for catalog changes is wasteful and laggy. Webhooks let us stay in sync within seconds rather than hours.

Events Recspert subscribes to

Delivery requirements

• POST JSON to a Recspert-provided URL
• X-Webhook-Signature: sha256={hmac} header for verification (shared secret per partner)
• Retry with exponential backoff on 5xx or timeout — at least 3 retries over 1 hour
• Idempotency key on each event so Recspert can dedupe

13. Error Handling

Status codes

Error body shape

{
  "error": {
    "code": "CLASS_FULL",
    "message": "Class is at capacity",
    "details": { "classId": "class-789", "capacity": 20, "registered": 20 },
    "userMessage": "Sorry, this class just filled up. Try a later date."
  }
}

• code — machine-readable, stable. Recspert maps these to UI states.
• message — for our logs.
• userMessage — displayed verbatim to end users. Write it for the end user, not the integrator.

14. Rate Limits & SLAs

Expected request volume from Recspert

• Catalog polling: modest, configurable per partner; webhook-driven sync reduces this further
• User-driven (registration, package buy): scales with the partner's active user base
• Bursty: registration-open moments and weekend high-activity periods produce short-duration peaks well above baseline; plan for sustained traffic with brief 10× spikes

Recommended limits

• Catalog reads: ≥ 100 req/min
• Write paths: ≥ 30 req/min sustained, ≥ 100 req/min burst
• Per-user write paths (registrations on one user): ≥ 5 req/min

429 behavior

Return:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Recspert respects Retry-After and backs off.

SLA expectations

• p50 latency under 500ms for reads, under 2s for writes
• p99 under 5s
• Availability ≥ 99.5% monthly

Catalog endpoints under heavier rate limits are tolerable. Write endpoints (registrations, package buys) under heavy throttling translate directly to checkout failures Recspert users see.

15. Sandbox / Test Environment

Required. Recspert cannot integrate against production for QA.

Sandbox requirements

• Separate base URL, separate credentials from prod
• Identical schema and behavior to prod
• Reset-able test data (or auto-reset nightly)
• At least one test card number that always succeeds and one that always declines (Stripe-style)
• At least one test user in a known-member state
• At least one test class that's always open for registration

Acceptable equivalents

• A long-lived dev instance with seeded data
• A "test mode" flag in your prod API that uses test cards / never bills

15.2 Recspert Sandbox

Recspert provides a development environment for partner integration testing.

Sandbox endpoints:

Sandbox access is provisioned manually during onboarding. During the first 2–4 weeks of an integration, expect coordination with the Recspert team for the following:

Self-service sandbox tooling — partner portal for credential management, ingestion log viewer, automated nightly resets, synthetic fixture seeding — is on the roadmap but not yet shipped. Plan on direct support contact during your initial integration.

What the Recspert sandbox does NOT provide:

• A production-like data volume (dev typically holds 1–5% of prod inventory)
• Mirror-of-prod payment processor behavior (Stripe test mode only; no live processor authorization paths)
• SLA guarantees — dev may have unannounced downtime for platform work
• Long-term data persistence — assume data is wiped quarterly or sooner

Production cutover happens only after Section 16's onboarding checklist is complete. Production credentials are issued separately and never shared via the same channel as sandbox credentials.

16. Onboarding Checklist

Hand this back to Recspert when each item is done.

Phase 1 — Read

• Sandbox base URL + credentials issued
• OAuth (or API key) tested end-to-end
• GET /clubs returns at least one club
• GET /clubs/{id}/locations returns ≥ 1 location with timezone
• GET /clubs/{id}/classes returns instances with startTimestamp, pricing
• GET /clubs/{id}/programs returns programs with sessions[]
• GET /clubs/{id}/packages returns packages (rates, packageType, includedActivities for groupex)

Phase 2 — User & Checkout

• POST /users/search works on email
• POST /users creates a guest user
• GET /users/{id}/payment-methods returns saved cards
• POST /classes/{id}/checkout returns eligibility + total

Phase 3 — Write

• POST /classes/{id}/registrations succeeds end-to-end with test card
• POST /programs/{id}/registrations succeeds end-to-end
• POST /users/{id}/packages rejects missing paymentMethodId with 422
• POST /users/{id}/packages succeeds with valid paymentMethodId
• All write responses include the source we sent

Phase 4 — Attribution & Webhooks

• source=recspert persists on registration records
• Report endpoint filters by source
• Webhooks delivered (or polling cadence agreed)

Phase 5 — Production

• Production credentials issued
• Rate limits agreed in writing
• Reconciliation report format agreed (CSV columns, delivery cadence)
• Escalation contact + on-call rotation shared

Appendix A — End-to-End Flow Walkthroughs

The flows below show the exact sequence of calls Recspert makes against a partner API during the most common end-user actions. Use these as integration test scenarios — if all four flows pass, you have a working integration.

A.1 Catalog ingestion (Recspert pulls partner inventory)

Runs on a schedule per partner (cadence configurable; webhook-driven sync per Section 12 reduces or eliminates polling). One sync per club.

Failure handling:

• 401 on any call → refresh token, retry once
• 429 → respect Retry-After, resume from same cursor
• 5xx → exponential backoff up to 3 retries, then abort sync for this club and alert
• Partial sync failures are tolerable; partial catalog is better than no catalog. Recspert flags the partner as "degraded" and continues serving the last good data.

A.2 Class registration (user clicks Register)

End-to-end latency target: under 5 seconds wall-clock.

Critical failure cases:

A.3 Package purchase (user clicks Buy Package)

Critical: Partner MUST reject the POST /packages call with 422 if paymentMethodId is missing. See Section 8.1 for the rationale — a known partner failure mode in this scenario silently creates unpaid house-charges that surface as operational and user-trust problems downstream.

A.4 Webhook delivery (partner notifies Recspert of catalog change)

Recspert webhook receiver expectations:

• Returns within 2 seconds (we ack quickly, process async)
• Returns 200 on success or already-processed (idempotent)
• Returns 401 on signature mismatch — partner must rotate shared secret if this happens unexpectedly
• Returns 5xx only on real outages — partner should retry

Appendix B — Field Reference Quick-Lookup

Required vs. optional fields per entity. For full schemas see the section noted in the rightmost column.

Club (Section 4.1)

Location (Section 4.2)

Class — entityType C (Section 4.4)

Program — entityType P (Section 4.5)

Same fields as Class except:

Package — entityType K (Section 4.6)

User (Section 5)

Checkout / Preview (Section 6)

Registration response (Section 7)

Package Instance (Section 8)

Appendix C — Glossary

• Club — top-level partner organization
• Location — physical facility within a club
• Class (C) — single-occurrence drop-in activity
• Program (P) — multi-session enrollment
• Package (K) — pre-purchased redemption bundle
• Member — user with active membership at the club
• Guest — user without active membership
• Source — referral attribution string (Recspert sends "recspert")
• Recspert member ID — Recspert's internal user identifier, passed in sourceMetadata for cross-system attribution

Document version 1.0 — 2026-05-19. Maintainer: Stuart Gill, Recspert. Send corrections / questions to sgill@recspert.com.