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 |
| 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
}
]
}
- Customer - Customer type
- Plan - Plan type
- Price - Price configuration type
- SubscriptionAddon - Subscription addon type
SubscriptionEntitlementUnion - Union of SubscriptionFeatureEntitlement and SubscriptionCreditEntitlementSubscriptionFeatureEntitlement - Feature entitlement on a subscriptionSubscriptionCreditEntitlement - Credit entitlement on a subscription (custom currency, amount, cadence)
