openapi: 3.0.3 info: title: Stigg Coupons Usage API description: Stigg is a pricing and packaging platform providing feature management, entitlements, and usage-based billing for SaaS and API products. The Stigg API exposes GraphQL and REST endpoints for customer provisioning, subscription management, entitlement checking, and usage reporting. Authentication requires a Full access key passed via the X-API-KEY header. version: '1.0' contact: url: https://www.stigg.io/ termsOfService: https://www.stigg.io/terms servers: - url: https://api.stigg.io description: Stigg Production API security: - ApiKey: [] tags: - name: Usage description: Usage reporting and metering. paths: /graphql: post: operationId: executeGraphQL summary: Execute GraphQL Query or Mutation description: Execute any Stigg GraphQL query or mutation. Stigg uses GraphQL as its primary API. Send a JSON body with a query/mutation string and optional variables. Supports customer management, subscription operations, entitlement checks, and usage reporting. tags: - Usage requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GraphQLRequest' examples: provisionCustomer: summary: Provision a Customer value: query: "mutation ProvisionCustomer($input: ProvisionCustomerInput!) {\n provisionCustomer(input: $input) {\n customer { id name email }\n subscription { id status plan { id name } }\n }\n}\n" variables: input: customerId: customer-123 name: Acme Corp email: admin@acme.com checkEntitlement: summary: Check Feature Entitlement value: query: "query GetCustomerEntitlement($customerId: String!, $featureId: String!) {\n customerEntitlement(customerId: $customerId, featureId: $featureId) {\n isGranted\n usageLimit\n currentUsage\n resetPeriod\n }\n}\n" variables: customerId: customer-123 featureId: feature-api-calls reportUsage: summary: Report Feature Usage value: query: "mutation ReportUsage($input: ReportUsageInput!) {\n reportUsage(input: $input) { id }\n}\n" variables: input: customerId: customer-123 featureId: feature-api-calls value: 100 responses: '200': description: GraphQL response (may contain data or errors). content: application/json: schema: $ref: '#/components/schemas/GraphQLResponse' '401': description: Invalid or missing X-API-KEY header. /api/v1/usage: post: tags: - Usage summary: Report usage measurements description: Reports usage measurements for metered features. The reported usage is used to track, limit, and bill customer consumption. operationId: UsageController_reportUsage parameters: - name: X-ACCOUNT-ID in: header required: false schema: type: string - name: X-ENVIRONMENT-ID in: header required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReportUsageRequestDto' examples: basic: summary: Report API call usage value: customerId: customer-123 featureId: feature-api-calls value: 100 responses: '201': description: The recorded usage measurement objects. content: application/json: schema: $ref: '#/components/schemas/UsageResponseDto' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/BadInputErrorResponseDto' '401': description: User is not authenticated. content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedErrorResponseDto' '403': description: User is not allowed to access this resource. content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorResponseDto' '409': description: Usage conflict error. content: application/json: schema: $ref: '#/components/schemas/ConflictErrorResponseDto' '429': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponseDto' /api/v1/events: post: tags: - Usage summary: Report usage events description: Reports raw usage events for event-based metering. Events are ingested asynchronously and aggregated into usage totals. operationId: EventsController_reportEvent parameters: - name: X-ACCOUNT-ID in: header required: false schema: type: string - name: X-ENVIRONMENT-ID in: header required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReportEventRequestDto' examples: basic: summary: Report a usage event value: customerId: customer-123 featureId: feature-api-calls eventName: api_request idempotencyKey: evt-unique-001 responses: '200': description: Confirmation that events were accepted for processing. content: application/json: schema: $ref: '#/components/schemas/EventResponseDto' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/BadInputErrorResponseDto' '401': description: User is not authenticated. content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedErrorResponseDto' '403': description: User is not allowed to access this resource. content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorResponseDto' '404': description: Event not found. content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponseDto' '429': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponseDto' components: schemas: EventResponseDto: type: object properties: data: type: object properties: accepted: type: boolean description: Whether the event was accepted for processing. description: Confirmation that events were accepted for processing. GraphQLResponse: type: object properties: data: type: object description: Response data from the GraphQL operation. additionalProperties: true errors: type: array description: Array of GraphQL errors if any occurred. items: $ref: '#/components/schemas/GraphQLError' ReportEventRequestDto: type: object properties: customerId: type: string description: The customer ID. featureId: type: string description: The feature ID. eventName: type: string description: The name of the event. idempotencyKey: type: string description: Idempotency key to prevent duplicate event ingestion. nullable: true timestamp: type: string format: date-time description: Timestamp for the event (defaults to now). nullable: true dimensions: type: object additionalProperties: type: string description: Additional event dimensions for aggregation. required: - customerId - featureId - eventName additionalProperties: false description: Reports raw usage events for event-based metering. NotFoundErrorResponseDto: type: object properties: message: type: string code: type: string nullable: true required: - message - code description: Resource not found error response. ReportUsageRequestDto: type: object properties: customerId: type: string description: The customer ID for which usage is being reported. featureId: type: string description: The feature ID for which usage is being reported. value: type: number description: The usage value to report. idempotencyKey: type: string description: Optional idempotency key to prevent duplicate usage reporting. nullable: true timestamp: type: string format: date-time description: Timestamp for the usage measurement (defaults to now). nullable: true updateBehavior: type: string enum: - DELTA - SET description: Whether the value is a delta to add or an absolute value to set. nullable: true required: - customerId - featureId - value additionalProperties: false description: Reports usage measurements for metered features. TooManyRequestsErrorResponseDto: type: object properties: message: type: string code: type: string enum: - RateLimitExceeded nullable: true required: - message - code description: Rate limit exceeded error response. GraphQLError: type: object properties: message: type: string description: Human-readable error message. locations: type: array items: type: object properties: line: type: integer column: type: integer path: type: array items: type: string extensions: type: object additionalProperties: true GraphQLRequest: type: object required: - query properties: query: type: string description: GraphQL query or mutation string. variables: type: object description: Variables for the GraphQL operation. additionalProperties: true operationName: type: string description: Named operation to execute when the document contains multiple. UsageResponseDto: type: object properties: data: type: object properties: id: type: string description: Usage measurement ID. customerId: type: string description: The customer ID. featureId: type: string description: The feature ID. value: type: number description: The reported usage value. timestamp: type: string format: date-time description: The timestamp of the usage measurement. description: Usage measurement response. UnauthenticatedErrorResponseDto: type: object properties: message: type: string code: type: string enum: - Unauthenticated nullable: true required: - message - code description: Authentication error response. ForbiddenErrorResponseDto: type: object properties: message: type: string code: type: string enum: - IdentityForbidden - AccessDeniedError - NoFeatureEntitlementError nullable: true required: - message - code description: Authorization error response. BadInputErrorResponseDto: type: object properties: message: type: string description: Human-readable error message. code: type: string description: Machine-readable error code. nullable: true required: - message - code description: Bad request error response. ConflictErrorResponseDto: type: object properties: message: type: string code: type: string enum: - DuplicatedEntityNotAllowed - EntitlementBelongsToFeatureGroupError nullable: true required: - message - code description: Conflict error response (e.g., duplicate resource). securitySchemes: ApiKey: type: apiKey in: header name: X-API-KEY description: Full access key from the Stigg dashboard (Integrations > API keys).