subscriptions

Get current organization trial state

Return the organization's authoritative trial state (WBC-164).

Additive, read-only surface consumed by the in-product trial indicator (WBC-166), HubSpot sync (WBC-168), and billing emails (WBC-169). trialStatus is derived (never stored) from Orb + payment state.

trialEndsAt is the time-based trial end (signup + 14 days) today. Credit exhaustion does not shorten it: the zero-balance timestamp needs an Orb-ledger fetch this endpoint does not make, so it is left unset rather than fabricated. Credit exhaustion ends the trial early via WS4 events (WBC-766), which flip the plan/subscription this endpoint already reflects. Do not read trialEndsAt as credit-aware, and do not treat trialCreditsRemaining == 0 as "trial over". See :mod:src.internal.billing.trial_state.

Degrades gracefully: an org with no trial data -- every org until the WBC-763 trial-grant flag is enabled -- gets all-null fields rather than an error. All upstream Orb failures (transport errors, an unconfigured client, the multi-subscription guard) also degrade to all-null, never a 500.

get/subscriptions/trial-state

Request

  • Base URL: https://api.cloud.wherobots.com
  • URL: https://api.cloud.wherobots.com/subscriptions/trial-state
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Response

Successful Response

trialStartedAtstring date-time nullable
trialEndsAtstring date-time nullable
trialCreditsRemainingstring nullable
trialStatus'active' | 'converted' | 'expired' | 'canceled' | 'ending_soon'

Derived lifecycle status of an organization's Professional trial.

Wire values (lowercased member names, matching the repo's other LowercaseStrEnum enums):

ACTIVE - "active" trial live, with or without a card on file (WBC-855). Read hasPaymentMethod for card presence. CONVERTED - "converted" the trial finished with a valid payment method on file, so the org rolled onto paid usage. Also an org whose delinquency downgrade is in effect (WBC-766): it converted and then stopped paying, which computeStatus reports as zero_compute -- it is not an expired trial. EXPIRED - "expired" trial lapsed with no card -> downgraded to Community. CANCELED - "canceled" subscription cancelled / org deleted without converting. ENDING_SOON - "ending_soon" credit-based flavor, set when the credit_balance_dropped signal fires while the trial is still live. The time-based "ending soon" flavor is derived downstream by consumers from trialEndsAt.

computeStatus'full' | 'zero_compute'

Two-tier entitlement / zero-compute state (see WS2/WS3).

FULL - "full" compute entitlement is intact. ZERO_COMPUTE - "zero_compute" compute is withdrawn (trial expired or cancelled without converting).

The full WS2/WS3 entitlement semantics land with WBC-766; here we expose a conservative two-tier value derived from the trial status so downstream consumers have the field available.

hasPaymentMethodboolean required

Changes

No recorded changes to this operation across all 1 revision of this API.