Synchronize a purchase

Verify a store purchase and attach its Feature access to a customer.

POSThttps://i.nuxie.ai/purchase

Attach a verified App Store or Google Play purchase to a customer and return the resulting Feature access. type selects the store; distinct_id identifies the customer for either store.

The iOS SDK’s default StoreKit integration sends verified transactions, retries synchronization, and finishes transactions for you. For another billing provider, see purchase ownership.

Request body

apiKeybodystringrequired

Publishable key for the app platform. A pk_test_ key selects test data; a pk_live_ key selects live data. Copy it from Connect your app.

typebodystringrequired

appstore or playstore.

distinct_idbodystringrequired

The identified or anonymous customer ID your app supplies to the SDK, rather than Nuxie’s internal customer record ID. See Customer identifiers.

transaction_jwtbodystring

Required for appstore: the signed transaction returned by StoreKit 2.

purchase_tokenbodystring

Required for playstore: the token returned by Google Play Billing.

product_idbodystring

Google Play Product identifier, when relevant.

base_plan_idbodystring

Google Play subscription base plan, when relevant.

purchase_option_idbodystring

Google Play one-time purchase option, when relevant.

offer_idbodystring

Selected Google Play store offer, when relevant.

product_typebodystring

Google Play subscription or one_time.

Use the publishable key for the matching iOS or Android platform. The configured Google Play connection supplies the package context. Nuxie verifies the purchase with the store before attaching access to the customer.

Response

successbooleanrequired

true when the purchase is attached.

customer_idstringrequired

Nuxie’s resolved customer record ID.

featuresobject[]required

Resulting Feature access.

idempotent_replaybooleanrequired

Whether this purchase was already processed.

transaction_idstring

App Store transaction identifier, returned for appstore.

purchase_tokenstring

Google Play purchase token, returned for playstore.

order_idstring

Google Play order identifier, returned for playstore.

catalog_productobject

Google Play mapping to the matched Product, base plan, purchase option, offer, and store product type.

Repeat the same evidence when retrying. Nuxie recognizes the existing transaction or token instead of granting it twice.

Purchase errors

Error codes use the prefix app_store_purchase_ or google_play_purchase_:

Suffix	Status	Action
`invalid`	`400`	Check the evidence, Product identifiers, App, and environment
`owner_unverified`	`400`	Check the customer identity used for checkout and synchronization
`unsupported`	`400`	Inspect `detail` for why the purchase cannot be attached
`conflict`	`409`	Resolve the ownership or conflicting replay before resubmitting
`reconciliation_retryable`	`503`	Retry with the same evidence after a delay
`unavailable`	`503`, or `429` for Google Play	Retry with backoff

curl https://i.nuxie.ai/purchase \
  --header 'Content-Type: application/json' \
  --data '{
  "apiKey": "pk_test_example",
  "type": "appstore",
  "distinct_id": "user-456",
  "transaction_jwt": "eyJhbGciOi..."
}'

curl https://i.nuxie.ai/purchase \
  --header 'Content-Type: application/json' \
  --data '{
  "apiKey": "pk_test_example",
  "type": "playstore",
  "purchase_token": "token-from-google-play",
  "product_id": "premium",
  "base_plan_id": "monthly",
  "distinct_id": "user-456"
}'

{
  "success": true,
  "customer_id": "customer-record-id",
  "features": [],
  "transaction_id": "200000000000001",
  "idempotent_replay": false
}

{
  "success": true,
  "customer_id": "customer-record-id",
  "features": [],
  "purchase_token": "token-from-google-play",
  "order_id": "google-play-order-id",
  "idempotent_replay": false,
  "catalog_product": {
    "id": "product-id",
    "store_product_id": "premium",
    "base_plan_id": "monthly",
    "purchase_option_id": null,
    "offer_id": null,
    "store_product_type": "subscription"
  }
}