---
# @generated by sylphx-gen. Do not edit.
title: "Report usage on a store purchase"
description: "`money.store_purchases.report_usage` (POST /v1/{name}:reportUsage): Reports verified delivery and usage facts for an App Store purchase in answer to an observed `CONSUMPTION_REQUEST`."
type: reference
product: purchases
summary: "Reports verified delivery and usage facts for an App Store purchase in answer to an observed `CONSUMPTION_REQUEST`."
updated: 2026-09-28
nav: false
---

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](/docs/api/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`](/docs/api/errors/UNAUTHENTICATED) — No valid key or token was presented.
- [`PERMISSION_DENIED`](/docs/api/errors/PERMISSION_DENIED) — The key lacks the method's permission.
- [`RESOURCE_NOT_FOUND`](/docs/api/errors/RESOURCE_NOT_FOUND) — The named Resource does not exist or is not visible.
- [`INVALID_FIELD`](/docs/api/errors/INVALID_FIELD) — A field failed validation.
- [`INVALID_STATE`](/docs/api/errors/INVALID_STATE) — The Resource is in a state that forbids the call.
- [`UNAVAILABLE`](/docs/api/errors/UNAVAILABLE) — The Resource store, the owning service's backend, or the key verifier's snapshot is unavailable; retry after Retry-After.
- [`IDEMPOTENCY_KEY_REUSED`](/docs/api/errors/IDEMPOTENCY_KEY_REUSED) — An Idempotency-Key was reused with another body.
- [`IDEMPOTENCY_IN_PROGRESS`](/docs/api/errors/IDEMPOTENCY_IN_PROGRESS) — The first call with this Idempotency-Key is still running.

Every error arrives in the body [Errors](/docs/platform/errors) describes.

## Examples

**cURL**

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

**TypeScript**

```ts
const response = await sylphx.money.storePurchases.reportUsage({ custodyAttestation: '…', deliveryStatus: '…', name: 'orgs/acme/projects/shop/envs/production/store_purchases/store-purchase', sampleContentProvided: false })
```

**Rust**

```rust
let mut req = sylphx::money::ReportStorePurchaseUsageRequest::default();
req.custody_attestation = "…".to_string();
req.delivery_status = "…".to_string();
req.name = "orgs/acme/projects/shop/envs/production/store_purchases/store-purchase".to_string();
req.sample_content_provided = false;
let response = sx.money().store_purchases().report_usage(req).await?;
```

**CLI**

```bash
sylphx money store-purchases report-usage orgs/acme/projects/shop/envs/production/store_purchases/store-purchase
```

**MCP**

```json
{ "method_id": "money.store_purchases.report_usage", "args": {"custody_attestation":"…","delivery_status":"…","name":"orgs/acme/projects/shop/envs/production/store_purchases/store-purchase","sample_content_provided":false} }
```
