Purchase Status Updates

This event is triggered whenever a change happens to a purchase throughout its lifecycle.

The purchase.updated data structure provides you all the relevant information known about the purchase at the time the event is sent. It is delivered to you via your webhook.

Delivery Timing

Events are sent in a near real-time. You will receive a purchase.updated event on a 2 minute delay after the update occurred. If an update occurs to a purchase within the 2 minutes, the timer is reset until there are no changes detected from the Nami SDK or the Platform Provider before sending on to you.

This mechanism ensures the data is provided in a timely fashion, while also cutting down on the number of events sent for one purchase.

Multiple updates for a purchase are possible. The collapse_key is the primary key for a specific purchase. Store the most recent version of each purchase update for a given collapse_key to have a complete view of all purchases Nami knows about.

Event Data Structure

Top-Level Elements

Field Name	Type	Definition
billing_cycles	Integer or Null	The number of total billing cycles that have occurred for this purchase. The original purchase counts as first cycle.
canceled_at	Timestamp or Null	When the subscription was cancelled.
current_term_length	String (ISO-8601 Time Interval Format) or Null	The current term length of the subscriptions. Requires Platform Product Sync to be enabled. Contact support for details.
devices_with_access	List of of DevicesWithAccess	A list of devices that have access to the purchase. Ordered by device claim date, oldest to newest.
entitlements	List of PurchaseEntitlements	A list of entitlements the purchase grants.
expires_at	Timestamp or Null	The current time when the subscription will expire.
is_active	Boolean or Null	Whether the purchase is currently active.
is_auto_renewable	Boolean or Null	Whether the purchase is auto-renewing.
is_free_trial_conversion	Boolean or Null	Whether the purchase converted from a free trial. Note: If Nami did not observe the original purchase, we do not know if the purchase was a free trial. In this case, this field will be null.
is_in_trial_period	Boolean or Null	Whether the purchase is currently in a trial period. Note: We only know if the purchase is in a free trial, if we observed the original purchase.
is_production	Boolean	Whether the purchase occurred in production or not.
is_in_intro_offer_period	Boolean or Null	Whether the purchase is in an introductory offer period.
last_seen_device_id	UUID or Null	The identifier for the last seen device with access to this purchase.
last_seen_external_id	String or Null	The external identifier associated with this purchase.
not_before	Timestamp or Null	When this purchase became active.
original_purchase_guid	String or Null	A reference to a previous purchase in the case of a plan change.
payment_issues_began_at	Timestamp or Null	When payment issues started.
platform_type	String	The platform type (e.g. apple, google)
price_in_usd	Decimal or Null	The estimated pricing in USD using currency exchange rates from the day of the purchase.
product_ref_id	String	The identifier for this purchase as configured with the app store platform.
purchase_country	String (2 Character Enum) or Null	The country code for the purchase from the app store platform.
purchase_currency	String (3 Character Enum) or Null	The currency code for the purchase from the app store platform.
purchase_guid	String	The identifier provided for the purchase from the app store platform.
purchase_price	Decimal or Null	The local price for the purchase from the app store platform.
revoked_at	Timestamp or Null	When the purchase was revoked.
transaction_id	String	The transaction identifier for the purchase from the app store platform.

DevicesWithAccess Elements

A list of devices that have access to the purchase.

Field Name	Type	Definition
claim_type	String	How a device gained access to purchase (original_purchaser, family_sharing, cross_platform_shared, etc).
first_launch	Timestamp	The time the device first registered with Nami
id	UUID	The device install's unique identifier.
last_active	Timestamp	The end time of the last known app session.
platform_type	String	What app platform of the device (apple, google)

PurchaseEntitlement Elements

A list of entitlements the purchase grants.

Field Name	Type	Description
description	String	Entitlement description in Nami Control Center.
entitlement_ref_id	String	Entitlement reference in Nami Control Center.
id	UUID	Nami internal identifier for an entitlement.
name	String	Entitlement display name in Nami Control Center.
type	String	binary_auth is an entitlement to gate features with an ‘on/off’ switch.

EventAttributes Elements

Metadata which can be useful when processing this event.

Field Name	Type	Definition
app_id	UUID or Null	Nami App ID (if applicable) for the event.
collapse_key	String	Collapse Key is the primary key for versioned events.
event_id	UUID	Unique ID for a specific event.
event_time	Timestamp	UTC Timestamp of Event in ISO-8601 format.
event_type	String	The type of event.
org_id	UUID or Null	Your Nami Org ID.
platform_id	UUID or Null	App Platform ID (if applicable) for the event.
subscription_id	UUID or Null	Subscription that caused the event delivery.
version	String	Version of event format

Example Payload

{
    "attributes": {
      "app_id": "486c1c9f-37b1-4873-9ff6-e78e563d184a",
      "collapse_key": "6b275a67-0bbb-4f3a-99b9-6600bf711993",
      "event_id": "b4ad74e4-8986-461b-aa08-473a19c608b2",
      "event_time": "2022-09-20T20:12:35.818538Z",
      "event_type": "purchase.updated",
      "org_id": "a8d39aa3-e393-46ee-8cb4-e8b8c0bd50e7",
      "platform_id": "aaf69dba-ef67-40f5-82ec-c7623a2848a6",
      "subscription_id": "7e0977f8-27c9-49c5-8356-e82cbf34b161",
      "version": "2.0"
    },
    "data": {
      "billing_cycles": 5,
      "canceled_at": null,
      "current_term_length": null,
      "devices_with_access": [
        {
          "claim_type": "original_purchaser",
          "first_launch": "2022-09-19T23:15:25.201213Z",
          "id": "eadea2bf-79b3-444c-b3a4-9e0127abc840",
          "last_active": "2022-09-20T19:37:38.713391Z",
          "platform_type": "google"
        }
      ],
      "entitlements": [
        {
          "description": null,
          "entitlement_ref_id": "premium",
          "id": "71a267cd-de70-4ba9-b743-24ef2b4be3ae",
          "name": "Premium",
          "type": "binary_auth"
        },
        {
          "description": null,
          "entitlement_ref_id": "gold",
          "id": "c1ec3e32-25b5-4eb9-b1e1-6fd429581b4a",
          "name": "Gold",
          "type": "binary_auth"
        }
      ],
      "expires_at": "2022-09-20T20:19:31.302000Z",
      "is_active": true,
      "is_auto_renewable": true,
      "is_free_trial_conversion": false,
      "is_in_intro_offer_period": false,
      "is_in_trial_period": false,
      "is_production": false,
      "last_seen_device_id": "eadea2bf-79b3-444c-b3a4-9e0127abc840",
      "last_seen_external_id": null,
      "not_before": "2022-09-20T19:37:30.193000Z",
      "original_purchase_guid": null,
      "payment_issues_began_at": null,
      "platform_type": "google",
      "price_in_usd": "4.99",
      "product_ref_id": "your_product_name",
      "purchase_country": "US",
      "purchase_currency": "USD",
      "purchase_guid": "google_play_token_or_apple_original_transacation_id",
      "purchase_price": "4.9900",
      "revoked_at": null,
      "transaction_id": "GPA.1234-5678-9012-12345..3"
    }
  }