> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CustomerSubscription

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

## Type Definition

```graphql theme={null}
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!`](/api-and-sdks/api-reference/types/enums#subscriptionstatus) | Current status of the subscription                         |
| `pricingType`    | [`PricingType!`](/api-and-sdks/api-reference/types/enums#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!`](/api-and-sdks/api-reference/types/customer) | The customer who owns this subscription          |
| `customerId`     | `UUID`                                                    | Customer's unique ID                             |
| `plan`           | [`Plan!`](/api-and-sdks/api-reference/types/plan)         | The plan this subscription is for                |
| `resource`       | `CustomerResource`                                        | Optional resource this subscription is scoped to |
| `payingCustomer` | [`Customer`](/api-and-sdks/api-reference/types/customer)  | Customer responsible for payment (if different)  |

### Pricing

| Field          | Type                                                              | Description                                |
| -------------- | ----------------------------------------------------------------- | ------------------------------------------ |
| `addons`       | [`[SubscriptionAddon!]`](/api-and-sdks/api-reference/types/addon) | Addons attached to this subscription       |
| `prices`       | [`[SubscriptionPrice!]`](/api-and-sdks/api-reference/types/price) | 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`](/api-and-sdks/api-reference/types/enums#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.                                             |

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

## 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

```json theme={null}
{
  "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](/api-and-sdks/api-reference/types/customer) - Customer type
* [Plan](/api-and-sdks/api-reference/types/plan) - Plan type
* [Price](/api-and-sdks/api-reference/types/price) - Price configuration type
* [SubscriptionAddon](/api-and-sdks/api-reference/types/addon) - 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](/api-and-sdks/api-reference/queries/get-subscription) - Fetch a single subscription
* [List Subscriptions](/api-and-sdks/api-reference/queries/list-subscriptions) - Query subscriptions
* [Create Subscription](/api-and-sdks/api-reference/mutations/create-subscription) - Create new subscription
* [Update Subscription](/api-and-sdks/api-reference/mutations/update-subscription) - Modify subscription
* [Cancel Subscription](/api-and-sdks/api-reference/mutations/cancel-subscription) - Cancel subscription