Feature usage

Agreed contract, implementation pending. Schemas and payload examples are attached to the two endpoints.

Endpoints and scope

Both accept optional query parameter placeId (string, ^[a-f0-9]{24}$). Omit it for merchant features; require it for place features. Empty or repeated values are invalid. Features validates the configured target, place ownership and caller permissions. Wrong scope returns 400. Admin uses the feature's configured target and its authenticated merchant/place context.

Merchant example, shared across all places:

Place example, independent balance and reset date:

The /features service prefix is included. GET has no body. POST uses JSON with action: "consume" or action: "refund"; scope identifiers are not repeated in its body. Authentication is inherited from Features API. POST requires a trusted internalApi backend caller with settings access.

Accounting rules

AI stock-up uses 300 merchant-shared requests. Consume one per upload submission, regardless of pages/files. Limits and resets are changed only in Configurations.

Consume before work. Only consumed starts new work. Successful work needs no follow-up accounting request.

Refund a known failure using the original request ID and scope. Restore the original quantity once; an old-period refund never increases the new period balance.

Retry uncertain responses with the same ID and payload. Matching consumes return duplicate or refunded; changed quantity/fingerprint returns request_conflict. After a confirmed refund, a fresh attempt uses a new ID. Interrupted work may remain consumed.

Periods advance on demand from original enablement, not first use. Re-enablement preserves the anchor. Treat periodId as opaque; use expectedPeriodId when confirming against a displayed period.

Why fingerprint is required

requestId identifies the attempt; fingerprint verifies that its input has not changed. Features compares the SHA-256 input hash when the same request ID is reused within the same scope. Matching input and quantity return the existing receipt; changed input or quantity returns request_conflict.

For example, retrying invoice A with its original request ID is safe. Sending invoice B with that same ID must be rejected; otherwise it could be mistaken for a retry and Admin could replay invoice A’s saved result. Features stores the hash, not the original document. The scope lock handles concurrency separately. Refunds need only the original request ID and scope, not a fingerprint.

MongoDB models

Shared collections in Features. ObjectId and Date are BSON types. Merchant/place IDs keep the existing string representation.

Indexes

Keep MongoDB's default unique _id indexes. Store placeId: null explicitly for merchant quotas; the scope index is neither sparse nor partial. A quota keeps its ObjectId through resets. Receipts reference that ObjectId and remain unique across periods. No receipt TTL is defined.

Use the existing scope lock and a MongoDB transaction for atomic balance/receipt changes. Indexes prevent duplicate identities; they do not replace atomic balance updates. Public receipts omit storage _id and quotaId. Neither is a URL parameter.

Design and policy details in Confluence

{feature}/usage

Feature usage#

Endpoints and scope#

Accounting rules#

Why fingerprint is required#