Track conversion events

DOCS

Last updated: Sept 24th, 1:26am

Note: Accelerated checkout is a limited release solution. This API and integration guide is only used with merchants and partners integrating with accelerated checkout versions 0.5 and 0.6.

The objective of accelerated checkout is to increase guest card checkout conversion by autofilling payers' checkout details. To measure that increase, PayPal requires merchants and partners to send a specific set of events as users trigger them on the checkout page. This integration guide specifies how a partner or merchant can send analytics event data to PayPal.

Guest card conversion for merchants is defined as number of guest card checkout sessions ending in successful transactions, divided by the number of guest card checkout sessions.

A checkout session is considered a guest session if the payer doesn't have a store account or doesn't pay with an alternate payment method.

Required events

PayPal requires the following events to measure checkout conversion for guest card users:

Event	Description	Trigger	Sent using
Checkout Page Loaded	A payer has entered the checkout flow from anywhere on the merchant’s site, starting a checkout session.	Payer loads the checkout page	Server-side API or client-side SDK
Email Submitted	A payer has entered their email, which helps identify them as either a store guest or store member, and whether they are in the test or control side of the A/B test.	payer submits their email in the email field	server-side API or client-side SDK
APM Selected	A payer attempted to use an alternate payment method, such as PayPal or Google Pay, to check out. Track this event to exclude from the conversion calculation.	Payer clicks any alternate payment method button on the checkout page	Client-side SDK
Order Placed	A payer clicked the Place Order button.	Payer clicks the Place Order button or equivalent button for a card transaction.	Client-side SDK
Checkout Ended	A payer completed their transaction and the payment was processed. Counts as a completed checkout session for the conversion equation.	Payer's payment was processed.	Server-side API

Integrations

Send events over one of the following pipelines:

Server-side API

Client-side SDK

Server-side API

Server-side analytics API

API Specification

Attribute	Value
Production hostname	`https://api-m.paypal.com`
API endpoint	`POST /v2/tracking/events`
Header	`Authorization: Bearer ACCESS-TOKEN`

For details on generating the access token, refer to PayPal API Authentication.

Sample request

1curl -v -k -X POST 'https://api-m.paypal.com/v2/tracking/events'\
2 -H 'Authorization: Bearer ACCESS-TOKEN'\
3 -H 'Content-Type: application/json'\
4 -d '{
5    "channel": "SERVER",
6    "event_params": {
7       "t": 1692383125640,
8       "local_timestamp": "2023-08-18T18:30:00-0800",
9       "event_name": "axo_merchant_checkout_started",
10       "component": "axo_partner",
11       "context_type": "cmid",
12       "context_id": "3cf508ff-d892-4bef-9139-de4e9b8042cb",
13       "event_source": "server",
14       "page_type": "cart_page",
15       "page_name": "mobile:android:low_resolution:v1:cart_page",
16       "url": "{"domain": "example.com","url": "http://checkout.example.com"}",
17       "apm_shown": "1",
18       "apm_list": "klarna,amazon_pay,apple_pay",
19       "sku": "[{"item_id": "","item_name": "","item_desc": "","item_amt": "","item_cnt": ""}]",
20       "partner_name": "bigc",
21       "user_type": "store_guest",
22       "ip_addr_hash": "661cebeba6d3ef943b2b76354d82eae5",
23       "account_country": "US",
24       "store_id": "12AF",
25       "merchant_name": "Example Co.",
26       "merchant_location_name": "{"country": "US", "state": "CA", "city": "Anytown"}",
27       "device_type": "mobile",
28       "platform": "android",
29       "browser_type": "chrome",
30       "browser_version": "116.0.5845.96",
31       "network_connection_type": "wifi",
32       "service_provider": "T Mobile",
33       "application_version": "1.0.1",
34       "browser_integration": "webview",
35       "experiment": "[{"experiment_name":"axo_checkout_ramp1","treatment_group":"axo_treatment_grp1","ramp_value":"20%"},{"experiment_name":"axo_checkout_ramp1","treatment_group":"axo_control_grp1","ramp_value":"50%"}]"
36  }
37}'

Modify the code

channel: The source from which the data is coming into the system. Valid values are:
- EMAIL: The event triggered in an email
- MOBILE: The event triggered on a mobile device
- WEB: The event triggered on a website
- SERVER: The event triggered from a server

event_params: Contains the event-specific tags. The details of the tags that need to be passed for each event are described later in this document.

A successful request results in an HTTP 204: No Content response code.

Session identifier

This API is used to track events that occur if the Braintree Web SDK isn't used. A common identifier need to be passed to this API and the Braintree Web SDK so that the events sent over both channels can be connected.

The merchant generates a session identifier to uniquely identify a checkout flow, such as the cart_id. Pass this ID as the context_id in the payload.

When instantiating the Braintree Web SDK’s Data Collector, pass the same value in the risk co-relation ID parameter.

Client-side SDK using connect component

As an interim solution to capture event data from the client-side for accelerated checkout versions 0.5 and 0.6, an events object to the connect module exposes methods to send event data for specific events that occur.

Each method sends the corresponding event and should be called at each event’s respective trigger point.

1interface Connect {
2  identity {
3    // ...
4  }
5  events {
6    checkoutPageLoaded: (options: CheckoutPageLoadedEventOptions) => void,
7    apmSelected: (options: ApmSelectedEventOptions) => void,
8    emailSubmitted: (options: EmailEnteredEventOptions) => void,
9    orderPlaced: (options: OrderPlacedEventOptions) => void
10  }
11  setLocale: (locale: string) => void,  // options: en_us, es_us, fr_us, zh_us
12} 
13interface CheckoutPageLoadedEventOptions {
14    "t": 1692383125640,
15    "local_timestamp": "2023-08-18T18:30:00-0800",
16    "context_id": "3cf508ff-d892-4bef-9139-de4e9b8042cb",
17    "page_type": "cart_page",
18    "page_name": "mobile:android:low_resolution:v1:cart_page",
19    "url": "{"domain": "example.com","url": "http://checkout.example.com?=98a7wert9y8wefg9ay"}",
20    "apm_shown": "1"
21    ...
22}
23interface ApmSelectedEventOptions {
24    "t": 1692383125640,
25    "local_timestamp": "2023-08-18T18:30:00-0800",
26    "context_id": "3cf508ff-d892-4bef-9139-de4e9b8042cb",
27    "page_type": "cart_page",
28    "page_name": "mobile:android:low_resolution:v1:cart_page",
29    "url": "{"domain": "example.com","url": "http://checkout.example.com?=98a7wert9y8wefg9ay"}",
30    "apm_shown": "1"
31    ...
32}
33interface EmailSubmittedEventOptions {
34    "t": 1692383125640,
35    "local_timestamp": "2023-08-18T18:30:00-0800",
36    "context_id": "3cf508ff-d892-4bef-9139-de4e9b8042cb",
37    "page_type": "cart_page",
38    "page_name": "mobile:android:low_resolution:v1:cart_page",
39    "url": "{"domain": "example.com","url": "http://checkout.example.com?=98a7wert9y8wefg9ay"}",
40    "apm_shown": "1"
41    ...
42}
43interface OrderPlacedEventOptions {
44    "t": 1692383125640,
45    "local_timestamp": "2023-08-18T18:30:00-0800",
46    "context_id": "3cf508ff-d892-4bef-9139-de4e9b8042cb",
47    "page_type": "cart_page",
48    "page_name": "mobile:android:low_resolution:v1:cart_page",
49    "url": "{"domain": "example.com","url": "http://checkout.example.com?=98a7wert9y8wefg9ay"}",
50    "apm_shown": "1"
51    ...
52}