> ## 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 > Reports usage measurements for metered features. The reported usage is used to track, limit, and bill customer consumption. ## OpenAPI ````yaml POST /api/v1/usage openapi: 3.0.0 info: title: Stigg API description: Stigg API documentation version: 7.93.1 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/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 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 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' x-codeSamples: - lang: JavaScript source: |- import Stigg from '@stigg/typescript'; const client = new Stigg({ apiKey: process.env['STIGG_API_KEY'], // This is the default and can be omitted }); const response = await client.v1.usage.report({ usages: [ { customerId: 'customerId', featureId: 'featureId', value: -9007199254740991, }, ], }); console.log(response.data); - lang: Python source: |- import os from stigg import Stigg client = Stigg( api_key=os.environ.get("STIGG_API_KEY"), # This is the default and can be omitted ) response = client.v1.usage.report( usages=[{ "customer_id": "customerId", "feature_id": "featureId", "value": -9007199254740991, }], ) print(response.data) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/stiggio/stigg-go\"\n\t\"github.com/stiggio/stigg-go/option\"\n)\n\nfunc main() {\n\tclient := stigg.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.V1.Usage.Report(context.TODO(), stigg.V1UsageReportParams{\n\t\tUsages: []stigg.V1UsageReportParamsUsage{{\n\t\t\tCustomerID: \"customerId\",\n\t\t\tFeatureID: \"featureId\",\n\t\t\tValue: -9007199254740991,\n\t\t}},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n" - lang: Java source: |- package io.stigg.example; import io.stigg.client.StiggClient; import io.stigg.client.okhttp.StiggOkHttpClient; import io.stigg.models.v1.usage.UsageReportParams; import io.stigg.models.v1.usage.UsageReportResponse; public final class Main { private Main() {} public static void main(String[] args) { StiggClient client = StiggOkHttpClient.fromEnv(); UsageReportParams params = UsageReportParams.builder() .addUsage(UsageReportParams.Usage.builder() .customerId("customerId") .featureId("featureId") .value(-9007199254740991L) .build()) .build(); UsageReportResponse response = client.v1().usage().report(params); } } - lang: Ruby source: |- require "stigg" stigg = Stigg::Client.new(api_key: "My API Key") response = stigg.v1.usage.report( usages: [{customerId: "customerId", featureId: "featureId", value: -9007199254740991}] ) puts(response) - lang: C# source: |- using System; using System.Collections.Generic; using Stigg.Client; using Stigg.Client.Models.V1.Usage; StiggClient client = new(); UsageReportParams parameters = new() { Usages = [ new() { CustomerID = "customerId", FeatureID = "featureId", Value = -9007199254740991, CreatedAt = DateTimeOffset.Parse("2019-12-27T18:11:19.117Z"), Dimensions = new Dictionary() { { "foo", "string" } }, IdempotencyKey = "x", ResourceID = "resourceId", UpdateBehavior = UpdateBehavior.Delta, }, ], }; var response = await client.V1.Usage.Report(parameters); Console.WriteLine(response); - lang: CLI source: |- stigg v1:usage report \ --api-key 'My API Key' \ --usage '{customerId: customerId, featureId: featureId, value: -9007199254740991}' 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 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: Resource id 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: The method by which the usage value should be updated 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: Idempotency key 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. UsageResponseDto: type: object properties: data: 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 currentUsage: type: number description: >- The credits consumed (optimistic — includes not-yet-reconciled usage) 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 required: - currencyId - currentUsage - usageLimit - timestamp additionalProperties: false title: UsageMeasurementCredit description: Optimistic credit balance for a credit-backed feature 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: Resource id nullable: true createdAt: type: string format: date-time description: Timestamp of when the record was created required: - id - value - timestamp - featureId - customerId - createdAt title: UsageMeasurement description: Recorded usage with period info description: Array of usage measurements with current values and period info required: - data title: UsageResponse description: >- Response containing reported usage measurements with current usage values, period information, and reset dates for each measurement. BadInputErrorResponseDto: type: object properties: message: type: string code: type: string enum: - BadUserInput - 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 - 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 nullable: true 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 - InvoicePreviewNotAvailableForDraftContract 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 ````