Links

Adding a new app

Good to know: While you control all your affiliate programs from the same dashboard, you set up each one individually. That allows you to set different affiliate terms (ex. Commission Rate) for each app.

The New App Form

Go to the 'My Apps' page and click on the 'Add a new app' button. You will be redirected to the new app page.

Affiliate Terms

The contract details between an app and an affiliate. You can find a detailed explanation of the affiliate terms here.

App details

  • App name: The exact name as shows on the App Store.
  • App Logo :
    A .png file of your logo. a 125x125 is recommended.
  • Shopify App Store Listing Link:
    eg. https://apps.shopify.com/YourApp
  • App Support Email:
    Your affiliates will use this email if they want to contact you
  • App Category:
    Your App category, as it is on the Shopify app store. if you can't find the right one choose 'other'.

Authentication

  • Partner ID:
    Find it under Settings > Account information
  • Partners API Client Access Token:
Important! Shoffi requires API permissions to your app so we can tell if an install was made using a referral link, and calculate the earning and commission rates properly.
Those permissions grant us a 'Read only' access, which we use only to read the information that is relevant to the Shoffi platform.
We don't read any data that was prior to your integration with Shoffi. You can find more information about the Partner API permissions here.
When creating a new API client, please approve permissions to:
  • View financials
  • Manage apps
If it's your first time creating a Partner API key, you can follow Shopify's guide here.
App ID:
  • Go to your app page on the partner admin, and copy it from the URL.
    For example:
    https://partners.shopify.com/1111111/apps/1234567#/
    1234567 is your app ID.

App Resources (Optional)

Add links to a public Google Drive, YouTube channel, or any other platform where your affiliate partners can find resources and tutorials that will help them learn and promote the app.

The app integration process

Partners API connection

In order to submit the 'new app' form, you will need to validate the connection to your Shopify Partners API, to make sure the details you've entered are correct. In case one of the fields is wrong or if you haven't added the right permissions, you will get an error explaining exactly what went wrong.

The POST request

To complete the integration, you will need to add a POST request to your app. Later on, this request will help us match which affiliate is associated with each install if any.
The request will need to run every time a new store installs the app. This will allow us to connect every successful install to the correct affiliate.

Adding the code to your app

When OAuth is complete, you will get a request from Shopify, which contains the shop name and the 'X-Forwarded-For' header.
When you have those values, you need to send the POST request with the following data:
api_key, shopName, appId, XFF

Variables explanations:

  • "api_key": Your Shoffi key is generated once you add a new app. you can find it when clicking "edit app" on the "My apps" page.
  • "shopName": The shop name of the shop that is currently logged in to the app.(full, ex. newshop.myshopify.com)
  • "appId": The ID of your Shopify app. To find it go to your app page on the partner admin, and copy it from the URL. For example: "https://partners.shopify.com/1111111/apps/1234567#/", 1234567 is your app ID.
  • "XFF": 'X-Forwarded-For' header value
Note! If you are using our old method (using CTX), you don’t need to replace it with the new one, It’s still supported.
Here is how the post request will look like:
Node.js
curl
await fetch("https://platform.shoffi.app/v1/newMerchant", {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
api_key: "pk_xxxxxx",
shopName: "xxxxxxx.myshopify.com",
appId: "1111111",
XFF:"11.1111.111.111"
})
})
curl -X POST https://platform.shoffi.app/v1/newMerchant
-H 'Content-Type: application/json'
-d '{"api_key":"pk_xxxxxx",
"shopName":"xxxxxxx.myshopify.com",
"appId":"1111111",
"XFF":"11.1111.111.111"}'

Different languages

The code above is an example of a Shoffi POST request. You can use any other language(Ruby, PHP, etc.) to initiate it.
if you have an issue with finding the value of 'X-Forwarded-For' header try looking for it under the request headers. Here are a few examples in different languages:
  • node: ctx.request.header['x-forwarded-for']
  • ruby: request.env["HTTP_X_FORWARDED_FOR"]
  • PHP: $_SERVER["HTTP_X_FORWARDED_FOR"]

Testing the request

You can use your app's test key in order to test it on your test app or staging environment. Once you push your code to production, change the test key to the real one.

Initiating the request

Once the POST request was added, you will need to open a new Development store from your Partner admin and install and open your app. Once our system receives the request for the first time, the integration status will change to 'Completed', and your app will be ready for affiliates to use.

Integration status

You can find the status of your app integration on the "My apps" page. There are three different integration statuses:
  1. 1.
    Initiated
    The connection with the Partner API was successful. Waiting for the POST request.
  2. 2.
    Under review
    POST request detected. We are now reviewing your app. That can take up to 48 hrs. If it's been more than 48 hrs and your app is still under review, Please check the email you signed up to Shoffi with, we sent instructions on what needs to be fixed.
  3. 3.
    Completed
    Your app was approved and is now listed on the Shoffi marketplace.