Skip to main content Link Menu Expand (external link) Document Search Copy Copied

Converge Server Integration

This section explains how to send events to Converge from your server.

Table of contents

  1. Retrieve a postback endpoint
  2. Implementing Ecommerce Server Events
    1. Placed Order
    2. Started Subscription
    3. Cancelled Subscription
    4. Placed Recurring Subscription Order

1. Retrieve a postback endpoint

This guide helps you install the basic Converge Pixel which tracks $page_load-events by default.

  1. Log in to the Converge webapp on app.runconverge.com and click on the Sources tab in the left side-bar.
  2. Click on Create a new source and pick Server-side from the modal
  3. Name your integration: e.g. {Storename} Server
  4. Choose Webhook from the dropdown of apps and click on Create Source.
  5. Once you create the source, you will receive a Postback endpoint, use this postback endpoint to send any of the events below.

2. Implementing Ecommerce Server Events

a) Placed Order

Description

When a user places an order.

Code example:

📌 Make sure you pass as many profile properties and appropriate aliases as possible. You can read more about profile_properties here, and about aliases here.

📌 We expect raw JSON, and no form-data or form-urlencoded data types.

📌 Make sure you pass the $is_new_customer property.

📌 Make sure your event_id is globally unique.

resp = requests.post(
    "{YOUR_POSTBACK_ENDPOINT}",
    json=
        {
        "event_name": "Placed Order",
        "event_id": "order-1", # your order id, necessary for deduplication
        "properties": {
            "id" : "order-1", # will be shown in the UI
            "total_price": 42,
            "total_tax": 3.5,
            "total_shipping": 2.4,
            "currency": "USD",
            "items": [
                {
                    "product_id": "123456",
                    "variant_id": "654321", # important for Shopify stores
                    "sku": "MY_SKU",
                    "name": "My Product",
                    "price": 42,
                    "currency": "USD",
                    "quantity": 1,
                    "vendor": "My Store",
                },
            ],
            "$first_name": "John",
            "$last_name": "Smith",
            "$email": "john.smith@apple.com",
            "$phone_number": "+199999999",
            "$city": "San Francisco",
            "$country_code": "US",
            "$state": "California",
            "$zip_code": "94103",
            "$is_new_customer": False, # important
        },
        "profile_properties": {
            # Pass as many as possible
            "$first_name": "John",
            "$last_name": "Smith",
            "$email": "john.smith@apple.com",
            "$phone_number": "+199999999",
            "$city": "San Francisco",
            "$country_code": "US",
            "$state": "California",
            "$zip_code": "94103",
        },
        "aliases": ["urn:email:john.smith@apple.com"],
    }
)

 

b) Started Subscription

📌 This event is only relevant if you sell subscription items.

Description

When a user starts a subscription.

Code example:

📌 Make sure you pass as many profile properties and appropriate aliases as possible. You can read more about profile_properties here, and about aliases here.

📌 We expect raw JSON, and no form-data or form-urlencoded data types.

resp = requests.post(
    "{YOUR_POSTBACK_ENDPOINT}",
    json=
        {
        "event_name": "Started Subscription",
        "properties": {
            "id": "4001920", # the subscription id
            "total_price": 42,
            "total_tax": 3.5,
            "total_shipping": 2.4,
            "currency": "USD",
            "items": [
                {
                    "product_id": "123456",
                    "variant_id": "654321", # important for Shopify stores
                    "sku": "MY_SKU",
                    "name": "My Product",
                    "price": 42,
                    "currency": "USD",
                    "quantity": 1,
                    "vendor": "My Store",
                },
            ],
            "$first_name": "John",
            "$last_name": "Smith",
            "$email": "john.smith@apple.com",
            "$phone_number": "+199999999",
            "$city": "San Francisco",
            "$country_code": "US",
            "$state": "California",
            "$zip_code": "94103",
        },
        "profile_properties": {
            # Pass as many as possible
            "$first_name": "John",
            "$last_name": "Smith",
            "$email": "john.smith@apple.com",
            "$phone_number": "+199999999",
            "$city": "San Francisco",
            "$country_code": "US",
            "$state": "California",
            "$zip_code": "94103",
        },
        "aliases": ["urn:email:john.smith@apple.com"],
    }
)

 

c) Cancelled Subscription

📌 This event is only relevant if you sell subscription items.

Description

When a user cancels a subscription.

Code example:

📌 Make sure you pass as many profile properties and appropriate aliases as possible. You can read more about profile_properties here, and about aliases here.

📌 We expect raw JSON, and no form-data or form-urlencoded data types.

resp = requests.post(
    "{YOUR_POSTBACK_ENDPOINT}",
    json=
        {
        "event_name": "Cancelled Subscription",
        "properties": {
            "id": "4001920", # the subscription id
            "total_price": 42,
            "total_tax": 3.5,
            "total_shipping": 2.4,
            "currency": "USD",
            "items": [
                {
                    "product_id": "123456",
                    "variant_id": "654321", # important for Shopify stores
                    "sku": "MY_SKU",
                    "name": "My Product",
                    "price": 42,
                    "currency": "USD",
                    "quantity": 1,
                    "vendor": "My Store",
                },
            ],
            "$first_name": "John",
            "$last_name": "Smith",
            "$email": "john.smith@apple.com",
            "$phone_number": "+199999999",
            "$city": "San Francisco",
            "$country_code": "US",
            "$state": "California",
            "$zip_code": "94103",
        },
        "profile_properties": {
            # Pass as many as possible
            "$first_name": "John",
            "$last_name": "Smith",
            "$email": "john.smith@apple.com",
            "$phone_number": "+199999999",
            "$city": "San Francisco",
            "$country_code": "US",
            "$state": "California",
            "$zip_code": "94103",
        },
        "aliases": ["urn:email:john.smith@apple.com"],
    }
)

d) Placed Recurring Subscription Order

📌 This event is only relevant if you sell subscription items.

Description

When a user places a recurring subscription order.

Code example:

📌 Make sure you pass as many profile properties and appropriate aliases as possible. You can read more about profile_properties here, and about aliases here.

📌 We expect raw JSON, and no form-data or form-urlencoded data types.

resp = requests.post(
    "{YOUR_POSTBACK_ENDPOINT}",
    json=
        {
        "event_name": "Placed Recurring Subscription Order",
        "properties": {
            "id": "4001920", # the subscription id
            "total_price": 42,
            "total_tax": 3.5,
            "total_shipping": 2.4,
            "currency": "USD",
            "items": [
                {
                    "product_id": "123456",
                    "variant_id": "654321", # important for Shopify stores
                    "sku": "MY_SKU",
                    "name": "My Product",
                    "price": 42,
                    "currency": "USD",
                    "quantity": 1,
                    "vendor": "My Store",
                },
            ],
            "$first_name": "John",
            "$last_name": "Smith",
            "$email": "john.smith@apple.com",
            "$phone_number": "+199999999",
            "$city": "San Francisco",
            "$country_code": "US",
            "$state": "California",
            "$zip_code": "94103",
        },
        "profile_properties": {
            # Pass as many as possible
            "$first_name": "John",
            "$last_name": "Smith",
            "$email": "john.smith@apple.com",
            "$phone_number": "+199999999",
            "$city": "San Francisco",
            "$country_code": "US",
            "$state": "California",
            "$zip_code": "94103",
        },
        "aliases": ["urn:email:john.smith@apple.com"],
    }
)