Logging Standard Events

  • Updated on May 1, 2026
  • Published on Feb 25, 2025
Prev Next
Post
/event/standard

This endpoint is used to log standard events i.e. Commerce, Content, User Lifecycle.

Important considerations

  • Real-time only: Events must be sent in real time as they occur. Branch does not support backtracking or historical event ingestion. Events with timestamps in the past will not be backfilled into reports.
  • SKAdNetwork (SKAN): SKAN must be handled natively by your app, not via the Branch SDK. Branch returns SKAN-relevant fields (such as coarse_key and update_conversion_value) in the API response so your app can update its conversion value accordingly. See the SKAdNetwork guide for details.
Header parameters
Content-Type
string

Recommended. The media type of the request body. Should be application/json.

Accept
string

Recommended. The media type the client expects in the response. Should be application/json.

X-IP-Override
string

Optional. Override the IP address Branch uses for the event (for example, when forwarding events server-to-server from your own backend).

Two requirements must be met for this header to function:

  1. Your app ID must be allowlisted by Branch. The header is ignored until allowlisting is enabled. Open a support request to have your app ID allowlisted before sending this header in production.
  2. You must also include user_data.ip in the request body with the same IP value. Sending the header alone is not sufficient — the body field is what Branch persists for attribution.
Body parameters
Expand All
object
branch_key
string Required

The Branch Key of the originating app obtained in your Account Settings

Examplekey_live_xxxx
name
string Required

The name of the event to log. Must be one of the following standard Branch Event names:

  • Commerce:
    • ADD_TO_CART
    • ADD_TO_WISHLIST
    • VIEW_CART
    • INITIATE_PURCHASE
    • ADD_PAYMENT_INFO
    • CLICK_AD
    • PURCHASE
    • SPEND_CREDITS
    • VIEW_AD
  • Content:
    • SEARCH
    • VIEW_ITEM
    • VIEW_ITEMS
    • RATE
    • SHARE
    • INITIATE_STREAM
    • COMPLETE_STREAM
  • User Lifecycle:
    • COMPLETE_REGISTRATION
    • COMPLETE_TUTORIAL
    • ACHIEVE_LEVEL
    • UNLOCK_ACHIEVEMENT
    • INVITE
    • LOGIN
    • START_TRIAL
    • SUBSCRIBE
Valid values[ "ADD_TO_CART", "ADD_TO_WISHLIST", "VIEW_CART", "INITIATE_PURCHASE", "ADD_PAYMENT_INFO", "CLICK_AD", "PURCHASE", "SPEND_CREDITS", "VIEW_AD", "SEARCH", "VIEW_ITEM", "VIEW_ITEMS", "RATE", "SHARE", "INITIATE_STREAM", "COMPLETE_STREAM", "COMPLETE_REGISTRATION", "COMPLETE_TUTORIAL", "ACHIEVE_LEVEL", "UNLOCK_ACHIEVEMENT", "INVITE", "LOGIN", "START_TRIAL", "SUBSCRIBE" ]
ExamplePURCHASE
customer_event_alias
string

The event alias as defined by you; used in addition to the event name defined above.

Examplemy custom alias
user_data
object (user_data_standard) Required

Information about the user and the device the event occurred on.

Required identifiers: You must include at least one of the following in user_data:

  • developer_identity, or
  • browser_fingerprint_id, or
  • os=iOS AND idfa, or
  • os=iOS AND idfv, or
  • os=Android AND android_id, or
  • os=Android AND aaid
os
string

One of the following operating system e.g. Android, iOS,MAC_OS,LINUX,WINDOWS etc.

ExampleAndroid
os_version
string

The version of the operating system. Strongly recommended for all paid traffic to ensure accurate attribution. Required for Facebook campaigns on iOS.

Example12.4.0
environment
string

usually FULL_APP

ExampleFULL_APP
aaid
string

The Android/Google advertising ID.

Exampleabcdabcd-0123-0123-00f0-000000000000
android_id
string

Android hardware ID

Examplea12300000000
idfa
string

iOS advertising ID

Example00000000-0000-0000-0000-000000000001
idfv
string

iOS vendor ID

Example00000000-0000-0000-0000-000000000002
anon_id
string

The Facebook anonymous user ID. Required when running Facebook campaigns using Aggregated Event Measurement (AEM) on iOS.

Examplefbanon_abc123def456
advertising_ids
object

Wrapper object for advertising identifiers. Use this in addition to the flat aaid, idfa, and idfv fields above to future-proof your integration for non-standard IDs (for example, OAID on Huawei devices). Additional advertising ID keys may be supported as new platforms emerge — contact Branch Support if you need to send an identifier that is not listed here.

oaid
string

Open Advertising ID, used on Huawei devices and other Android devices without Google Play Services.

Example00aa00a0-0000-0a00-a000-aaa0000a0aaa
google_analytics_id
string

The Google Analytics client ID, useful for cross-platform stitching with Google Analytics. Include where applicable to improve attribution coverage and downstream analytics.

ExampleGA1.2.123456789.1234567890
limit_ad_tracking
boolean

true if the partner has opted to not be tracked by advertisers

Examplefalse
user_agent
string

The user agent of the browser or app where the event occurred. Usually associated with a webview.

ExampleMozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko)
browser_fingerprint_id
string

Branch internal-only field for tracking browsers.

Example857675855146829999
http_origin
string

The current page url where Web SDK logged web session start.

Examplehttps://example.com/landing
http_referrer
string

The referral url that led to the current page where Web SDK logged web session start.

Examplehttps://referrer.example.com/path
developer_identity
string

The developer-specified identity for a user.

Exampleuser123
country
string

The country code of the user, usually based on device settings or user agent string.

ExampleUS
language
string

The language code of the user, usually based on device settings or user agent string.

Exampleen
ip
string

The IP address for the device where the event occurred. Required if using the X-IP-Override request header.

Example198.51.100.42
local_ip
string

Android only - local ip of the device

Example192.0.2.1
brand
string

The brand of the device

ExampleLGE
randomized_device_token
string

Branch internal-only field for tracking devices.

Example857675855146829998
app_version
string

The app version downloaded by the user.

Example1.0.0
model
string

The model of the device.

ExampleNexus 5X
screen_dpi
integer

The screen's DPI.

Example420
screen_height
integer

The screen's height.

Example1794
screen_width
integer

The screen's width.

Example1080
dma_eea
boolean

Whether European regulations, including the DMA, apply to this user and conversion. Required if EU regulations apply to this user. Failure to include user consent signals may result in attribution or campaign performance degradation.

Exampletrue
dma_ad_personalization
boolean

Whether end user has granted or denied ads personalization consent. Required if dma_eea is set to true (i.e., EU regulations apply to this user). Failure to include user consent signals may result in attribution or campaign performance degradation.

Exampletrue
dma_ad_user_data
boolean

Whether end user has granted or denied consent for 3P transmission of user level data for ads. Required if dma_eea is set to true (i.e., EU regulations apply to this user). Failure to include user consent signals may result in attribution or campaign performance degradation.

Exampletrue
custom_data
object

Additional custom key-value pairs that you want attached to the event. Values may be of any JSON type. Attached to events retrieved via Exports and sent via Webhooks.

event_data
object (event_data_standard)
transaction_id
string

The partner-specified transaction id for their internal use

Example00000000
revenue
number

The partner-specified reported revenue for the event.

Example1.5
currency
string

Currency that revenue, price, shipping, tax were originally reported in by the partner

ExampleUSD
shipping
number

Shipping cost associated with the transaction.

Example10.2
tax
number

Total tax associated with the transaction.

Example12.3
coupon
string

Transaction coupon redeemed with the transaction (e.g. "SPRING2017")

Examplecoupon
affiliation
string

Store or affiliation from which this transaction occurred (e.g. Google Store)

Exampletest_affiliation
description
string

Description associated with the event, not necessarily specific to any individual content items (see below)

ExampleEvent_description
search_query
string

Additional search queries.

ExampleTest Search query
content_items
Array of object (content_items_standard)
object
$content_schema
string

Category / Schema for a piece of content.

Valid values[ "COMMERCE_AUCTION", "COMMERCE_BUSINESS", "COMMERCE_OTHER", "COMMERCE_PRODUCT", "COMMERCE_RESTAURANT", "COMMERCE_SERVICE", "COMMERCE_TRAVEL_FLIGHT", "COMMERCE_TRAVEL_HOTEL", "COMMERCE_TRAVEL_OTHER", "GAME_STATE", "MEDIA_IMAGE", "MEDIA_MIXED", "MEDIA_MUSIC", "MEDIA_OTHER", "MEDIA_VIDEO", "OTHER", "TEXT_ARTICLE", "TEXT_BLOG", "TEXT_OTHER", "TEXT_RECIPE", "TEXT_REVIEW", "TEXT_SEARCH_RESULTS", "TEXT_STORY", "TEXT_TECHNICAL_DOC" ]
ExampleCOMMERCE_PRODUCT
$og_title
string

Commerce and Content Reports only. The title (for the individual content item).

ExampleMy Content Title
$og_image_url
string

Commerce and Content Reports only. The image URL (for the individual content item).

Examplevalid URL
$canonical_identifier
string

Commerce and Content Reports only. Used to allow Branch to unify content/messages for Content Analytics

Exampleitem12345
$publicly_indexable
boolean

Commerce and Content Reports only. true- content can be seen by anyone. false- cannot index for public use

Examplefalse
$locally_indexable
boolean

Commerce and Content Reports only. true- content can be indexed for local (device) use. false- cannot index for local use

Exampletrue
$price
number

Commerce and Content Reports only. The price for the product/content.

Example23.2
$quantity
number

Commerce and Content Reports only. The quantity of the item to be ordered (for PURCHASE, ADD_TO_CART, etc).

Example2.0
$sku
string

Commerce and Content Reports only. The product sku or product ID.

Example1994320302
$product_name
string

Commerce and Content Reports only. The product's name.

Examplemy_product_name1
$product_brand
string

Commerce and Content Reports only. The product's brand.

Examplemy_prod_Brand1
$product_category
string

Commerce and Content Reports only. The product's category, if it's a product

Valid values[ "ANIMALS_AND_PET_SUPPLIES", "APPAREL_AND_ACCESSORIES", "ARTS_AND_ENTERTAINMENT", "BABY_AND_TODDLER", "BUSINESS_AND_INDUSTRIAL", "CAMERAS_AND_OPTICS", "ELECTRONICS", "FOOD_BEVERAGES_AND_TOBACCO", "FURNITURE", "HARDWARE", "HEALTH_AND_BEAUTY", "HOME_AND_GARDEN", "LUGGAGE_AND_BAGS", "MATURE", "MEDIA", "OFFICE_SUPPLIES", "RELIGIOUS_AND_CEREMONIAL", "SOFTWARE", "SPORTING_GOODS", "TOYS_AND_GAMES", "VEHICLES_AND_PARTS" ]
ExampleBABY_AND_TODDLER
$product_variant
string

Commerce and Content Reports only. The product's variant (e.g. XL, red).

Example3T
$rating_average
number

Commerce and Content Reports only. The average rating of the item.

Example4.2
$rating_count
number

Commerce and Content Reports only. The number of ratings for the item.

Example5.0
$rating_max
number

Commerce and Content Reports only. The maximum possible rating for the item (e.g. 5.0 if 5 stars is highest possible rating).

Example5.0
$creation_timestamp
integer (int64)

Commerce and Content Reports only. The time the content was created (Unix timestamp, typically in milliseconds).

Example1499892854966
$exp_date
integer (int64)

Commerce and Content Reports only. The last time after which this content is no longer valid. null / 0 mean no limit. Should rarely be set.

Example0
$keywords
Array of string

Commerce and Content Reports only. keywords

Example[ "sneakers", "shoes" ]
string
$address_street
string

Commerce and Content Reports only. The street address for a restaurant, business, room (hotel), etc.

ExampleStreet_name1
$address_city
string

Commerce and Content Reports only. The street address for a restaurant, business, room (hotel), etc.

Examplecity1
$address_region
string

Commerce and Content Reports only. The state or region for a restaurant, business, room (hotel), etc.

ExampleRegion1
$address_country
string

Commerce and Content Reports only. The country code for a restaurant, business, room (hotel), etc.

ExampleCountry1
$address_postal_code
string

Commerce and Content Reports only. The postal/zip code for a restaurant, business, room (hotel), etc.

Examplepostal_code
$latitude
number

Commerce and Content Reports only. The latitude for a restaurant, business, room (hotel), etc.

Example12.07
$longitude
number

Commerce and Content Reports only. The longitude for a restaurant, business, room (hotel), etc.

Example-97.5
$image_captions
Array of string

Commerce and Content Reports only. The captions associated with the image.

string
Examplemy_img_caption1
$condition
string

Commerce and Content Reports only. For auctions, whether the item is new, good, acceptable, etc.

Valid values[ "OTHER", "NEW", "EXCELLENT", "GOOD", "FAIR", "POOR", "USED", "REFURBISHED" ]
$custom_fields
object

Commerce and Content Reports only. key-value pairs that the app developer would like attached to the content item. Values may be of any JSON type. Attached to events that are retrieved via Exports and sent via Webhooks.

Responses
200

Ok

object

Successful event ingestion. The response carries SKAdNetwork-relevant fields that the app can use to update its native SKAN conversion value.

ascending_only
boolean
Examplefalse
coarse_key
string
Examplehigh
locked
boolean
Examplefalse
update_conversion_value
integer
Example3
400

Authentication Failed

Result
"{\n    \"error\": {\n        \"message\": \"Authentication failed !\",\n        \"code\": 400\n    }\n}"
Expand All
object
error
object (inline_response_400_error)
message
string
ExampleAuthentication failed !
code
integer
Example400
429

Rate Limit Reached

Result
"{\n    \"error\": {\n        \"code\": 429,\n        \"message\": \"Rate limit reached.\"\n    }\n}"
Expand All
object
error
object (inline_response_400_error)
message
string
ExampleAuthentication failed !
code
integer
Example400
Tags