Skip to main content

Documentation Index

Fetch the complete documentation index at: https://documentation.qonversion.io/llms.txt

Use this file to discover all available pages before exploring further.

Qonversion validates user receipts with app stores and sends subscription events to your HTTP endpoints. Keep in mind events delivery time when using webhooks to manage subscriber statuses on your back-end. Webhook delivery is asynchronous and typically completes within tens of seconds, but the exact latency depends on store-side notification timing, your server’s response time, and any retries. For real-time subscription status on the client-side, use the checkEntitlements method of the Qonversion SDK.

​
1. Set up the webhook URL

  1. Navigate to the Integrations section in your Qonversion account and select Webhooks.
  2. Register your URL and Qonversion will send a request
  3. Press the “Add new integration” or “Save” button. If the endpoint server returns a 200 response code, the integration is activated.

​
Sandbox webhook URL

The Webhooks integration form also exposes a separate Sandbox Webhook URL field. Production-environment events are delivered to the main URL; sandbox-environment events (environment: "sandbox") are delivered to the Sandbox URL when it is set. If you receive sandbox events but leave the Sandbox URL empty, Qonversion will fail to deliver them and they will be retried until the per-event tracking window expires.

​
2. Request format

Qonversion sends POST request to webhook URL every time an event occurs. The request includes an Authorization header of the form Basic <token>, where <token> is the Header Authorization-Token Value you configured in the Webhooks integration settings - it is sent as-is, not base64-encoded as in standard HTTP Basic auth. Use it to protect your server from unwanted requests.

​
SSL certificate

Remember, maintaining secure connections is essential for the integrity and reliability of your application’s communication.Ensure the SSL certificate used is not expired and your server’s CA bundle is up-to-date to recognize the latest root CAs.
Request Header: 
Authorization: Basic {Header Authorization-Token}
Accept: application/json
Request Body: 
{
    "event_name": "trial_converted",
    "user_id": "3YjIDEUDaf_5g4IdWw6zcMlLgfg_YQp2",
    "custom_user_id": "",
    "identity_id": "",
    "advertiser_id": "9FD1767D-8B48-45BD-A2F4-1C08B08E56F2",
    "time": 1600000000,
    "created_at": 1600000000,
    "product_id": "com.myapp.subs.9.99.trial",
    "revenue": {
        "value": 7.99,
        "value_usd": 9.99,
        "currency": "GBP",
        "is_proceed": 0,
        "proceeds_rate": 70
    },
    "price": {
        "value": 7.99,
        "value_usd": 9.99,
        "currency": "GBP"
    },
    "transaction": {
        "transaction_id": "500000601234560",
        "original_transaction_id": "500000601234560",
        "expires": 1600259200,
        "grace_period_expires": null,
      "transaction_date": 1600004000,
			"promo_offer_id": "appname.subscription.month.withoutTrial.promo"

    },
    "properties": {
        "_q_email": "me@qonversion.io"
    },
    "device_id": "0E66565D-4F3A-E366-B3D4-B5DDAC6BBE2E",
    "app_version": "2.1.4",
    "sdk_version": "3.1.0",
    "environment": "production",
    "platform": "iOS",
    "ip": "10.0.0.1",
    "country": "GB",
    "storefront": "GBR",
    "old_product_id": "com.myapp.subs.4.99.trial",
    "new_product_id": "com.myapp.subs.9.99.trial",
    "locale": "en_US",
    "subscription_group": "784563",
    "user_install_date": 1600000000,
    "project_name": "Sample App",
    "app_id": "com.sample.app",
    "quantity": 3,
    "subscription_renew_count": 5,
    "entitlements": {
        "0": {
            "active": true,
            "expires": 1654215637,
            "id": "plus",
            "product": {
                "product_id": "main",
                "subscription": {
                    "current_period_type": "normal",
                    "renew_state": "will_renew"
                }
            },
            "source": "stripe",
            "started": 1652438020
        }
    },
    "asa_attribution": {
        "org_id": 1234567890,
        "campaign_id": 1234567890,
        "adgroup_id": 1234567890,
        "keyword_id": 1234567890,
        "ad_id": 1234567890,
        "country_or_region": "DE",
        "conversion_type": "Download",
        "click_date": "2024-08-21T16:10Z",
 		   	"impression_date": "2024-08-21T16:10Z",
    		"claim_type": "Impression"
    }
}
ColumnRequiredDescription
event_nameyesEvent name provided in the integration config. See the details on the events trackedhere
user_idyesUnique user identifier assigned by Qonversion
custom_user_idyesUnique user identifier that you can set with Qonversion SDK methods:User Identifiers
identity_idyesUnique user ID for the authenticated users that you can set using identify method of the Qonversion SDK
advertiser_idyesIDFA or AAID
timeyesThe time an app store changed a subscription status or a time Qonversion detected the change in the UNIX epoch time format in seconds. Read more about events timehere
created_atyesThe time Qonversion generated the event
product_idyesApp Store or Google Play Store product identifier
revenueyesDictionary with transaction revenue details. Only events with value filled
priceyesDictionary containing the price details of the product
transactionyesDictionary with store transaction IDs and expiration timestamp
propertiesyesUser properties provided by SDK as a JSON object (always present; sent as {} when the user has no properties). Read more about user properties here.
device_idyesidentifierForVendor or Settings Secure Android ID.
app_versionnoApplication version.
sdk_versionnoQonversion SDK version.
environmentyes”production” or “sandbox”.
platformyes”iOS”, “Android”, or “Stripe”.
ipyesApplication device IP address.
countryyesA two-letter code representing a country, defined by theISO 3166-1 alpha-2standard, is determined on the Cloud provider’s side based on the IP address of the incoming request.
storefrontnoApple App Store country code (ISO 3166-1 alpha-3, e.g. “CHN”, “USA”, “GBR”). Represents the storefront from which the transaction originated. Not the user’s geographic location. Only available for iOS transactions when an App Store Connect API Certificate is configured.
old_product_idnoPrevious product (for product change events).
new_product_idnoNew product (for product change events).
localeyesA two-letter code representing a device language based on the device locale.
subscription_groupyessubscription_group_identifier for iOS or Google base_plan_id for Android. Empty string for Stripe events.
user_install_dateyesTimestamp when the user last installed the application.
project_nameyesThe project name of your app from the Qonversion dashboard.
app_idyesStore App Id. App Store ID for iOS or Android Package Name for Android.
quantitynoNumber of consumable in-app purchases. For non-consumable items or subscriptions, it will always return 1. Only present when the event has an associated transaction.
subscription_renew_countnoTotal number of times a user’s subscription has been renewed. Only present for events that carry a renewal counter (e.g. subscription renewals).
entitlementsyesGranted user entitlements. Always present, delivered as a JSON object keyed by zero-based index ({"0": {...}, "1": {...}}); sent as {} when the user has no active entitlements. Entity fields are synchronised with our public API.
asa_attributionnoDictionary with Apple Search Ads attribution details. Only for events for users who were attributed with the ad.

​
Revenue and price fields

There are 3 fields that contain transaction details:
  • The revenue field contains a dictionary with details depending on your integration setting Send sales as proceed.
  • The price field always contains a gross price that is charged to a user.
  • The transaction field contains params of the transaction related to the event.

​
Revenue

ColumnRequiredDescription
valueyesValue in user’s currency
value_usdyesValue in USD
currencyyesThree-letter ISO currency code
is_proceedyes1 – if value and value_usd are net excluding app stores’ commission; 0 - if values are before deducting app stores commission;
proceeds_rateyes70 or 85; Proceeds rate that developer receives after deducting app stores commission.

​
Price

ColumnRequiredDescription
valueyesValue in user’s currency
value_usdyesValue in USD
currencyyesThree-letter ISO currency code

​
Transaction

ColumnRequiredDescription
transaction_idyesTransaction_id from App Store (e.g. 521456677817903) or Play Store (e.g. GPA.4563-9870-7648-87395)
original_transaction_idyesTransaction_id from App Store (e.g. 521456677817903) or Play Store (e.g. GPA.4563-9870-7648-87395)
expiresyesExpire timestamp for purchase, prolong or product change events, event timestamp for refund or upgrade events.
grace_period_expiresyesGrace period expiration timestamp. This field returns the timestamp for the grace period expiration.
transaction_dateyesTimestamp when the transaction was made.
For the Billing Issue, Trial Canceled, Subscription Canceled, Subscription Upgraded events, the transaction_id field will be the same as for the previous related event. For the Subscription Renewed, Subscription Downgraded, Subscription Product Changed events, we’re sending a newer transaction_id.

​
Apple Search Ads attribution fields

You need to set up Apple Search Ads integration first, then we will send ASA attribution with all new events for only attributed users. The data in the table below can be found in the asa_attribution field. 
{
  ...
  "asa_attribution": {
    "org_id": 1234567890,
    "campaign_id": 1234567890,
    "adgroup_id": 1234567890,
    "keyword_id": 1234567890,
    "ad_id": 1234567890,
    "country_or_region": "DE",
    "conversion_type": "Download",
    "click_date": "2024-08-21T16:10Z",
    "impression_date": "2024-08-21T16:10Z",
    "claim_type": "Impression"
  }
}
ColumnRequiredDescription
org_idyesThe identifier of the Organization or Campaign group Id that owns the campaign.
campaign_idyesThe unique identifier for the campaign.
adgroup_idyesThe identifier for the ad group.
keyword_idnoThe identifier for the keyword.
ad_idyesThe identifier representing the assignment relationship between an ad object and an ad group.
country_or_regionyesThe country or region for the campaign.
conversion_typeyesThe type of conversion is either Download or Redownload.
click_datenoThe date and time when the user clicks an ad in a corresponding campaign. Available only if a user accepts App Tracking Transparency (ATT).
impression_datenoThe date and time when an ad view occurs in a corresponding Apple Search Ads campaign. Available only if a user accepts App Tracking Transparency (ATT).
claim_typenoThe type of claim is either Impression or Click.
Learn more about fileds from Apple AdSevices documentation.

​
Retries between Qonversion and Destination Server

Qonversion increases the delivery rate to your server with retries. Retries happen automatically if your server is not responding (returns a non-2xx status, times out, or is unreachable). This substantially improves the data delivery rate. After the initial attempt fails, Qonversion schedules up to five retries spread over roughly 24 hours, then abandons the per-event delivery job. The tracking record itself is retained for 7 days. Retries have the following schedule (delay measured from the previous attempt):
AttemptDelay since previousApprox. time since first attempt
1Immediate0
21 minute~1 minute
35 minutes~6 minutes
4~3 hours 55 minutes~4 hours
54 hours~8 hours
616 hours~24 hours
Tenjin Refund Keeper