> ## 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. # Report usage measurements (v2) > Reports usage measurements for metered features. The reported usage is used to track, limit, and bill customer consumption. Credit balances are returned once per wallet in `credits`, not on each measurement. ## OpenAPI ````yaml /openapi/stigg-api.documented.yml post /api/v2/usage openapi: 3.0.0 info: title: Stigg API description: Stigg API documentation version: 8.137.0 contact: {} servers: - url: https://api.stigg.io description: Production security: - ApiKeyAuth: [] tags: - name: Customers description: Operations related to customers - name: Subscriptions description: Operations related to subscriptions - name: Coupons description: Operations related to coupons - name: Bulk Import description: Operations related to import of customers and subscriptions - name: Usage description: Operations related to usage & metering - name: Promotional Entitlements description: Operations related to promotional entitlements - name: Products description: Operations related to products - name: Features description: Operations related to features - name: Addons description: Operations related to addons - name: Plans description: Operations related to plans - name: Credit grants description: Operations related to credit grants - name: Credit ledger description: Operations related to credit ledger - name: Custom currencies description: Operations related to custom currencies paths: /api/v2/usage: post: tags: - Usage summary: Report usage measurements (v2) description: >- Reports usage measurements for metered features. The reported usage is used to track, limit, and bill customer consumption. Credit balances are returned once per wallet in `credits`, not on each measurement. operationId: UsageV2Controller_reportUsage parameters: - name: X-ACCOUNT-ID in: header description: >- Account ID — optional when authenticating with a user JWT (Bearer token); falls back to the user's first membership. Ignored for API-key auth. required: false schema: type: string - name: X-ENVIRONMENT-ID in: header description: >- Environment ID — required when authenticating with a user JWT (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is intrinsic to the key). required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReportUsageRequestDto' responses: '201': description: >- The recorded usage measurements and the balance of each credit wallet they drew from. content: application/json: schema: $ref: '#/components/schemas/UsageV2ResponseDto' '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' components: schemas: ReportUsageRequestDto: type: object properties: usages: type: array items: type: object properties: value: type: integer minimum: -9007199254740991 description: >- The value to report for usage. Must be a whole number — the REST API does not accept fractional (float) usage values; scale up (e.g. report cents instead of dollars, or milliseconds instead of seconds) if you need sub-unit precision. featureId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Feature id customerId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$ description: Customer id resourceId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: >- The customer resource this usage applies to. Optional — only required if the customer has multiple resources (for example, one subscription per workspace or site) and usage needs to be tracked separately per resource; omit it to report usage at the customer level. nullable: true createdAt: type: string format: date-time description: Timestamp of when the record was created updateBehavior: default: DELTA type: string enum: - DELTA - SET description: >- How the reported value is applied: DELTA (default) adds it to the feature's current usage; SET treats it as the new absolute usage total, and Stigg computes the delta internally. dimensions: description: Additional dimensions for the usage report type: object additionalProperties: oneOf: - type: string - type: number - type: boolean idempotencyKey: type: string maxLength: 255 minLength: 1 description: >- A key you provide to safely retry the same usage report without double-counting it. Reports with a previously-seen idempotency key are deduplicated for 7 days; after that window a retry is treated as new usage. required: - value - featureId - customerId additionalProperties: false title: UsageRecord description: Single usage measurement minItems: 1 maxItems: 100 description: A list of usage reports to be submitted in bulk required: - usages additionalProperties: false title: ReportUsageRequest description: Report usage for metered features. Batch up to 100 records. UsageV2ResponseDto: type: object properties: data: type: object properties: usages: type: array items: type: object properties: id: type: string maxLength: 255 description: Unique identifier for the entity value: type: integer minimum: -9007199254740991 description: The usage measurement record currentUsage: type: number description: The current measured usage value nullable: true credit: type: object properties: currencyId: type: string maxLength: 255 description: The credit currency identifier consumed: type: number description: >- The credits this single reportUsage call deducted, in credit units — scoped to this one measurement (0 for idempotency duplicates). Contrast `currentUsage`, which is the wallet-wide running total shared across all features on this currency. Use it to reconcile expected per-call deductions. required: - currencyId - consumed additionalProperties: false title: UsageMeasurementV2Credit description: >- The credits this measurement deducted. `null` when the measurement drew from no wallet listed in `credits`. The balance of the wallet it drew from is in the response `credits` list, matched by customer, resource and currency. nullable: true usagePeriodStart: type: string format: date-time description: >- The start date of the usage period in which this measurement resides (for entitlements with a reset period) nullable: true usagePeriodEnd: type: string format: date-time description: >- The end date of the usage period in which this measurement resides (for entitlements with a reset period) nullable: true nextResetDate: type: string format: date-time description: The date when the next usage reset will occur nullable: true timestamp: type: string format: date-time description: Timestamp featureId: type: string maxLength: 255 description: Feature id customerId: type: string maxLength: 255 description: Customer id resourceId: type: string maxLength: 255 description: >- The customer resource this usage applies to. Optional — only required if the customer has multiple resources (for example, one subscription per workspace or site) and usage needs to be tracked separately per resource; omit it to report usage at the customer level. nullable: true createdAt: type: string format: date-time description: Timestamp of when the record was created required: - id - value - timestamp - featureId - customerId - createdAt title: UsageMeasurementV2 description: Recorded usage with period info and the credits it deducted description: >- Usage measurements, in request order, with current values and period info credits: type: array items: type: object properties: currencyId: type: string maxLength: 255 description: The credit currency identifier currentUsage: type: number description: >- The wallet's total consumed credits for this currency (optimistic — includes not-yet-reconciled usage), shared across every feature that draws on the currency. This is the running balance, not this call's deduction — see `consumed` for that. usageLimit: type: number description: The total credits granted timestamp: type: string format: date-time description: >- The grant-version timestamp of this balance, used by the SDK for last-write-wins reconciliation usagePeriodEnd: type: string format: date-time description: >- End of the current credit grant period (when recurring credits reset), if applicable nullable: true customerId: type: string maxLength: 255 description: Customer id resourceId: type: string maxLength: 255 description: >- The wallet's resource; `null` for the customer-level wallet nullable: true required: - currencyId - currentUsage - usageLimit - timestamp - customerId - resourceId additionalProperties: false title: UsageCreditBalance description: >- Optimistic credit balance of one wallet (customer, resource and currency) after the request, listed once however many measurements drew from it description: >- The balance of each credit wallet the request drew from. Omitted when no reported feature consumes credits, or when credit balances aren't computed synchronously for the environment; each usage's `credit` is then `null`. entities: type: array items: type: object properties: customerId: type: string maxLength: 255 description: The customer whose usage counted towards the entitlement resourceId: type: string maxLength: 255 description: >- The customer resource the usage counted from; `null` for customer-level usage nullable: true entityId: type: string maxLength: 255 description: The governance entity the entitlement belongs to entitlementId: type: string maxLength: 255 description: The governance entitlement the usage counts towards featureId: type: string maxLength: 255 description: >- The feature the entitlement governs (exactly one of featureId and currencyId is set) currencyId: type: string maxLength: 255 description: >- The credit currency the entitlement governs (exactly one of featureId and currencyId is set) scopeEntityIds: type: array items: type: string maxLength: 255 description: >- The entities the entitlement is scoped to (empty when it is not scoped) description: >- The entities the entitlement is scoped to (empty when it is not scoped) currentUsage: type: number description: The absolute usage counted against the entitlement usageUpdatedAt: type: string format: date-time description: When the entitlement usage was last updated required: - customerId - resourceId - entityId - entitlementId - scopeEntityIds - currentUsage - usageUpdatedAt additionalProperties: false title: GovernanceEntityUsage description: The usage counted against one governance entitlement description: >- The current usage of each governance entitlement this request counted towards. Absent when governance is not enabled or the usage is unknown. Entitlements whose usage could not be read, and those of repeated idempotent requests, are left out required: - usages title: UsageV2Data description: Reported usage measurements and the credit balances they drew from required: - data title: UsageV2Response description: >- Response containing reported usage measurements with current usage values, period information and reset dates, plus the balance of each credit wallet they drew from. BadInputErrorResponseDto: type: object properties: message: type: string code: type: string enum: - BadUserInput - EnvironmentMismatch - BillingContractOperationRejected - DuplicateIntegrationNotAllowed - EntityIsArchivedError - IntegrityViolation - FreePlanCantHaveCompatiblePackageGroupError - SubscriptionMustHaveSinglePlanError - AddonIsCompatibleWithPlan - AddonIsCompatibleWithGroup - DuplicateAddonProvisionedError - ScheduledMigrationAlreadyExistsError - SubscriptionAlreadyOnLatestPlan - EntityIdDifferentFromRefIdError - UnsupportedFeatureType - UnsupportedVendorIdentifier - UnsupportedSubscriptionScheduleType - InvalidEntitlementResetPeriod - IncompatibleSubscriptionAddon - UnPublishedPackage - MeteringNotAvailableForFeatureType - AuthCustomerMismatch - AuthCustomerReadonly - FetchAllCountriesPricesNotAllowed - MemberInvitationError - PlansCircularDependencyError - NoFeatureEntitlementInSubscription - CheckoutIsNotSupported - UnsupportedParameter - PricingModelNotSupportedByBillingIntegration - BillingIntegrationMissing - BillingIntegrationAlreadyExistsError - InvalidMemberDelete - PackageAlreadyPublished - DraftPlanCantBeArchived - DraftAddonCantBeArchived - PlanWithChildCantBeDeleted - PlanCannotBePublishWhenBasePlanIsDraft - PlanCannotBePublishWhenCompatibleAddonIsDraft - PlanIsUsedAsDefaultStartPlan - PlanIsUsedAsDowngradePlan - InvalidAddressError - InvalidQuantity - BillingPeriodMissingError - DowngradeBillingPeriodNotSupportedError - CustomerAlreadyUsesCouponError - CustomerAlreadyHaveCustomerCoupon - SubscriptionAlreadyCanceledOrExpired - TrialMustBeCancelledImmediately - SubscriptionDoesNotHaveBillingPeriod - InvalidCancellationDate - FailedToImportCustomer - FailedToImportSubscriptions - PackagePricingTypeNotSet - InvalidSubscriptionStatus - InvalidArgumentError - EditAllowedOnDraftPackageOnlyError - ResyncAlreadyInProgress - ArchivedCouponCantBeApplied - ImportAlreadyInProgress - AddonHasToHavePriceError - SelectedBillingModelDoesntMatchImportedItemError - CannotArchiveProductError - CannotUnarchiveProductError - CannotDeleteCustomerError - CannotRemovePaymentMethodFromCustomerError - CannotDeleteFeatureError - CannotArchiveFeatureError - InvalidUpdatePriceUnitAmountError - ExperimentAlreadyRunning - ExperimentStatusError - OperationNotAllowedDuringInProgressExperiment - EntitlementsMustBelongToSamePackage - CanNotUpdateEntitlementsFeatureGroup - MeterMustBeAssociatedToMeteredFeature - CannotUpdateMeterOfFeatureInUse - CannotEditPackageInNonDraftMode - CannotAddOverrideEntitlementToPlan - MissingEntityIdError - NoProductsAvailable - PromotionCodeNotForCustomer - PromotionCodeNotActive - PromotionCodeMaxRedemptionsReached - PromotionCodeMinimumAmountNotReached - PromotionCodeCustomerNotFirstPurchase - AddonWithDraftCannotBeDeletedError - CannotReportUsageForEntitlementWithMeterError - RecalculateEntitlementsError - ImportSubscriptionsBulkError - InvalidMetadataError - CannotUpsertToPackageThatHasDraft - IntegrationValidationError - AwsMarketplaceIntegrationValidationError - AwsMarketplaceIntegrationError - DataExportIntegrationError - HubspotIntegrationError - DuplicateProductValidationError - AmountTooLarge - CustomerHasNoEmailAddress - MergeEnvironmentValidationError - EntitlementLimitExceededError - EntitlementUsageOutOfRangeError - UsageMeasurementDiffOutOfRangeError - AddonQuantityExceedsLimitError - AddonDependencyMissingError - PackageGroupMinItemsError - CannotUpdateUnitTransformationError - SingleSubscriptionCantBeAutoCancellationTargetError - MultiSubscriptionCantBeAutoCancellationSourceError - ChangingPayingCustomerIsNotSupportedError - RequiredSsoAuthenticationError - InvalidDoggoSignatureError - InvalidReceivedSignatureError - CannotDeleteDefaultIntegration - CannotChangeBillingIntegration - FailedToResolveBillingIntegration - WorkflowTriggerNotFound - DeprecatedEstimateSubscriptionError - FeatureConfigurationExceededLimitError - FeatureNotBelongToFeatureGroupError - FeatureGroupMissingFeaturesError - VersionExceedsMaxValueError - CannotUpdateExpireAtForExpiredCreditGrantError - ExpireAtMustBeLaterThanEffectiveAtError - OfferAlreadyExists - DraftAlreadyExists - CreditGrantAlreadyVoided - CreditGrantCannotBeVoided - InvalidTaxId - ObjectAlreadyBeingUsedByAnotherRequestError - TooManySubscriptionsPerCustomer - TooManyCustomCurrencies - StripeError - SchedulingAtEndOfBillingPeriod - ApiKeyExpired - ApiKeyHasExpiry - OveragePriceNotSupportedOnAddon - OveragePriceRequiresUsageLimit - InvalidCreditOverageBillingModel - CreditOveragePriceCurrencyNotFound - InvoicePreviewNotAvailableForDraftContract nullable: true reason: type: string maxLength: 255 description: >- The billing side's machine-readable code for a billing-contract refusal. Present only when the code is BillingContractOperationRejected and the refusal carried one. required: - message - code UnauthenticatedErrorResponseDto: type: object properties: message: type: string code: type: string enum: - Unauthenticated nullable: true required: - message - code ForbiddenErrorResponseDto: type: object properties: message: type: string code: type: string enum: - IdentityForbidden - AccessDeniedError - NoFeatureEntitlementError - GovernanceNotEnabled nullable: true required: - message - code ConflictErrorResponseDto: type: object properties: message: type: string code: type: string enum: - DuplicatedEntityNotAllowed - EntitlementBelongsToFeatureGroupError nullable: true required: - message - code TooManyRequestsErrorResponseDto: type: object properties: message: type: string code: type: string enum: - RateLimitExceeded nullable: true required: - message - code securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: Server API Key ```` ## Related topics - [Report usage measurements](/api-reference/usage/report-usage-measurements.md) - [API Client (JS)](/api-and-sdks/changelog/backend-graphql/api-client-js.md) - [.NET SDK](/api-and-sdks/changelog/backend-graphql/dotnet.md) - [Go SDK](/api-and-sdks/changelog/backend-graphql/go.md) - [Java SDK](/api-and-sdks/changelog/backend-graphql/java.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.