Report usage on a store purchase
Reports verified delivery and usage facts for an App Store purchase in answer to an observed `CONSUMPTION_REQUEST`.
Reports verified delivery and usage facts for an App Store purchase in answer to an observed CONSUMPTION_REQUEST. Strictly fails closed (0 outbound Apple calls) unless Money's append-only buyer-authenticated consent ledger holds an unwithdrawn granted decision for this purchase or app.
- Path
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/store_purchases/store-purchase:reportUsage - Scope
billing:write - Effect
write— a successful call changes state. - Collection store_purchases
Request
| Field | Type | What it is |
|---|---|---|
name | string | The store purchase to report usage for. Required. |
consumption_request | string | Optional consumption request resource name when targeting a specific captured CONSUMPTION_REQUEST. |
delivery_status | string | Apple deliveryStatus: DELIVERED, UNDELIVERED_QUALITY_ISSUE, UNDELIVERED_WRONG_ITEM, UNDELIVERED_SERVER_OUTAGE, or UNDELIVERED_OTHER. Required. |
sample_content_provided | bool | Apple sampleContentProvided: whether a free sample or trial was offered. Explicit presence is required so an omitted value is never defaulted. Required. |
consumption_percentage | int32 | Apple consumptionPercentage in milliunits (0..=100000, where 25000 is 25%). Required for non-subscription purchases (0 when undelivered) and omitted for auto-renewable subscriptions. |
refund_preference | string | Optional Apple refundPreference: DECLINE, GRANT_FULL, or GRANT_PRORATED. |
custody_attestation | string | Non-empty attestation confirming the caller holds exclusive reporting custody for this purchase (never a consent override). Required. |
Response
| Field | Type | What it is |
|---|---|---|
store_consumption_request | StoreConsumptionRequest | The updated store consumption request record. |
store_purchase | StorePurchase | The store purchase that was answered. |
StoreConsumptionRequest
| Field | Type | What it is |
|---|---|---|
name | string | orgs/{org}/projects/{project}/envs/{env}/store_consumption_requests/{store_consumption_request}. |
uid | string | scr_<cell><ulid>; never reused. Output only. |
meta | ResourceMeta | Resource metadata. |
store | string | Store name (app_store). Output only. |
bundle_id | string | App Store bundle identifier. Output only. |
environment | string | production or sandbox. Output only. |
transaction_id | string | App Store transaction identifier. Output only. |
original_transaction_id | string | App Store original transaction identifier. Output only. |
notification_id | string | Store notification UUID that opened this request. Output only. |
consumption_request_reason | string | Apple's consumptionRequestReason, when present. Output only. |
store_purchase | string | Linked StorePurchase resource name, when verified in Money. Output only. |
subject | Subject | Linked buyer subject, when known. Output only. |
status | string | Current state: pending, consent_missing, consent_withdrawn, in_flight, sent, failed_retryable, failed_terminal, or expired. Output only. |
observed_time | timestamp | When Money observed the notification. Output only. |
deadline_time | timestamp | 12-hour Apple response deadline. Output only. |
attempt_count | int32 | Number of outbound Apple Send Consumption attempts started. Output only. |
last_attempt_time | timestamp | Timestamp of the last outbound Apple Send Consumption attempt. Output only. |
sent_time | timestamp | Timestamp when Apple accepted the consumption report (HTTP 202). Output only. |
apple_http_status | int32 | HTTP status code returned by Apple's consumption endpoint (202 when sent). Output only. |
last_refusal_reason | string | Last fail-closed refusal reason, when blocked before calling Apple. Output only. |
consent_id | string | Consent ledger event id evaluated for the dispatch, when present. Output only. |
StorePurchase
| Field | Type | What it is |
|---|---|---|
name | string | orgs/{org}/projects/{project}/envs/{env}/store_purchases/{store_purchase}. |
uid | string | spu_<cell><ulid>; never reused. Output only. |
meta | ResourceMeta | Resource metadata. |
subject | Subject | Who it belongs to. Output only. |
store | string | app_store or google_play. Output only. |
product_id | string | The store product id. Output only. |
product | string | The catalog product it sells, when the catalog maps the store product. Output only. |
bundle_or_package | string | The bundle id or package name. Output only. |
transaction_id | string | The store's transaction id (App Store transaction id, Play order id). Output only. |
original_transaction_id | string | The first transaction of a subscription or restored purchase. Output only. |
quantity | int32 | Units bought. Output only. |
environment | string | production or sandbox. Output only. |
state | string | purchased, pending, or revoked. Output only. |
purchase_time | timestamp | When the store says it was bought. Output only. |
revoke_time | timestamp | When the store refunded or revoked it. Output only. |
price | string | The price the store charged, in minor units of currency, when the store reports it. Output only. |
currency_code | string | ISO 4217 currency of price. Output only. |
customer_subscription | string | The subscription it belongs to, for a subscription purchase. Output only. |
region_code | string | ISO 3166-1 alpha-2 country of the buyer's storefront, upper case; empty when the store did not report one. Output only. |
original_purchase_time | timestamp | When the store says the first purchase of this subscription or restored purchase was made; unset when it did not report one. Output only. |
claw_back | bool | Revoked after it was delivered, and its goods come back: its entitlements ended, and the app takes back the assets its grant credited, up to what the subject still holds. False while it stands, and for a refund the catalog's refund_claw_back lets the subject keep. Output only. |
ResourceMeta
| Field | Type | What it is |
|---|---|---|
generation | int64 | Increases by one on every change to spec. Output only. |
etag | string | Strong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as If-Match or etag to make Update and Delete conditional; a mismatch fails with ABORTED / 409 ETAG_MISMATCH. Output only. |
create_time | timestamp | When the Resource was created. Output only. |
update_time | timestamp | When the Resource last changed. Output only. |
delete_time | timestamp | Set while the Resource is being deleted. Output only. |
labels | map<string, string> | Caller-writable, indexed labels (AIP-122 label rules). |
annotations | map<string, string> | Caller-writable, unindexed annotations. |
display_name | string | Caller-writable human-readable name. |
creator | string | The principal that created the Resource. Output only. |
Subject
| Field | Type | What it is |
|---|---|---|
end_user | string | An end user's id (Sylphx Auth, or the app's own OIDC issuer). One of the kind group. |
customer_organization | string | A customer organization's id. One of the kind group. |
Errors
UNAUTHENTICATED— No valid key or token was presented.PERMISSION_DENIED— The key lacks the method's permission.RESOURCE_NOT_FOUND— The named Resource does not exist or is not visible.INVALID_FIELD— A field failed validation.INVALID_STATE— The Resource is in a state that forbids the call.UNAVAILABLE— The Resource store, the owning service's backend, or the key verifier's snapshot is unavailable; retry after Retry-After.IDEMPOTENCY_KEY_REUSED— An Idempotency-Key was reused with another body.IDEMPOTENCY_IN_PROGRESS— The first call with this Idempotency-Key is still running.
Every error arrives in the body Errors describes.
Examples
curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/store_purchases/store-purchase:reportUsage" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"custody_attestation":"…","delivery_status":"…","sample_content_provided":false}'