CustomerSubscription

Represents a subscription linking a customer to a plan. Subscriptions define billing periods, pricing, addons, and entitlements for a customer.

Type Definition

type CustomerSubscription {
  id: UUID!
  subscriptionId: String!
  status: SubscriptionStatus!
  pricingType: PricingType!

  # Dates
  startDate: DateTime!
  endDate: DateTime
  effectiveEndDate: DateTime
  trialEndDate: DateTime
  cancellationDate: DateTime
  createdAt: DateTime

  # Billing period
  billingCycleAnchor: DateTime
  currentBillingPeriodStart: DateTime
  currentBillingPeriodEnd: DateTime

  # Related entities
  customer: Customer!
  customerId: UUID
  plan: Plan!
  resource: CustomerResource
  resourceId: UUID
  payingCustomer: Customer
  payingCustomerId: UUID

  # Pricing
  addons: [SubscriptionAddon!]
  prices: [SubscriptionPrice!]
  totalPrice: CustomerSubscriptionTotalPrice
  minimumSpend: SubscriptionMinimumSpend
  freeItems: [FreeSubscriptionItem!]

  # Coupons
  coupon: SubscriptionCoupon
  coupons: [SubscriptionCoupon!]

  # Trial & cancellation
  wasInTrial: Boolean
  cancelReason: SubscriptionCancelReason
  trialConfiguration: TrialConfiguration

  # Budget
  budget: BudgetConfiguration
  budgetExceeded: Boolean

  # Integrations
  billingId: String
  billingLinkUrl: String
  billingSyncError: String
  crmId: String
  crmLinkUrl: String
  salesforceId: String
  syncStates: [SyncState!]

  # Updates
  futureUpdates: [SubscriptionFutureUpdate!]!
  scheduledUpdates: [SubscriptionScheduledUpdate!]
  outdatedPricePackages: [String!]

  # Entitlements
  entitlements: [SubscriptionEntitlementUnion!]
  subscriptionEntitlements: [SubscriptionEntitlement!] @deprecated(reason: "Use entitlements instead")

  # Metadata
  additionalMetaData: JSON
  paymentCollection: PaymentCollection!
  paymentCollectionMethod: PaymentCollectionMethod

  # Invoices
  latestInvoice: SubscriptionInvoice
  lastUsageInvoice: SubscriptionInvoice

  # Experiments
  experiment: Experiment
  experimentInfo: experimentInfo
  environment: Environment!
  environmentId: UUID!
}

Fields

Core Fields

Field	Type	Description
id	UUID!	Unique identifier for the subscription
subscriptionId	String!	Your application’s unique identifier for this subscription
status	SubscriptionStatus!	Current status of the subscription
pricingType	PricingType!	Type of pricing (FREE, PAID, CUSTOM)

Dates

Field	Type	Description
startDate	DateTime!	When the subscription started
endDate	DateTime	Scheduled end date (for fixed-term subscriptions)
effectiveEndDate	DateTime	Actual end date after cancellation
trialEndDate	DateTime	When the trial period ends
cancellationDate	DateTime	When the subscription was cancelled
createdAt	DateTime	When the subscription record was created

Billing Period

Field	Type	Description
billingCycleAnchor	DateTime	Anchor date for billing cycles
currentBillingPeriodStart	DateTime	Start of current billing period
currentBillingPeriodEnd	DateTime	End of current billing period

Related Entities

Field	Type	Description
customer	Customer!	The customer who owns this subscription
customerId	UUID	Customer’s unique ID
plan	Plan!	The plan this subscription is for
resource	CustomerResource	Optional resource this subscription is scoped to
payingCustomer	Customer	Customer responsible for payment (if different)

Pricing

Field	Type	Description
addons	[SubscriptionAddon!]	Addons attached to this subscription
prices	[SubscriptionPrice!]	Price configurations for this subscription
totalPrice	CustomerSubscriptionTotalPrice	Calculated total price
minimumSpend	SubscriptionMinimumSpend	Minimum spend configuration
freeItems	[FreeSubscriptionItem!]	Items included for free

Trial & Cancellation

Field	Type	Description
wasInTrial	Boolean	Whether this subscription was ever in trial
cancelReason	SubscriptionCancelReason	Reason for cancellation
trialConfiguration	TrialConfiguration	Trial settings

Entitlements

Field	Type	Description
entitlements	[SubscriptionEntitlementUnion!]	Entitlements granted by this subscription. Each entry is either a SubscriptionFeatureEntitlement or a SubscriptionCreditEntitlement.
subscriptionEntitlements	[SubscriptionEntitlement!]	Deprecated — use entitlements instead. Feature-only entitlements on this subscription.

SubscriptionEntitlementUnion is a union of SubscriptionFeatureEntitlement (feature access and usage limits) and SubscriptionCreditEntitlement (recurring credit grants with a custom currency, amount, and cadence).

SubscriptionStatus Enum

Value	Description
ACTIVE	Subscription is active and billing
IN_TRIAL	Subscription is in trial period
CANCELED	Subscription has been cancelled
EXPIRED	Subscription has expired
NOT_STARTED	Subscription is scheduled but not started
PAYMENT_PENDING	Awaiting payment confirmation

Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "subscriptionId": "subscription-123",
  "status": "ACTIVE",
  "pricingType": "PAID",
  "startDate": "2024-01-15T00:00:00Z",
  "currentBillingPeriodStart": "2024-01-15T00:00:00Z",
  "currentBillingPeriodEnd": "2024-02-15T00:00:00Z",
  "customer": {
    "customerId": "customer-123",
    "name": "Acme Corp"
  },
  "plan": {
    "refId": "plan-pro",
    "displayName": "Pro Plan"
  },
  "totalPrice": {
    "subTotal": {
      "amount": 99.00,
      "currency": "USD"
    },
    "total": {
      "amount": 99.00,
      "currency": "USD"
    }
  },
  "addons": [
    {
      "addonId": "addon-extra-seats",
      "quantity": 5
    }
  ]
}

Related Types

• Customer - Customer type
• Plan - Plan type
• Price - Price configuration type
• SubscriptionAddon - Subscription addon type
• SubscriptionEntitlementUnion - Union of SubscriptionFeatureEntitlement and SubscriptionCreditEntitlement
• SubscriptionFeatureEntitlement - Feature entitlement on a subscription
• SubscriptionCreditEntitlement - Credit entitlement on a subscription (custom currency, amount, cadence)

Related Operations

• Get Subscription - Fetch a single subscription
• List Subscriptions - Query subscriptions
• Create Subscription - Create new subscription
• Update Subscription - Modify subscription
• Cancel Subscription - Cancel subscription