Skip to content
Console
On this page

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

FieldTypeWhat it is
namestringThe store purchase to report usage for. Required.
consumption_requeststringOptional consumption request resource name when targeting a specific captured CONSUMPTION_REQUEST.
delivery_statusstringApple deliveryStatus: DELIVERED, UNDELIVERED_QUALITY_ISSUE, UNDELIVERED_WRONG_ITEM, UNDELIVERED_SERVER_OUTAGE, or UNDELIVERED_OTHER. Required.
sample_content_providedboolApple sampleContentProvided: whether a free sample or trial was offered. Explicit presence is required so an omitted value is never defaulted. Required.
consumption_percentageint32Apple consumptionPercentage in milliunits (0..=100000, where 25000 is 25%). Required for non-subscription purchases (0 when undelivered) and omitted for auto-renewable subscriptions.
refund_preferencestringOptional Apple refundPreference: DECLINE, GRANT_FULL, or GRANT_PRORATED.
custody_attestationstringNon-empty attestation confirming the caller holds exclusive reporting custody for this purchase (never a consent override). Required.

Response

FieldTypeWhat it is
store_consumption_requestStoreConsumptionRequestThe updated store consumption request record.
store_purchaseStorePurchaseThe store purchase that was answered.

StoreConsumptionRequest

FieldTypeWhat it is
namestringorgs/{org}/projects/{project}/envs/{env}/store_consumption_requests/{store_consumption_request}.
uidstringscr_<cell><ulid>; never reused. Output only.
metaResourceMetaResource metadata.
storestringStore name (app_store). Output only.
bundle_idstringApp Store bundle identifier. Output only.
environmentstringproduction or sandbox. Output only.
transaction_idstringApp Store transaction identifier. Output only.
original_transaction_idstringApp Store original transaction identifier. Output only.
notification_idstringStore notification UUID that opened this request. Output only.
consumption_request_reasonstringApple's consumptionRequestReason, when present. Output only.
store_purchasestringLinked StorePurchase resource name, when verified in Money. Output only.
subjectSubjectLinked buyer subject, when known. Output only.
statusstringCurrent state: pending, consent_missing, consent_withdrawn, in_flight, sent, failed_retryable, failed_terminal, or expired. Output only.
observed_timetimestampWhen Money observed the notification. Output only.
deadline_timetimestamp12-hour Apple response deadline. Output only.
attempt_countint32Number of outbound Apple Send Consumption attempts started. Output only.
last_attempt_timetimestampTimestamp of the last outbound Apple Send Consumption attempt. Output only.
sent_timetimestampTimestamp when Apple accepted the consumption report (HTTP 202). Output only.
apple_http_statusint32HTTP status code returned by Apple's consumption endpoint (202 when sent). Output only.
last_refusal_reasonstringLast fail-closed refusal reason, when blocked before calling Apple. Output only.
consent_idstringConsent ledger event id evaluated for the dispatch, when present. Output only.

StorePurchase

FieldTypeWhat it is
namestringorgs/{org}/projects/{project}/envs/{env}/store_purchases/{store_purchase}.
uidstringspu_<cell><ulid>; never reused. Output only.
metaResourceMetaResource metadata.
subjectSubjectWho it belongs to. Output only.
storestringapp_store or google_play. Output only.
product_idstringThe store product id. Output only.
productstringThe catalog product it sells, when the catalog maps the store product. Output only.
bundle_or_packagestringThe bundle id or package name. Output only.
transaction_idstringThe store's transaction id (App Store transaction id, Play order id). Output only.
original_transaction_idstringThe first transaction of a subscription or restored purchase. Output only.
quantityint32Units bought. Output only.
environmentstringproduction or sandbox. Output only.
statestringpurchased, pending, or revoked. Output only.
purchase_timetimestampWhen the store says it was bought. Output only.
revoke_timetimestampWhen the store refunded or revoked it. Output only.
pricestringThe price the store charged, in minor units of currency, when the store reports it. Output only.
currency_codestringISO 4217 currency of price. Output only.
customer_subscriptionstringThe subscription it belongs to, for a subscription purchase. Output only.
region_codestringISO 3166-1 alpha-2 country of the buyer's storefront, upper case; empty when the store did not report one. Output only.
original_purchase_timetimestampWhen the store says the first purchase of this subscription or restored purchase was made; unset when it did not report one. Output only.
claw_backboolRevoked 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

FieldTypeWhat it is
generationint64Increases by one on every change to spec. Output only.
etagstringStrong 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_timetimestampWhen the Resource was created. Output only.
update_timetimestampWhen the Resource last changed. Output only.
delete_timetimestampSet while the Resource is being deleted. Output only.
labelsmap<string, string>Caller-writable, indexed labels (AIP-122 label rules).
annotationsmap<string, string>Caller-writable, unindexed annotations.
display_namestringCaller-writable human-readable name.
creatorstringThe principal that created the Resource. Output only.

Subject

FieldTypeWhat it is
end_userstringAn end user's id (Sylphx Auth, or the app's own OIDC issuer). One of the kind group.
customer_organizationstringA customer organization's id. One of the kind group.

Errors

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}'