In this guide, we will walk you through the process of adding the app to PartnerJam.

Step 1: Prepare your Shopify Partner account details

In order to get information about sales and attribution of your referrals, we basically need 2 information:
An Partner API token - here’s the guide how to create it: How to create or change an API token.
Your Shopify Partner ID - a unique identifier called Partner ID assigned for each associated developer account.

Are you concerned about privacy? We are a European company, an established Shopify app developer, fully compliant with GDPR, and we do not share or use your data for anything other than referral attribution. You can learn more about our privacy practices: here

Step 2: Follow the Installation Process

Connect your Shopify account with PartnerJam on this page and enter your Partner ID and Partner API token:



Add the details about your referral program:



Create a landing page that you can use to promote the referral program to your publishers. On this page, you can explain the benefits of your affiliate program, and list all your apps. Learn more about why and how to optimize your landing page.

Recommended: How to enable redirection to your app's Shopify App Store link

By default, we use a custom installation page to attribute installs. This default method doesn't require any changes to your app's code and works right away. It is ideal for trying PartnerJam without any additional implementation.

However, by implementing a simple tracking code (see below), you can enable affiliate links to redirect users directly to the Shopify App Store. This implementation can significantly increase the conversion rate of your affiliate links - see the example link here.

You can learn more about differences between the methods in this article: How do affiliate links work?

Enable redirect to Shopify App Store

Implement an HTTP endpoint in your application that PartnerJam redirects the user to. This endpoint will store the partner_jam_token in the cookie and redirect the user to the Shopify app store.

Python/Django example

import datetime
from django.http import HttpResponseRedirect

def installation_init_view(request):
    partner_jam_token = request.GET.get("token")
    app_store_url = 'https://apps.shopify.com/your-app-name'  # replace with your app store url
    expiration = timezone.now() + timedelta(
        days=60,  # feel free to adjust the cookie validity. 60 days is recommended.
    )
    
    if not partner_jam_token:
        raise Http404
        
    response = HttpResponseRedirect(app_store_url)
    response.set_cookie(
        "partner_jam_token",
        partner_jam_token,
        expires=expiration,
        httponly=True,
        secure=True,
        samesite="Lax",
    )
    return response

NodeJS/Express example

app.get('/partner-jam-init', function (request, response) {
    const partnerJamToken = req.query.token;
    const appStoreUrl = 'https://apps.shopify.com/your-app-name'; // replace with your app store url
    
    const currentDate = new Date();
    const expirationDate = new Date(currentDate);
    expirationDate.setDate(currentDate.getDate() + 60); // feel free to adjust the cookie validity. 60 days is recommended.

    if (!partnerJamToken) {
        response.status(404).send('Not Found');
        return;
    }
    
    response.cookie("partner_jam_token", partnerJamToken, {
        expires: expirationDate,
        httpOnly: true,
        secure: true,
        sameSite: "Lax",
    });
    response.redirect(appStoreUrl);
});

Enter the endpoint URL into PartnerJam’s “Endpoint URL”

Enrich your installation logic so that your application notifies PartnerJam about successful installation via calling PartnerJam’s HTTP endpoint. Your app will send partner_jam_token stored in the cookie together with Shopify domain of the merchant. Thanks to that PartnerJam will be able to attribute the installation to the correct publisher.

It's necessary to read the partner_jam_token from the cookie on an endpoint that is not rendered in an Iframe (= it is not embeded in Merchant Admin). The safest place where to read the cookie is on an URL where Shopify redirects the merchant after finishing oAuth processes. You can find such URL in you Shopify application setup.

Python example

def install_app_view(request):
    # do your logic
    shop = store_shop_data(request)
    app_secret = '<secret>' # Obtain this from the actual code snippet in the PartnerJam on the "Edit app" page
    token = request.COOKIES.get("partner_jam_token")
    requests.post(
        "https://be-app.partnerjam.com/webhooks/installation-confirm/",
         json={
             "token": token,
             "shopify_id": shop.shopify_id,
             "shop_name": shop.shop_name,
             "myshopify_domain": shop.myshopify_domain,
             "secret": app_secret,
             "test": False,  # set True for dry run (only for testing purposes)
         }
    )

NodeJS example

const axios = require("axios");

async function installAppView(request) {
  // do your logic
  const shop = store_shop_data(request);
  const appSecret = "<secret>" // Obtain this from the actual code snippet in the PartnerJam on the "Edit app" page
  const token = request.cookies.partner_jam_token;
  await axios.post(
    "https://be-app.partnerjam.com/webhooks/installation-confirm/",
    {
      token: token,
      shopify_id: shop.shopify_id,
      shop_name: shop.shop_name,
      myshopify_domain: shop.myshopify_domain,
      secret: appSecret,
      test: false, // set true for dry run (only for testing purposes)
    }
  );
}

Provide discount on affiliate links

Optionally, select the "Enable discount for publishers" feature ( learn more about the feature) and adjust your charging logic - find out whether the merchant should receive a discount by querying the PartnerJam API endpoint and apply the discount to the Shopify charge if the merchant is eligible for it.




Python example

def create_discounted_charge(request):
    price, plan_name = create_charge(request)
    if discount_token := request.COOKIES.get('partner_jam_token'):
        try:
            response = requests.get(
                "https://be-app.partnerjam.com/api/v1/discount-check/",
                params={
                    "token": discount_token,
                },
            )
            response.raise_for_status()
            discount = response.json().get("discount")
            if discount:
                price -= price * (discount / 100)
                plan_name = f"{plan_name} ({discount}% discount)"
        except requests.exceptions.RequestException as e:
            print(f"Error occurred while checking discount: {e}")

     return price, plan_name

NodeJS example

async function createDiscountedCharge(request) {
    const [price, planName] = createCharge(request);
    const discountToken = request.cookies.partner_jam_token;

    if (discountToken) {
        try {
            const response = await axios.get(`https://be-app.partnerjam.com/api/v1/discount-check/?token=${discountToken}`);
            const { discount } = response.data;
            if (discount) {
                const discountedPrice = price - price * (discount / 100);
                const discountedPlanName = `${planName} (${discount}% discount)`;
                return [discountedPrice, discountedPlanName];
            }
       } catch (error) {
            console.error('Error occurred while checking discount:', error);
       }
   }

   return [price, planName];
}

Understanding the process

To help you in understanding the whole process we've prepared a sequence diagram of the communication between PartnerJam, Your Shopify Application and Shopify.

Full integration example

Check our Sample Shopify Application with PartnerJam integration repository for understanding how to practically integrate the PartnerJam into existing Shopify application.

Updated on: 02/02/2024