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

# GraphQL API Overview

The Stigg GraphQL API provides comprehensive access to pricing, entitlement, and subscription management functionality. This guide covers everything you need to get started.

<Card title="API Playground" icon="play" href="https://studio.apollographql.com/public/Stigg-API/variant/Production/explorer">
  Interact with Stigg's GraphQL API directly from your browser.
</Card>

## Endpoint

```
POST https://api.stigg.io/graphql
```

## Authentication

All requests require an API key in the `X-API-Key` header:

```bash theme={null}
curl -X POST https://api.stigg.io/graphql \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"query": "..."}'
```

## GraphQL Basics

### Queries

Queries are used to fetch data without side effects:

```graphql theme={null}
query GetCustomer($input: GetCustomerByRefIdInput!) {
  getCustomerByRefId(input: $input) {
    customerId
    name
    email
    subscriptions {
      subscriptionId
      status
    }
  }
}
```

### Mutations

Mutations create, update, or delete data:

```graphql theme={null}
mutation ProvisionCustomer($input: ProvisionCustomerInput!) {
  provisionCustomer(input: $input) {
    customer {
      customerId
    }
    subscription {
      subscriptionId
    }
  }
}
```

### Variables

Pass variables separately from the query:

```json theme={null}
{
  "query": "query GetCustomer($input: GetCustomerByRefIdInput!) { ... }",
  "variables": {
    "input": {
      "customerId": "customer-123"
    }
  }
}
```

## Common Patterns

### Pagination

List queries use cursor-based pagination:

```graphql theme={null}
query ListCustomers {
  customers(
    paging: { first: 10, after: "cursor123" }
  ) {
    edges {
      node {
        customerId
        name
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}
```

### Filtering

Filter results using the `filter` parameter:

```graphql theme={null}
query ListActiveCustomers {
  customers(
    filter: {
      hasActiveSubscription: { eq: true }
      createdAt: { gte: "2024-01-01T00:00:00Z" }
    }
  ) {
    edges {
      node {
        customerId
      }
    }
  }
}
```

### Sorting

Sort results using the `sorting` parameter:

```graphql theme={null}
query ListCustomersByDate {
  customers(
    sorting: [{ field: createdAt, direction: DESC }]
  ) {
    edges {
      node {
        customerId
        createdAt
      }
    }
  }
}
```

## Error Handling

Errors are returned in the `errors` array:

```json theme={null}
{
  "data": null,
  "errors": [
    {
      "message": "Customer not found",
      "extensions": {
        "code": "CUSTOMER_NOT_FOUND",
        "isValidationError": false
      }
    }
  ]
}
```

### Common Error Codes

| Code                         | Description                |
| ---------------------------- | -------------------------- |
| `UNAUTHENTICATED`            | Invalid or missing API key |
| `CUSTOMER_NOT_FOUND`         | Customer doesn't exist     |
| `SUBSCRIPTION_NOT_FOUND`     | Subscription doesn't exist |
| `FEATURE_NOT_FOUND`          | Feature doesn't exist      |
| `VALIDATION_ERROR`           | Invalid input parameters   |
| `ENTITLEMENT_LIMIT_EXCEEDED` | Usage would exceed limit   |

## Subscriptions (Real-time)

The API supports GraphQL subscriptions for real-time updates:

```graphql theme={null}
subscription EntitlementsUpdated {
  entitlementsUpdated {
    customerId
    entitlements {
      feature {
        refId
      }
      isGranted
    }
  }
}
```

Available subscriptions:

* `entitlementsUpdated` - Customer entitlement changes
* `usageUpdated` - Usage updates
* ~~`creditBalanceUpdated`~~ - Credit balance changes (**deprecated** — use `usageUpdated` instead)
* `packagePublished` - Package publication events