Skip to main content
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
  subscriptionEntitlements: [SubscriptionEntitlement!]

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

  # Invoices
  latestInvoice: SubscriptionInvoice
  lastUsageInvoice: SubscriptionInvoice

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

​
Fields

​
Core Fields

FieldTypeDescription
idUUID!Unique identifier for the subscription
subscriptionIdString!Your application’s unique identifier for this subscription
statusSubscriptionStatus!Current status of the subscription
pricingTypePricingType!Type of pricing (FREE, PAID, CUSTOM)

​
Dates

FieldTypeDescription
startDateDateTime!When the subscription started
endDateDateTimeScheduled end date (for fixed-term subscriptions)
effectiveEndDateDateTimeActual end date after cancellation
trialEndDateDateTimeWhen the trial period ends
cancellationDateDateTimeWhen the subscription was cancelled
createdAtDateTimeWhen the subscription record was created

​
Billing Period

FieldTypeDescription
billingCycleAnchorDateTimeAnchor date for billing cycles
currentBillingPeriodStartDateTimeStart of current billing period
currentBillingPeriodEndDateTimeEnd of current billing period
FieldTypeDescription
customerCustomer!The customer who owns this subscription
customerIdUUIDCustomer’s unique ID
planPlan!The plan this subscription is for
resourceCustomerResourceOptional resource this subscription is scoped to
payingCustomerCustomerCustomer responsible for payment (if different)

​
Pricing

FieldTypeDescription
addons[SubscriptionAddon!]Addons attached to this subscription
prices[SubscriptionPrice!]Price configurations for this subscription
totalPriceCustomerSubscriptionTotalPriceCalculated total price
minimumSpendSubscriptionMinimumSpendMinimum spend configuration
freeItems[FreeSubscriptionItem!]Items included for free

​
Trial & Cancellation

FieldTypeDescription
wasInTrialBooleanWhether this subscription was ever in trial
cancelReasonSubscriptionCancelReasonReason for cancellation
trialConfigurationTrialConfigurationTrial settings

​
SubscriptionStatus Enum

ValueDescription
ACTIVESubscription is active and billing
IN_TRIALSubscription is in trial period
CANCELEDSubscription has been cancelled
EXPIREDSubscription has expired
NOT_STARTEDSubscription is scheduled but not started
PAYMENT_PENDINGAwaiting 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
    }
  ]
}