Nami Public Documentation
Sign In
Nami Documentation
Nami Documentation
  • Get Started
    • Overview
      • Key Concepts
      • Data Collection
      • Built for Privacy
    • Evaluating Nami
    • SDKs
      • Apple Native SDK
      • Android Native SDK
      • Amazon Native SDK
      • Roku Native SDK
      • React Native Cross-Platform SDK
      • Flutter Cross-Platform SDK
      • Unity Cross-Platform SDK
      • Release Notes
        • Find Nami SDK Version
    • Quickstart Guide
  • Subscription Management
    • Overview
    • Products
      • Archive Products
      • Sync Products
    • Entitlements
    • Customer Screen
    • Accounts and Login/Logout
    • Advanced Use Cases
      • Upgrades and Downgrades
      • Supported Purchase Change States by Platform
      • Restoring Purchases
      • Working with Consumable IAPs
  • No Code Paywalls
    • Overview
    • Paywall Creator
      • Using the Creator
      • Paywall Layout
      • Components
        • Editing, Deleting, Reordering
        • Hiding Components
        • Video
        • Collapse
      • Editable Properties
        • Focused Styling
        • Safe Area
      • Conditions
        • Notched Devices
        • Product Entitlements
      • Adding Products
      • Repeating Product Group
      • Product Fields
      • Capabilities
        • Featured Styling
        • Selected Styling
        • Custom Brand Fonts
        • Carousel
        • Trial Eligibility
        • Deeplink Button
        • Introductory Offer Eligibility
        • Login Check
        • Product Groups
        • Conditional Product Groups
        • Offer Eligibility and Purchasing
        • Screenreader Text
        • Personalization Tokens
        • Custom Variables
        • Multipage
        • Custom Data Source
        • Advanced Video Features
        • Product Error States
      • ❓FAQs
        • Designing Paywalls in Figma
        • Guide to Building a Paywall from Scratch
      • 🎁Releases
        • Roadmap
    • Paywall Templates
      • Pacific
      • Pacific Premium
      • Trident
      • Starfish
      • Mantis
      • Venice
      • Venice Premium
      • Honest
      • Catalina
      • Oyster
      • Puffin
      • Marina
      • Beluga
      • Driftwood
      • Lagoon
      • Pisces
      • Aquarius
      • Conch
      • Lionfish
      • Moray
      • Tetra
      • Lighthouse
      • Puffin Tablet
    • Managing Paywalls
      • Archiving a Paywall
      • Duplicate a Paywall
    • Paywall Smart Text
    • Pricing Eligibility States
    • Pricing Eligibility by Platform
    • Nami Paywalls in Different Languages
    • Legacy Paywalls
  • Campaigns
    • Placements
      • Create a Placement
      • Deeplink Placements
      • Archiving a Placement
      • Managing Lots of Placements
      • Export Placements
    • Campaigns
      • Campaign Filters
        • Campaign Use Cases
      • Archiving a Campaign
      • Scheduling a Campaign
      • Campaign Conversion Events
      • Managing Lots of Campaigns
      • Campaign Troubleshooting
    • A/B and Multivariate Testing
      • Selecting an A/B test winner
      • A/B Test Allocation
  • Integrations
    • All Integrations
    • Billing Platforms
      • Apple Integration
        • App Store Setup
          • Privacy Details
        • Platform Integration
        • App Store Server Notifications
        • Store Credentials
          • App Store Connect Shared Secret
          • Apple App Store Connect API
          • Apple In App Purchase
        • Add a Product
        • Platform Sync
        • SDK Integration
        • Troubleshooting
        • Testing and Development
          • Apple Testing Environments
          • Setting up Device Sandbox Test Environment
          • Setting up StoreKit config in Xcode
      • Google Integration
        • Google Play Store Setup
        • Platform Integration
        • Service Account
        • Real-time Developer Notifications
        • Add a Product
        • Platform Sync
        • SDK Setup
        • Troubleshooting
          • Supporting Android minSdkVersion 25 or lower
          • Requested product is not available for purchase
          • Unsupported Version of Play Billing
      • Amazon Appstore Integration
        • Create Amazon Android App
        • Platform Integration
        • Shared Key
        • Real-time Event Notifications
        • Add a Product
        • SDK Integration
        • Testing
      • Roku Integration
        • Platform Integration
        • API Key
        • Transaction Notifications
        • Add a Product
        • SDK Integration
      • Web Integration
    • Analytics Tools
      • Adobe Analytics
      • Amplitude
      • Google Analytics
      • mParticle
      • 3rd-Party Analytics
    • Subscription Management
      • Nami Subscription Management
      • Bring your Own Payment Code
    • CDP Integrations
      • Adobe CDP Integration
      • Amplitude CDP Integration
      • Custom CDP Integration
      • Generic CDP Integration
    • Other Integrations
      • Wicket Labs
      • Webhooks
        • Introduction to the Nami ML Event System
        • Event Types
          • Purchase Status Updates
          • Events for Upgrades, Downgrades, and Crossgrades
        • Event Subscriptions
        • Understanding Transferred Events and Accounts
      • API Access
    • Events Feed
  • Analytics
    • Using Charts
    • Paywall Analytics
      • Impressions
      • Paywall Conversion Rate
      • Sessions
      • Active Devices
    • Subscription Analytics
      • Revenue
      • MRR
      • Purchases
      • Trial Starts
  • Nami Account
    • Manage your Apps
      • Find your Nami App Platform ID
      • Setting up Legal Text for your Apps
    • Organization
      • Configuring Organization Security Policies
      • Billing
    • Invite your Team
      • Roles
    • Manage your Account
      • Two-Factor Authentication (2FA)
Powered by GitBook
On this page
  • Delivery Timing
  • Event Data Structure
  • EventAttributes Elements
  • Example Payload
  1. Integrations
  2. Other Integrations
  3. Webhooks
  4. Event Types

Purchase Status Updates

Last updated 8 months ago

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 .

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

webhook