# Getting Started
An introduction to the Shoffi platform
### What is Shoffi?
Shoffi is an affiliate platform and network for Shopify apps.
#### For App Owners
Shoffi offers a "Plug and Play" affiliate system for your Shopify apps. You can use it to create a partner program for each app, invite and manage affiliate partners, and get discovered by new ones.
### App Owners Guides
Follow our guides to get started on the basics as quickly as possible:
{% content-ref url="/pages/VVBNckbEoAAAeJqfX0gM" %}
[Adding a new app](/for-app-owners/adding-a-new-app)
{% endcontent-ref %}
{% content-ref url="/pages/egxK0aV4F52Gi21TAj9p" %}
[BigQuery integration](/for-app-owners/bigquery-integration)
{% endcontent-ref %}
{% content-ref url="/pages/ZeK5MF0NSJZ0RLQWjTFB" %}
[Managing affiliates](/for-app-owners/managing-affiliates)
{% endcontent-ref %}
{% content-ref url="/pages/SUQBVX6RGxKi81xoUfbT" %}
[Paying affiliates](/for-app-owners/paying-affiliates)
{% endcontent-ref %}
{% content-ref url="/pages/PgbqFku4lf2pc2U6cmkH" %}
[Managing your apps](/for-app-owners/managing-your-apps)
{% endcontent-ref %}
#### For Affiliates
In Shoffi, you can find Shopify apps that offer rewards for promoting them. You can discover apps on the market, review their affiliate program terms, and apply.
Once an app owner approves your request, you get a unique affiliate link and can add referrals manually. Affiliates can be Shopify agencies, freelancers, or content creators who want to monetize their content more effectively.
### Affiliate Guides
Learn how to make the most of your affiliate account on Shoffi:
{% content-ref url="/pages/p9llJN63yMvbSOg6Zbsf" %}
[Connecting to new apps](/for-affiliates/connecting-to-new-apps)
{% endcontent-ref %}
{% content-ref url="/pages/V2n5M1UHlV3bwfvjj4lH" %}
[Referral links](/for-affiliates/referral-links)
{% endcontent-ref %}
{% content-ref url="/pages/HfKkho4bIzCFRC8eAXNn" %}
[Payout requests](/for-affiliates/payout-requests)
{% endcontent-ref %}
{% content-ref url="/pages/4t34L0jZXO9RkVyPadGC" %}
[The affiliate commission](/general/the-affiliate-commission)
{% endcontent-ref %}
# Adding a new app
{% hint style="info" %}
**Good to know:** While you manage multiple affiliate programs from the same dashboard, you set up each one separately. That lets you set different affiliate terms, such as commission rate, for each app.
{% endhint %}
## The new app form
Go to the `My Apps` page and click `Add a new app`. You will be redirected to the new app page.
### App settings
Set your app's settings based on your preferences. You can change them later from your dashboard.
### Affiliate terms
These are the contract details between an app and an affiliate. You can find a detailed explanation in [The affiliate terms](/for-app-owners/the-affiliate-terms#terms-breakdown).
### App details
* **App name:**\
The exact name shown in the App Store.
* **App logo:**
Upload your logo as a `.png` file. We recommend `125x125`.
* **Shopify App Store listing link:**
Example: `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 listed in 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:**
{% hint style="info" %}
**Important!** Shoffi requires API permissions for your app so we can detect installs from referral links and calculate earnings and commission rates correctly.
These permissions give us read-only access. We use it only to **read the information relevant to the Shoffi platform**.
**We don't read any data from before your Shoffi integration**.\
You can find more information about the [Partner API permissions here](https://shopify.dev/api/partner/getting-started#permissions).
{% endhint %}
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, follow [Shopify's guide](https://shopify.dev/api/partner/getting-started#create-an-api-client).
**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 to help them learn and promote the app.
## The app integration process
### Partners API connection
To submit the new app form, you must validate the connection to your Shopify Partners API. This confirms that the details you entered are correct. If a field is wrong or permissions are missing, you will get an error that explains what went wrong.
### Option 1: BigQuery integration
See [BigQuery integration](/for-app-owners/bigquery-integration) for a detailed guide.
When you connect BigQuery in Shoffi, use the **numeric GA4 Property ID** (digits only from GA4 Admin → Property details) — not the Measurement ID that starts with `G-`, and not a Shopify Partners app ID. The **Project ID** and **Property ID** must be a matched pair: the property’s BigQuery export must live in the same Google Cloud project you enter in Shoffi.
If something is slightly off (for example the Property ID), Shoffi’s automatic checks can often detect the correct property from your project and fix it — or show a banner on your Apps page with the exact step to fix.
### Option 2: POST request
When you have those values, you need to send the POST request with the following data:
**`api_key, shopName, appId, XFF`**
#### Variable explanations
* "**api\_key**":\
Your Shoffi post-install key is generated when you add a new app. You can find it by clicking `Edit app` on the `My Apps` page. This is **not** the Shoffi API Key used for the [Shoffi API](/the-shoffi-api/introduction-to-shoffi-api) — that key is created under **Integrations → API Key**.
* "**shopName**":\
The full shop domain currently logged in to the app, for example `newshop.myshopify.com`.
* "**appId**":\
The ID of your Shopify app. To find it, go to your app page in the Partner Dashboard and copy it from the URL. For example, in `https://partners.shopify.com/1111111/apps/1234567#/`, `1234567` is your app ID. A Shopify appId is **digits only** - don't send the Shoffi app id here. If it contains any letters, Shoffi will reject the request with a "wrong appId" error.
* "**XFF**":\
'`X-Forwarded-For`' header value
Here is what the POST request looks like:
{% tabs %}
{% tab title="Node.js" %}
```javascript
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"
})
});
```
{% endtab %}
{% tab title="curl" %}
```bash
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"}'
```
{% endtab %}
{% endtabs %}
#### Different languages
The code above shows a Shoffi POST request.\
You can use any other language, including Ruby or PHP, to send it.
If you are having trouble finding the value of the 'X-Forwarded-For' header, try searching 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 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.
The response includes a `warnings` list that helps you catch mistakes before going live. You'll get a warning if you are still using the **test key**, or if the `XFF` value is wrong - for example missing, a placeholder like `0.0.0.0` or `11.1111.111.111`, the text `unknown`, or an IP sent together with a port. Use the merchant's real `x-forwarded-for` value (IPv4 or IPv6), without a port.
If a problem with your post-install call continues after your app is approved, Shoffi will also show an error on your `My Apps` page describing what to fix. Important: while the post-install call is sending a wrong IP, Shoffi can't match new referrals, so affiliate installs during that time won't be attributed - so it's worth fixing quickly.
#### Initiating the request
Once the POST request is added, you need to **open a new development store** from your Partner Dashboard 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. **Incomplete**
The Partner API connection was successful. We are waiting for the POST request.
2. **Under review**\
POST request detected. We are now reviewing your app. This can take up to 48 hours.\
If it has been more than 48 hours and your app is still under review, check the email address you used to sign up for Shoffi. We may have sent instructions about what needs to be fixed.
3. **Completed**
Your app was approved and is now listed on Shoffi.
# Google Analytics integration
{% hint style="info" %}
**Please Note!**\
This is a complete guide to creating a Google Analytics account for your Shopify app listing and connecting it to Shoffi. If you’ve already set up Google Analytics for your app listing, jump to [#connect-to-shoffi](#connect-to-shoffi "mention").
{% endhint %}
### Jump to
[#setup-google-analytics](#setup-google-analytics "mention")
[#connect-your-shopify-app-listing](#connect-your-shopify-app-listing "mention")
[#connect-to-shoffi](#connect-to-shoffi "mention")
## Set up Google Analytics
### 1. Set Up or Access Your Google Analytics Account
Visit [analytics.google.com](https://analytics.google.com) and sign in using your Google account credentials.
### 2. Navigate to the Admin Section
Click on the gear (cog) icon located at the bottom left to access the Admin panel.
### 3. Initialize a New Account
If you are starting a fresh account, you can skip the initial setup. Otherwise, click the **Create** button and select **Account**.
### 4. Provide an Account Name
Enter a suitable name for your account and then click **Next** to proceed.
### 5. Specify Property Details
Input a name for your property, choose the appropriate timezone and currency, and then click **Next**.
### 6. Enter Business Information
Fill in your business category and size, then click **Next** to continue.
### 7. Define Business Objectives
Select the relevant business objectives that align with your goals and click **Create**.
### 8. Accept Google Analytics Terms of Service
Choose the terms applicable to your region. When ready, accept the terms by clicking the **I Accept** button.
### 9. Set Up Data Collection
Add a data stream to collect data from Shopify for your application. Select the **Web** platform.
### 10. Create a Web Stream
Enter your Shopify app’s URL, assign a name to the stream, and then click **Create and continue**.
{% hint style="warning" %}
**Please Notice!**\
Make sure the "Website URL" is the full URL of your app listing, including the slug (ex. ).
{% endhint %}
### 11. Record the Measurement ID
Take note of the Measurement ID as this will be necessary for integration with Shopify via the Partner portal.
### 12. Obtain the API Secret
On the same page, retrieve the API Secret by clicking on **Measurement Protocol API secret**.
### 13. Generate the API Secret
You may need to review and accept the terms first.
Next, click the **Create** button.
Assign a nickname to the API secret, such as “Shopify App Listing,” and click **Create**.
Ensure you save the secret value (API Secret) for future use.
## Connect your Shopify app listing
### 1. Access the Shopify Portal
Log in at [partners.shopify.com](https://partners.shopify.com).
### 2. Select Your App
From the left-hand menu, choose **Apps**.
Select your specific app.
Navigate to **Distribution** in the left menu.
Click on the **Manage Listing** button.
Now click **Edit** on your primary listing.
### 3. Input Google Analytics Details
Scroll to the **Tracking Information** section and enter your Measurement ID and API Secret in the designated fields. After entering the information, click **Save**.
## Connect to Shoffi
### 1. Configure Custom Definitions
Custom definitions allow you to collect additional data, such as identifying which store is installing your app.
First, click the gear icon to return to the main Admin page.
Next, select **Custom Definitions**.
Click on **Create Custom Dimension**.
Enter `shop_url` in both the **Dimension Name** and **Event Parameter** fields, then click **Save**.
Repeat this process to add another custom dimension called `ga_session_id`.
Once you finish, you should see both custom definitions listed:
### 2. Give read-only access to Shoffi
{% hint style="info" %}
Note!\
The Analytics integration section appears only after you verify your Shopify Partners details.
{% endhint %}
Navigate to your Shoffi `New app` or `Edit app` page.
Click the **Connect Google Analytics** button and select the Google account you used earlier to create your Google Analytics account.
### 3. Approve Access to Shoffi
A pop-up appears and asks you to approve read-only access.
By clicking **Approve**, you grant us permission to read your Google Analytics data.
### 4. Integration Completed
Once the integration is successfully completed, you’ll be redirected back to Shoffi, and your app will be automatically approved.
# BigQuery integration
{% hint style="info" %}
**Please Note!**\
This is a comprehensive guide to setting up a Google Analytics account for your Shopify app listing and connecting it to Shoffi. If you’ve already set up Google Analytics for your app listing, proceed to [#set-up-bigquery](#set-up-bigquery "mention").
{% endhint %}
### Jump to
[#set-up-google-analytics](#set-up-google-analytics "mention")
[#connect-your-shopify-app-listing](#connect-your-shopify-app-listing "mention")
[#set-up-bigquery](#set-up-bigquery "mention")
## Set up Google Analytics
### 1. Set Up or Access Your Google Analytics Account
Visit [analytics.google.com](https://analytics.google.com) and sign in using your Google account credentials.
### 2. Navigate to the Admin Section
Click on the gear (cog) icon located at the bottom left to access the Admin panel.
### 3. Initialize a New Account
If you are starting a fresh account, you can skip the initial setup. Otherwise, click the **Create** button and select **Account**.
### 4. Provide an Account Name
Enter a suitable name for your account and then click **Next** to proceed.
### 5. Specify Property Details
Input a name for your property, choose the appropriate timezone and currency, and then click **Next**.
### 6. Enter Business Information
Fill in your business category and size, then click **Next** to continue.
### 7. Define Business Objectives
Select the relevant business objectives that align with your goals and click **Create**.
### 8. Accept Google Analytics Terms of Service
Choose the terms applicable to your region. When ready, accept the terms by clicking the **I Accept** button.
### 9. Set Up Data Collection
Add a data stream to collect data from Shopify for your application. Select the **Web** platform.
### 10. Create a Web Stream
Enter your Shopify app’s URL, assign a name to the stream, and then click **Create and continue**.
{% hint style="warning" %}
**Please Notice!**\
Make sure the "Website URL" is the full URL of your app listing, including the slug (ex. ).
{% endhint %}
### 11. Record the Measurement ID
Take note of the Measurement ID as this will be necessary for integration with Shopify via the Partner portal.
### 12. Obtain the API Secret
On the same page, retrieve the API Secret by clicking on **Measurement Protocol API secret**.
### 13. Generate the API Secret
You may need to review and accept the terms first.
Next, click the **Create** button.
Assign a nickname to the API secret, such as “Shopify App Listing,” and click **Create**.
Ensure you save the secret value (API Secret) for future use.
## Connect your Shopify app listing
### 1. Access the Shopify Portal
Log in at [partners.shopify.com](https://partners.shopify.com).
### 2. Select Your App
From the left-hand menu, choose **Apps**.
Select your specific app.
Navigate to **Distribution** in the left menu.
Click on the **Manage Listing** button.
Now click **Edit** on your primary listing.
### 3. Input Google Analytics Details
Scroll to the **Tracking Information** section and enter your Measurement ID and API Secret in the designated fields. After entering the information, click **Save**.
## Set up BigQuery
### **1. Provision BigQuery in Google Cloud**
**1. Sign in**
Visit the [**Google Cloud Console**](https://console.cloud.google.com/) and log in (or create a new account).
**2. Create a GCP project**
1\. Click **Select a project ▸ New Project** at the top.\
2\. Name it something memorable (e.g., `myapp-shoffi-integration`).
### **2. Link GA4 to BigQuery**
1. In **GA4 ▸ Admin**, choose **BigQuery links**.
2. Click "Link" and select the project you just created.
3. Enable **Daily** export.
4. Confirm the link appears in the BigQuery links table.
### **3. Authorise Shoffi to read your dataset**
1. Open [**IAM & Admin**](https://console.cloud.google.com/iam-admin/iam) and ensure the correct project is selected in the top-left dropdown.
2. Click **Grant access**.
3. Enter Shoffi's service account email:\
`shoffi-bigquery-master@shoffi.iam.gserviceaccount.com`
4. Assign these roles, under the "BigQuery" section:
* **BigQuery Data Viewer** – permits read access.
* **BigQuery Job User** – permits query jobs.
{% hint style="info" %}
**Tip:**\
If you hit a policy error, the simplest fix is:\
• Go to [**Cloud Organization Policies**](https://console.cloud.google.com/iam-admin/orgpolicies/list).\
• Locate **constraints/iam.allowedPolicyMemberDomains**.\
• Click **Manage Policy ▸ Add Rule ▸ Allow All**.
{% endhint %}
### 4. Plug BigQuery into Shoffi
**1. Enter the GA property ID**
Go to `Admin` → `Property` → `Property details` and copy the property ID from the top right. It is **digits only** — do not enter the Measurement ID that starts with `G-`, and do not enter a Shopify Partners app ID.
Use the same GA4 property whose Measurement ID you put in Shopify Partners → Tracking Information (the one that receives your App Store listing page views), not a property that only tracks your website or app admin.
**2. Enter the BigQuery project ID**
You can find it at the top of the Google Cloud dashboard or on the `BigQuery links` page in Google Analytics. The Project ID and Property ID must match: the property’s BigQuery link must export into this same Google Cloud project.
Each Google Cloud project can be connected to **one Shoffi account only** — this is what keeps every company’s analytics data separate. If you enter a project that is already connected to a different account, validation stops and asks you to check the Project ID. You can still use the same project for several of your own apps. If the project really is yours and you see this message, contact Shoffi support.
**3. Submit the details.**
{% hint style="warning" %}
*Dataset missing?* Google can take **up to 24 hours** to create the first partition. Come back later and pick it up once it appears.
{% endhint %}
{% hint style="info" %}
If validation fails, Shoffi shows a banner on your Apps page with the specific issue (for example wrong Property ID format, missing permissions, or the property tracking your own site instead of the App Store listing). Follow the steps in the banner — Shoffi also rechecks automatically and can sometimes correct a slightly wrong Property ID once your export is ready.
{% endhint %}
# The affiliate terms
The affiliate terms are the default contract between an app and an affiliate.\
Once an affiliate makes a new referral, commissions are based on those terms.
You can always change the app's default terms or [change them for an individual affiliate](#editing-the-affiliate-terms).
## Terms breakdown
* **Commission Rate**:
The percentage you are willing to pay an affiliate for every transaction made by a store they referred. You can read more about [the affiliate commission](/general/the-affiliate-commission).
* **Commission Rate Period Limit:**\
The number of months an affiliate earns commissions from transactions made by the referred store. If there is no limit, the affiliate earns commissions while the referral is active.
* **CPI:**
Cost per install. The amount an affiliate is rewarded for each successful app install. You can set the amount to `0` if you do not want to pay per install.
* **Minimum Withdrawal:**
The minimum amount an affiliate must earn before they can request a withdrawal. This amount is in USD.
* **Auto Approval:**
If enabled, every affiliate who joins your affiliate program is approved automatically — including market requests and affiliates who use a group invite link. If disabled, you must approve each request manually on the `Affiliates` page, no matter how the affiliate applied.
* **Recurring charges only:**\
If enabled, affiliates receive a share of revenue only from recurring payments, not from one-time fees.
* **Require invoice:**\
If enabled, affiliates must attach an invoice link to every payout request for this app before they can submit it. The invoice link they provide appears next to their payout in the `Payouts` page so you can review it before paying.
## Editing the affiliate terms
You can edit your app's main affiliate terms when [editing your app](/for-app-owners/managing-your-apps).
You can also change terms for a specific affiliate by [editing affiliate terms](/for-app-owners/managing-affiliates#editing-affiliate-terms).
# Affiliate groups
Manage your affiliates more effectively by organizing them into groups. This lets you invite new affiliates or manually move existing ones to a specific group.
This way, you can offer tailored terms to particular affiliates. For instance, you might set up a "VIP" group for affiliates who have proven themselves and would like to reward them with better terms, such as a higher CPI or commission rate.
### The default group
Once you add a new app to Shoffi, a `Default` affiliate group for that app is created automatically. The default group terms match the terms you added to the app. You can change them from the `My Apps` page by editing the app.
### Adding and managing affiliate groups
Navigate to the `Affiliates` page and then to the `Groups` page in the side navbar.
You can add new groups for each app or edit existing ones. Each group will have its unique invite link so that you can invite affiliates directly to this group.
The **group name is internal only** and is not visible to affiliates. Affiliates see only the terms, such as commission and CPI.
{% hint style="warning" %}
**Please Note!**
* Changes to group terms will not affect previous referrals; only new referrals will be subjected to the new terms.
* Once the group affiliate terms are changed, all the affiliates will be notified of the new terms.
{% endhint %}
### Group invite link
Each group has a unique invite link that you can use to invite affiliates directly to that group. You can read more in [Invite affiliates](/for-app-owners/invite-affiliates).
If [Auto Approval](/for-app-owners/the-affiliate-terms) is disabled for the app, affiliates who join through a group invite link still need your approval on the `Affiliates` page before they can promote the app.
### Moving an affiliate to a different group
To change an existing affiliate's group, go to the `Affiliates` page and click the affiliate name. In the `Actions` dropdown, choose `Edit affiliate group`.
These terms apply only to new transactions made by stores referred by the affiliate.
{% hint style="warning" %}
**Please Note!**
* Changes to the affiliate group will not affect previous referrals; only new referrals will be subjected to the new terms.
* Once the affiliate group is changed, the affiliate will be notified of the new terms.
{% endhint %}
### The custom group badge
Regardless of group assignments, you can still set custom terms for each affiliate using the API or by [changing them manually](/for-app-owners/managing-affiliates#editing-affiliate-terms).
If an affiliate has individual terms, a `Custom` badge appears. This means the affiliate is not using group terms.
# Managing affiliates
### Adding affiliates
After getting your app listed, you will want affiliate partners to join your affiliate program.\
This can happen through four main channels:
* **Affiliate requests**\
Affiliates on Shoffi can find your app on the `Market` page and request to connect.
* **Affiliate invites**\
You can invite affiliates outside Shoffi to join your affiliate program with a unique [invite link to any affiliate group](/for-app-owners/affiliate-groups#group-invite-link). If Auto Approval is off, these joins still need your approval.
* **Affiliates Imports**
You can import affiliates from different platforms into Shoffi. We automatically add them to your program and create their affiliate links.
To give imported affiliates the terms of one of your [affiliate groups](/for-app-owners/affiliate-groups) instead of your default terms, add a `Group Invite Link` column to the affiliates file and paste that group's invite link (or its group ID) on the rows that belong to it. Those affiliates join the group and their imported referrals use the group's terms. Rows you leave empty, or a link that does not belong to this app, get your default terms.
* **Shoffi API**\
You can use the Shoffi API to add affiliates directly to your program with a POST request. [Learn more here](/the-shoffi-api/create-new-affiliate).
### Affiliate requests
{% hint style="info" %}
**Good to know:** Depending on your preference, you can auto-approve affiliate requests or review each one manually. This applies to both market requests and invite-link joins. Affiliates you add yourself through import or the Shoffi API are added to your program directly.
{% endhint %}
Affiliate requests appear on the `Affiliates` page. If you do not auto-approve requests, you must approve each one manually.
### Affiliate information
To learn more about your affiliates, click a name on the `Affiliates` page (or on a group page). This opens the affiliate connection page, where you can see details and perform actions such as editing affiliate terms or removing an affiliate.
### Editing affiliate terms
{% hint style="warning" %}
**Please Note!** The new terms will apply only to new referrals, not to the existing ones.
{% endhint %}
If you want to offer special affiliate terms to specific affiliates, it is possible to revise their affiliate terms. This is possible only after the affiliate joins your affiliate program.
On the `Affiliates` page, find the affiliate whose terms you want to edit for a specific app, then click their name to open the affiliate connection page.
Under `Actions`, choose `Edit affiliate terms`.
### Adding a bonus reward
You can manually reward an affiliate with a one-time bonus commission from the affiliate details page.
{% stepper %}
{% step %}
Open the affiliate details
{% endstep %}
{% step %}
Add the bonus reward
Click `Actions`, then select `Add bonus reward`.
{% endstep %}
{% step %}
Fill in the bonus details
* **Reward amount**: enter the bonus amount (any amount).
* **Internal note (optional):** internal note for your own use.
{% endstep %}
{% endstepper %}
### Removing affiliates
{% hint style="danger" %}
**Please note!** Removing an affiliate will result in the deletion of all their referral data. The affiliate will also receive an immediate notification of their removal.
{% endhint %}
On the `Affiliates` page, find the affiliate you want to remove for a specific app affiliate program, then click their name to open the affiliate connection page.
Under `Actions`, choose `Remove affiliate`.
# Invite affiliates
{% hint style="warning" %}
**Please note!** This page is about the links app owners use to invite affiliates to their affiliate program, not the links affiliates use to promote apps to merchants.
{% endhint %}
### The affiliate invite link
The affiliate invite link lets you invite people to join your affiliate program on Shoffi without searching for your app in the marketplace and requesting access.
Each affiliate group you create has its own unique link, which adds the affiliate directly to that group. The default group gives affiliates your app's standard terms. You can read more about [affiliate groups](/for-app-owners/affiliate-groups).
The link redirects to a sign-up page that shows your app's logo, name, and affiliate terms. After users complete sign-up, they are redirected automatically to their `Connections` page.
### Approval
Whether an affiliate who uses an invite link is approved right away depends on your app's [Auto Approval](/for-app-owners/the-affiliate-terms) setting:
* If **Auto Approval** is enabled, affiliates who join with an invite link are approved automatically and can copy their unique affiliate link right away.
* If **Auto Approval** is disabled, invite-link joins stay as requests on your `Affiliates` page until you approve them, the same as market requests.
### Where to find the link
You can find it under `Affiliates` in the `Groups` tab.
# Paying affiliates
## Getting payout requests
Once an affiliate reaches the minimum withdrawal amount for a specific app, they can request a payout. You will find the payout requests under the `Payouts` page.
## Paying affiliates
When an affiliate requests payment, you have a 60-day window to deliver the requested amount directly to their PayPal account unless you have specified otherwise in your custom terms and conditions.
The affiliate’s default PayPal email and any alternative payment details they added are listed in the payments table on the `Payouts` page. Don’t forget to mark the payment as paid after you complete the transaction.
If you enabled **Require invoice** in the app's [affiliate terms](/for-app-owners/the-affiliate-terms), the affiliate must attach an invoice link when requesting a payout. That invoice link is shown with the payout on the `Payouts` page so you can review it before sending the payment.
### Alternative payment methods
By default, affiliate payouts are paid through PayPal.
Affiliates can add alternative payment details to their Shoffi account, such as a bank account, Wise account, or another payment method. This is only used for reference and does not automatically change the payout method.
If an affiliate wants to be paid through an alternative payment method, they must contact you directly and ask for it explicitly.
You can choose whether to approve the request. If you approve it, make sure to use the alternative payment details provided by the affiliate when completing the payout.
If no alternative method was explicitly agreed with the affiliate, the payout should be sent to the affiliate’s PayPal account.
After completing the payment, mark the payout as paid in Shoffi.
## PayPal Mass Pay
If you want to issue multiple payouts in a batch, you can use the mass pay feature instead of paying each one individually.
Download the mass pay CSV file from your `Payouts` tab with `Actions` → `Download mass payments CSV`, then upload and pay in PayPal using [PayPal Mass Pay](https://www.paypal.com/us/cshelp/article/how-do-i-send-a-payouts-mass-payment-help252).
# Managing your apps
## Editing an existing app
Find the app you want to edit on the `My Apps` page. Under `Actions`, click `Edit app`.
From that page, you can change affiliate terms, update the app logo, and add app resources. If you need to change a disabled field, contact support.
## Refreshing your Partners API client access token
If you created a new Partners API client in your Shopify Partner account, or your current token stopped working, you can replace it yourself:
1. Open the app on the `My Apps` page and click `Edit app`.
2. Scroll to `Shopify partner details` and click `Refresh token`.
3. Paste your new Partners API client access token. It starts with `prtapi_`, and the API client needs the `View financials` and `Manage apps` permissions.
4. Click `Validate connection`. Shoffi checks the token against Shopify right away.
5. Once it's validated, click `Save` in the bar at the top of the page.
{% hint style="info" %}
Your `Partner ID` and `App ID` stay locked. If either of those changed, contact support.
{% endhint %}
If validation fails, double-check that you copied the whole token and that the API client has both required permissions. Shoffi keeps using your previous token until a new one is validated and saved.
{% hint style="info" %}
For security, the token is only ever shown masked — `prtapi_`, then `xxxx…`, then its last 4 characters — so you can tell which token is saved without exposing it. It can never be read back in full, so when you refresh it, paste the whole new token.
{% endhint %}
{% hint style="warning" %}
**Important:** If you change your app's affiliate terms, the new terms apply only to new referrals from that point forward. Previous referrals keep the terms that were active when the referral started.
{% endhint %}
## Integration errors on My Apps
If Shoffi detects a problem that blocks matching new referrals (for example expired Shopify Partners credentials, or BigQuery access revoked), a warning banner appears on your `My Apps` page with steps to fix it. Open the app settings and fix the issue as soon as you can so new referrals keep matching.
The same banner appears if you subscribe again after your account was deactivated, because Shoffi no longer holds your Partners API client access token. Re-enter it under the app's Shopify partner details, validate the connection and save. See [Frozen and Deactivated accounts](/subscriptions/frozen-and-deactivated-accounts#coming-back-after-deactivation).
## Deleting an app
To delete an existing app, please get in touch with our support.
# Managing your team
### Overview
The Team feature lets you invite people from your organization or external collaborators to your Shoffi account. You can give them specific permissions to manage and access account data.
### Permission types
There are two types of permissions that can be assigned to team members:
#### Viewer
* **Description**: The Viewer role allows users to explore account data and access detailed information related to affiliates, referrals, and payouts.
* **Restrictions**: Viewers do not have permission to perform any actions within the account. This includes importing and exporting affiliate lists, so the Import and Export buttons on the Affiliates page are unavailable to them.
* **Ideal For**: Users focused on marketing and analytics.
#### Editor
* **Description**: The Editor role grants users full visibility of account data, including affiliates, referrals, and payouts.
* **Capabilities**: Editors can perform all operational actions available in the application, except for inviting new team members and modifying the subscription plan.
* **Ideal For**: Senior team members who require comprehensive access to manage daily operations.
### Managing team members
#### Adding a team member
1. Navigate to the **Team** page.
2. Click the **"Invite team member"** button.
3. Enter the required information for the new team member.
4. Assign the appropriate permission type (Viewer or Editor).
5. Send the invitation.
The invitation is sent to the email address you entered, and only that address can accept it. The person who accepts joins with the permission you chose, so if you want to change it, remove the invitation and send a new one. Each invitation link works once — if it has already been used, or you removed the member, the link stops working and you'll need to invite them again.
**Invitations expire after 7 days.** If someone doesn't accept in time, the link stops working and they'll see a message saying it has expired — just remove the pending invitation and send a new one. Treat the invitation link like a password: anyone who opens it can join your account as that person, so avoid forwarding it or pasting it into shared channels.
#### Removing a team member
1. Navigate to the **Team** page.
2. Locate the member to be removed in the team members table.
3. Click the **"Remove member"** button next to the member's name.
### Team member limits
If the **"Invite team member"** button is disabled, this indicates that you have reached the maximum number of team members allowed for your current plan. To resolve this, you can either:
* Upgrade your subscription plan to increase the team member limit.
* Remove an existing team member to free up space for a new one.
# Integrations (Webhooks & API Key)
### Overview
The **Integrations** page has two tabs:
* **Webhook** — receive real-time notifications about important events in your app by sending event data to any publicly accessible URL.
* **API Key** — create and manage the Shoffi API Key used to authenticate calls to the [Shoffi API](/the-shoffi-api/introduction-to-shoffi-api).
***
## Webhook tab
### Creating a new integration
1. **Navigate to the Integrations page**
* In your Shoffi dashboard, click **Integrations** in the left-hand menu.
* Open the **Webhook** tab.
* A list of existing integrations is displayed, each with details such as the integration name, linked app, notifications count, and actions (**Edit**, **Delete**).
2. **Add a new integration**
* Click **Add Integration** at the top-right corner of the Integrations page.
* A modal titled **New Integration** will appear.
3. **Fill in the integration details**
* **Integration Name**: A name that helps you identify this webhook (e.g., “Subscription-Only Events”).
* **Webhook URL**: A publicly accessible URL where Shoffi will send the webhook events (e.g., `https://example.com/webhook`).
* **App**: The app this webhook integration will be associated with (e.g., “RTL Master,” “RTL King: Hebrew,” etc.).
* **Types**: Check which event types you want to receive (e.g., `affiliates/join_requested`, `affiliates/joined`, `affiliates/referral`, etc.).
4. **Validate your webhook**
* Click **Validate Webhook**. Shoffi will send a sample request to the provided URL.
* If Shoffi receives a `2xx` response, validation succeeds, and you can proceed.
* The **Save** button is enabled only after successful validation.
5. **Save the integration**
* After validation is successful, click **Save** to finalize the integration.
* The new integration appears in the **Integrations** list.
***
### How webhooks work
When an event occurs, Shoffi sends an HTTP POST request to your specified **Webhook URL**. Each request includes:
* `Type`: A string identifying the event type (e.g., `JOIN_REQUESTED`, `JOINED`, `REFERRAL`, etc.).
* Relevant data fields: A JSON payload with details about the event, such as affiliate name, email, and date/time.
***
### Event definitions
* **affiliates/join\_requested**\
Occurs when someone applies to become an affiliate. This event is sent only if your app requires manual approval.
* **affiliates/joined**\
Occurs when an affiliate is officially approved or confirmed, and they can now start promoting.
* **affiliates/referral**\
Occurs when an affiliate successfully refers someone to your store or product. This event carries information about the referral.
* **affiliates/referral\_requested**\
Occurs when an affiliate manually requests credit for a specific referral.
* **affiliates/payment\_requested**\
Occurs when an affiliate requests a payout for their accrued earnings.
***
### Example payloads
Below are three sample webhook payloads. All other event types use a similar structure, but with different fields as necessary.
#### 1. JOIN\_REQUESTED
```json
{
"App Name": "Demo Shopify App",
"Affiliate Name": "JohnDoe",
"affiliateEmail": "john@example.com",
"affiliatePromotingAgenda": ["Blog"],
"Type": "JOIN_REQUESTED"
}
```
#### 2. JOINED
```json
{
"App Name": "Demo Shopify App",
"Affiliate Name": "JaneSmith",
"affiliateEmail": "jane@example.com",
"Type": "JOINED"
}
```
#### 3. REFERRAL
```json
{
"App Name": "Demo Shopify App",
"Affiliate Name": "ReferralUser",
"affiliateEmail": "referraluser@example.com",
"shopName": "demostore.myshopify.com",
"Type": "REFERRAL"
}
```
***
### Receiving and responding to webhook requests
1. **Set up a server endpoint**
* Ensure the **Webhook URL** is an endpoint in your system that can accept and parse HTTP POST requests.
2. **Parse the payload**
* Check the `Type` field to determine which event occurred.
* Access other fields for event-specific information.
3. **Return a `2xx` response**
* Return `200 OK` (or another `2xx` status) to indicate that you have successfully received the webhook.
***
### Event types
All currently available event types are:
* `affiliates/join_requested`
* `affiliates/joined`
* `affiliates/referral`
* `affiliates/referral_requested`
* `affiliates/payment_requested`
Each event’s JSON structure follows a pattern similar to the examples shown.
### Connecting to third-party tools
You can integrate Shoffi’s webhooks with external platforms like **Zapier**, **HubSpot**, and more:
* **Zapier**
1. Create a new Zap and select **Webhooks by Zapier** as your trigger app.
2. Choose **Catch Hook** as the trigger event.
3. Copy the webhook URL Zapier provides and paste it into the **Webhook URL** field when creating or editing your Shoffi integration.
4. Select the event types you want to receive and validate.
5. Once set up, you can use the incoming webhook data within Zapier to connect to other apps.
* **HubSpot**
1. In HubSpot, create a workflow or a custom integration that accepts inbound webhooks.
2. Provide HubSpot’s webhook endpoint URL when setting up your Shoffi integration.
3. Validate the webhook and save the integration.
4. HubSpot will then receive real-time data from Shoffi, allowing you to automate processes or update contacts based on affiliate events.
In the same manner, any other tool that can accept inbound webhooks can be integrated by supplying the relevant endpoint URL in your Shoffi integration settings.
***
## API Key tab
Use the **API Key** tab to create a Shoffi API Key for each of your apps. This key authenticates requests to the [Shoffi API](/the-shoffi-api/introduction-to-shoffi-api). It is **not** the key used for the post-install request under `My Apps` → `Edit app`.
The Shoffi API is available on the Pro and Enterprise plans, so creating a key requires one of those plans.
### Create a key
1. Open **Integrations** → **API Key**.
2. Find the app in the list and click **Create key**.
3. Confirm, then **copy the key immediately**. For security, the full key is shown only once.
4. Store the key somewhere safe. Anyone with it can call the Shoffi API for that app.
### Rotate or revoke a key
* **Rotate** creates a new key and immediately invalidates the previous one. Update any integrations that still use the old key.
* **Revoke** deletes the key with no replacement. API calls using that key stop working until you create a new one.
The table shows a masked version of the current key (for example `sk_1a2b...9f8e`), when it was created, and when it was last used.
# Shoffi Metrics (Beta)
Shoffi Metrics helps you understand how your app is performing by showing key business metrics like MRR, churn, LTV, and revenue breakdowns.
***
### How to enable Shoffi Metrics
#### If you have at least one integrated app
1. Open **Metrics**.
2. Click **Opt-in Shoffi Metrics**.
3. Wait a few minutes/hours while we process it.
4. When it’s ready, you will be notified by email and in the platform.
#### If you have no integrated apps
Shoffi Metrics requires at least one app fully integrated with Shoffi.
Go to **My Apps**, finish integrating an app, then come back to **Metrics** to opt in.
### What you will see in Shoffi Metrics
#### Summary cards
Shoffi Metrics shows key metrics at the top:
* **Gross earnings**\
Total earnings in the selected time range.
* **MRR (Monthly Recurring Revenue)**\
Your recurring revenue from subscriptions.
* **ARR (Annual Recurring Revenue)**\
Your recurring revenue annualized.
* **Usage & One-Time**\
Revenue from usage-based charges and one-time purchases.
* **Active Subscribers**\
How many subscribers are currently active.
* **ARPU (Average Revenue Per User)**\
Average recurring revenue per active subscriber.
* **LTV (Lifetime Value)**\
Estimated customer lifetime value based on your recent data.
* **Churn**\
Subscriber churn rate in the selected time range.
#### Revenue charts
The Revenue section helps you spot trends over time, such as:
* **Gross Earning trend**
* **MRR trend**
#### Filters
You can filter the dashboard to focus on what you need, for example:
* **App selector** (choose which app to view)
* **Date range** (example: last 30 days)
***
### Tooltips and definitions
If you want more detail about any number or chart, hover over it. Tooltips explain what the metric means and how it is calculated.
### Troubleshooting
#### I don’t see data
* Confirm your app integration status is **Completed**.
* Make sure you’re viewing the right app in the app selector.
# Choosing/Upgrading a plan
## How to choose a subscription plan
Go to the `Settings` tab and scroll to the bottom. You will find the `Subscription` section, where you can see your active plan and a `Change plan` button. Click it to open the subscription page and choose a new plan.
On the subscription page, you will see all the available plans and descriptions. Use the "Subscribe" button to upgrade your subscription to your preferred plan.
## Available plans
For the latest details and prices, visit our [pricing page](https://shoffi.app/pricing/).
# Plan limits
## Earning limit
### What is "Earning limit"?
The revenue your app generates over a 30-day period **only from affiliate partners** is your earnings from affiliates.
For example, if you had ten referrals on Shoffi in the last 30 days and each generated `$10`, your "Earnings from affiliates" for that month would be `$100`.
The limit for those earnings is different for each plan.
### Exceeding the earning limit of your plan
Once the earning limit of your current subscription plan is reached, Shoffi notifies you and requires you to upgrade within 14 days. If you do not upgrade in time, your [account is frozen](/subscriptions/frozen-and-deactivated-accounts#frozen-account) until you upgrade.
## Integrated apps
Each Shoffi plan has a different limit for how many Shopify apps you can integrate with your account.
Each app's affiliate program, affiliates, and referrals can be managed separately.
# Changing billing details
## How to change your billing info
If you want to change billing or payment details, such as your address, credit card, or VAT number, you can do that with the `Edit billing info` link.
Go to `Settings` → `Change Plan`, then use the button under your current plan to view and edit your details.
# Downgrade and cancellation
### Account cancellation
{% hint style="danger" %}
**Be careful!**\
When you cancel your account, all your affiliates will be notified and can request to withdraw their profits, even if they didn’t reach the minimum withdrawal.\
You will still be able to log in to Shoffi to follow the payment requests and fulfill them.
If you want to use Shoffi again, you will need to subscribe and re-approve your apps. Shoffi also stops keeping your Partners API client access token when your account is canceled, so you will be asked to enter it again for each app. See [Frozen and Deactivated accounts](/subscriptions/frozen-and-deactivated-accounts#coming-back-after-deactivation).
{% endhint %}
You can cancel your account anytime by clicking on `account cancellation` at the bottom of the subscription page. You can cancel your account at any time by clicking `Account cancellation` at the bottom of the subscription page.
Your subscription is canceled immediately.
### Downgrading your plan
If you want to downgrade your current plan, please [contact our support](https://shoffi.app/contact-support/).
When downgrading your plan, we need to make sure you do not have too many integrated apps. If you do, we will ask which ones you want to keep.
# Frozen and Deactivated accounts
## Frozen account
### How an account becomes frozen
Your account becomes frozen if you exceed your [plan earning limit](/subscriptions/plan-limits#earning-limit) and do not upgrade your subscription within 14 days.
### What happens when my account is frozen?
Once your account is frozen:
✅ Active referrals keep being tracked\
✅ Existing affiliates will stay connected\
❌ New affiliates can't join your affiliate program\
❌ You won't be able to edit your apps\
❌ Your apps will be removed from the market\
❌ Your affiliates won't be able to copy and use their affiliate link\
❌ Your affiliates won't be able to add manual referrals\
❌ Existing affiliates will see your apps under a "Frozen" status
## Deactivated account
### How an account becomes deactivated
Your account becomes deactivated if you cancel it, or if your payment to Shoffi fails and is not fixed within 14 days of the first warning.
### What happens when my account is deactivated?
Once your account is deactivated:
✅ You will still have access to your Shoffi dashboard\
❌ New affiliates can't join your affiliate program using the invite link\
❌ Your affiliates will be notified that your apps are no longer active\
❌ Your apps will be removed from the market\
❌ Your affiliates won't be able to copy and use their affiliate link\
❌ Your affiliates won't be able to add manual referrals\
❌ Existing affiliates will see your app under a "Deactivated" status
If any of your affiliates still have a balance to withdraw, they can still request payment. Your `Payments` tab remains accessible so you can settle outstanding payouts and review affiliate approvals.
### What happens to my Shopify Partners access token?
Because Shoffi no longer needs to read your Shopify Partners data once your account is deactivated, we stop keeping your Partners API client access token. Nothing changes on your Shopify Partner account itself — your token stays valid there, Shoffi simply no longer holds a copy of it.
### Coming back after deactivation
If you subscribe again, your apps return to review and Shoffi will ask you to enter your Partners API client access token again. Open the app settings, re-enter the token under the Shopify partner details section, validate the connection and save. Referral tracking resumes once your app is approved again.
# Introduction to Shoffi API
{% hint style="info" %}
The Shoffi API is available for the Pro and Enterprise plans. Learn more on the [Shoffi Pricing](https://shoffi.app/pricing/) page.
{% endhint %}
## Endpoint URL
The Shoffi API is constructed according to REST principles, making it easy for authenticated users to interact with any of our URIs using the appropriate HTTP request method. To ensure the highest level of security, we enforce TLS encryption by requiring that all requests are sent via HTTPS.
```
https://platform.shoffi.app/API/
```
## Authentication
To ensure the security and integrity of our API, all requests to the Shoffi API require authentication. To authenticate, you must include your **Shoffi API Key** and your app's `appId`.
### Your Shoffi API Key
Every app can have its own Shoffi API Key. You must use the `apiKey` and `appId` fields in the body of your API calls to Shoffi.
This key is **not** the same as the key shown under `My Apps` → `Edit app`. That key is only for the post-install request. For the API:
1. Open **Integrations** in the left-hand menu of your Shoffi dashboard.
2. Select the **API Key** tab.
3. Click **Create key** for the app you want to use.
4. Copy the key immediately — for security, it is shown only once.
If you lose the key, revoke it and create a new one.
### Additional information
#### API affiliate accounts
For every affiliate you create using the API, Shoffi opens an affiliate account on our platform. If an affiliate wants to log in to Shoffi, they can use the [Reset password](https://platform.shoffi.app/resetpassword) page with their email address and then log in to view their information.
Affiliates won’t get emails from Shoffi until they log in and complete the signup in the Shoffi platform.
#### Plan limits
The API feature is available on specific subscription plans, with different call limits per plan. For more details, visit the [pricing page](https://shoffi.app/pricing/).
#### Use cases
Get inspired and learn more about using the Shoffi API in [this blog post](https://shoffi.app/blog/leveraging-the-shoffi-api-intro-and-best-practices/).
# Get All Affiliates
## Get all affiliates for an app
`GET` `https://platform.shoffi.app/API/affiliate/getAll`
#### Request Body
| Name | Type | Description |
| ---------------------------------------- | ------- | -------------------------------------------- |
| apiKey\* | String | Your Shoffi API Key (Integrations → API Key) |
| appId\* | Integer | Your app ID |
{% tabs %}
{% tab title="200: OK " %}
```json
[
{
"affiliateDetails": {
"email": "tobias@lutke.com",
"firstName": "Tobias",
"lastName": "Lütke",
"nickName": "tobi"
}
},
{
"affiliateDetails": {
"email": "harley@finkelstein.com",
"firstName": "Harley",
"lastName": "Finkelstein",
"nickName": "President"
}
}
]
```
{% endtab %}
{% tab title="400: Bad Request " %}
```javascript
{
"status": 400,
"message": "Error details"
}
```
{% endtab %}
{% endtabs %}
```
curl -X POST \
https://platform.shoffi.app/API/affiliate/getAll \
-H 'Content-Type: application/json' \
-d '{
"apiKey": "YourKey",
"appId": 00000000
}'
```
## Response example
```json
200 OK
Content-Type: application/json
```
```json
[
{
"affiliateDetails": {
"email": "tobias@lutke.com",
"firstName": "Tobias",
"lastName": "Lütke",
"nickName": "tobi"
}
},
{
"affiliateDetails": {
"email": "harley@finkelstein.com",
"firstName": "Harley",
"lastName": "Finkelstein",
"nickName": "President"
}
}
]
```
# Get Affiliate Info
## Get all information about a specific affiliate
`GET` `https://platform.shoffi.app/API/affiliate/getInfo`
#### Request Body
| Name | Type | Description |
| ---------------------------------------- | ------- | -------------------------------------------- |
| apiKey\* | String | Your Shoffi API Key (Integrations → API Key) |
| appId\* | Integer | Your app ID |
| email\* | String | The affiliate email address |
{% tabs %}
{% tab title="200: OK " %}
```json
{
"affiliateDetails": {
"email": "tobias@lutke.com",
"firstName": "Tobias",
"lastName": "Lütke",
"nickName": "tobi"
},
"affiliateTerms": {
"revenueShare": 30,
"cpi": 10,
"limitPeriod": 24,
"minWithdrawal": 50
},
"affiliatePerformance": {
"appProfit": 1000,
"affiliateProfit": 300,
"paidToAffiliate": 100,
"linkViews": 72
},
"affiliateLink": "https://platform.shoffi.app/r/rl_xxxxxxxx",
"referralCount": 10
}
```
{% endtab %}
{% tab title="400: Bad Request " %}
```javascript
{
"status": 400,
"message": "Error details"
}
```
{% endtab %}
{% endtabs %}
```
curl -X POST \
https://platform.shoffi.app/API/affiliate/getInfo \
-H 'Content-Type: application/json' \
-d '{
"apiKey": "YourKey",
"appId": 00000000,
"email": "tobias@lutke.com"
}'
```
## Response example
```json
200 OK
Content-Type: application/json
```
```json
{
"affiliateDetails": {
"email": "tobias@lutke.com",
"firstName": "Tobias",
"lastName": "Lütke",
"nickName": "tobi"
},
"affiliateTerms": {
"revenueShare": 30,
"cpi": 10,
"limitPeriod": 24,
"minWithdrawal": 50,
"recurringChargeOnly": true
},
"affiliatePerformance": {
"appProfit": 1000,
"affiliateProfit": 300,
"paidToAffiliate": 100,
"linkViews": 72
},
"affiliateLink": "https://platform.shoffi.app/r/rl_xxxxxxxx",
"referralCount": 10
}
```
# Create New Affiliate
## Create a new affiliate and get its affiliate link
`POST` `https://platform.shoffi.app/API/affiliate/create`
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------- | --------------------------------------------------------------- |
| apiKey\* | String | Your Shoffi API Key (Integrations → API Key) |
| appId\* | Integer | Your app ID |
| affiliateDetails\* | Object | Affiliate account details |
| groupId | Integer | Affiliate group ID. If sent, Shoffi applies the group terms. |
| affiliateTerms | Object | Affiliate contract terms. Used only when `groupId` is not sent. |
{% hint style="info" %}
Shoffi applies terms in this order:
1. `groupId`
2. `affiliateTerms`
3. Your app default group
If you send both `groupId` and `affiliateTerms`, `groupId` takes priority.
{% endhint %}
{% tabs %}
{% tab title="200: OK " %}
```json
{
"affiliateDetails": {
"email": "tobias@lutke.com",
"firstName": "Tobias",
"lastName": "Lütke",
"nickName": "tobi"
},
"affiliateTerms": {
"revenueShare": 30,
"cpi": 10,
"limitPeriod": 24,
"minWithdrawal": 50,
"recurringChargeOnly": true,
"isNetAmount": false
},
"affiliateLink": "https://platform.shoffi.app/r/rl_xxxxxxxx"
}
```
{% endtab %}
{% tab title="400: Bad Request " %}
```javascript
{
"status": 400,
"message": "Error details"
}
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
**Please Note!**\
If the email you send in the POST request is already associated with an affiliate account in Shoffi, we will not create a new account.\
We will update the existing one with a new connection to your app with the group terms or affiliate terms you sent. You will still get a "200" response with the relevant data.
{% endhint %}
### Example request with custom terms
```bash
curl -X POST \
https://platform.shoffi.app/API/affiliate/create \
-H 'Content-Type: application/json' \
-d '{
"apiKey": "YourKey",
"appId": 00000000,
"affiliateDetails": {
"email": "tobias@lutke.com",
"firstName": "Tobias",
"lastName": "Lütke",
"nickName": "tobi"
},
"affiliateTerms": {
"revenueShare": 30,
"cpi": 10,
"limitPeriod": 24,
"minWithdrawal": 50,
"recurringChargeOnly": true,
"isNetAmount": false
}
}'
```
### Example request with group terms
```bash
curl -X POST \
https://platform.shoffi.app/API/affiliate/create \
-H 'Content-Type: application/json' \
-d '{
"apiKey": "YourKey",
"appId": 00000000,
"affiliateDetails": {
"email": "tobias@lutke.com",
"firstName": "Tobias",
"lastName": "Lütke",
"nickName": "tobi"
},
"groupId": 12345
}'
```
## Parameter breakdown
### affiliateDetails
* `email:`\
The new affiliate email address
* `firstName:`\
The new affiliate first name
* `lastName:`\
The new affiliate last name
* `nickName:`\
The new affiliate nickname
### groupId
* `groupId:`\
The ID of the affiliate group to assign to the affiliate. When this value is sent, Shoffi uses the group's terms.
You can find the group ID under `Groups` → click the group name → `Group ID` field.
### affiliateTerms
* `revenueShare:`\
The percentage you are willing to pay the affiliate for every transaction made by a store they referred (1–100). When `cpi` is greater than `0`, you may also set `revenueShare` to `0`. You can read more about [the affiliate commission](/general/the-affiliate-commission).
* `cpi:`\
Cost per install. The amount the affiliate will be rewarded for each successful app install. You can set the amount to `0` if you do not want to pay per install.
* `limitPeriod:`\
The period in which the affiliate will earn commissions from transactions made by the referred store, in months. If not limited, the affiliate will earn commissions as long as the referral is active.
* `minWithdrawal:`\
The minimum amount an affiliate must earn before they can request a withdrawal. This amount is in USD.
* `recurringChargeOnly:`\
Apply affiliate earnings from recurring charges only, excluding one-time fees charged by the app.
* `isNetAmount:`\
Calculate revenue share from the net amount. Default is `false`.
## Response example
```json
200 OK
Content-Type: application/json
```
# Add Bonus Reward
## Add a bonus reward to an affiliate
`POST` `https://platform.shoffi.app/API/affiliate/addBonusReward`
Use this endpoint to reward an affiliate with a one-time bonus commission.
#### Request Body
| Name | Type | Description |
| ---------------------------------------- | ------- | -------------------------------------------- |
| apiKey\* | String | Your Shoffi API Key (Integrations → API Key) |
| appId\* | Integer | Your app ID |
| email\* | String | The affiliate email address |
| amount\* | Integer | Bonus reward amount (USD) |
| internalNote | String | Internal note (for your own records) |
{% tabs %}
{% tab title="200: OK " %}
```json
{
"bonusReward": {
"email": "tobias@lutke.com",
"amount": 100,
"internalNote": "Bonus for Q4 campaign"
}
}
```
{% endtab %}
{% tab title="400: Bad Request " %}
```json
{
"status": 400,
"message": "Error details"
}
```
{% endtab %}
{% endtabs %}
```bash
curl -X POST \
https://platform.shoffi.app/API/affiliate/addBonusReward \
-H 'Content-Type: application/json' \
-d '{
"apiKey": "YourKey",
"appId": 00000000,
"email": "tobias@lutke.com",
"amount": 100,
"internalNote": "Bonus for Q4 campaign"
}'
```
## Parameter breakdown
* `email:`\
The affiliate email address.
* `amount:`\
The bonus reward amount to add.
* `internalNote:`\
Optional internal note (not shown to the affiliate).
## Response example
```json
200 OK
Content-Type: application/json
```
```json
{
"bonusReward": {
"email": "tobias@lutke.com",
"amount": 100,
"internalNote": "Bonus for Q4 campaign"
}
}
```
# Update Affiliate Terms
## Update existing affiliate contract terms
`POST` `https://platform.shoffi.app/API/affiliate/updateAffiliateTerms`
#### Request Body
| Name | Type | Description |
| ---------------------------------------- | ------- | -------------------------------------------------------------- |
| apiKey\* | String | Your Shoffi API Key (Integrations → API Key) |
| appId\* | Integer | Your app ID |
| email\* | String | The affiliate email address |
| groupId | Integer | Affiliate group ID. If sent, Shoffi applies the group terms. |
| affiliateTerms | Object | New affiliate contract terms. Used when `groupId` is not sent. |
{% hint style="info" %}
Send either `groupId` or `affiliateTerms`.
* If `groupId` is sent, Shoffi applies the group's terms.
* If only `affiliateTerms` is sent, Shoffi applies those terms and sets the affiliate group to custom.
{% endhint %}
{% tabs %}
{% tab title="200: OK " %}
```json
{
"affiliateNewTerms": {
"revenueShare": 50,
"cpi": 10,
"limitPeriod": 24,
"minWithdrawal": 50,
"recurringChargeOnly": false,
"isNetAmount": false
}
}
```
{% endtab %}
{% tab title="400: Bad Request " %}
```javascript
{
"status": 400,
"message": "Error details"
}
```
{% endtab %}
{% endtabs %}
### Example request with custom terms
```
curl -X POST \
https://platform.shoffi.app/API/affiliate/updateAffiliateTerms \
-H 'Content-Type: application/json' \
-d '{
"apiKey": "YourKey",
"appId": 00000000,
"email": "tobias@lutke.com",
"affiliateTerms": {
"revenueShare": 50,
"cpi": 10,
"limitPeriod": 24,
"minWithdrawal": 50,
"recurringChargeOnly": false,
"isNetAmount": false
}
}'
```
### Example request with group terms
```bash
curl -X POST \
https://platform.shoffi.app/API/affiliate/updateAffiliateTerms \
-H 'Content-Type: application/json' \
-d '{
"apiKey": "YourKey",
"appId": 00000000,
"email": "tobias@lutke.com",
"groupId": 12345
}'
```
## Parameter breakdown
### groupId
* `groupId:`\
The ID of the affiliate group to assign to the affiliate. When this value is sent, Shoffi uses the group's terms.
You can find the group ID under `Groups` → click the group name → `Group ID` field.
### affiliateTerms
* `revenueShare:`\
The percentage you are willing to pay the affiliate for every transaction made by a store they referred (1–100). When `cpi` is greater than `0`, you may also set `revenueShare` to `0`. You can read more about [the affiliate commission](/general/the-affiliate-commission).
* `cpi:`\
Cost per install. The amount the affiliate will be rewarded for each successful app install. You can set the amount to `0` if you do not want to pay per install.
* `limitPeriod:`\
The period in which the affiliate will earn commissions from transactions made by the referred store, in months. If not limited, the affiliate will earn commissions as long as the referral is active.
* `minWithdrawal:`\
The minimum amount an affiliate must earn before they can request a withdrawal. This amount is in USD.
* `recurringChargeOnly:`\
Apply affiliate earnings from recurring charges only, excluding one-time fees charged by the app.
* `isNetAmount:`\
Calculate revenue share from the net amount. Default is `false`.
## Response example
```json
200 OK
Content-Type: application/json
```
```json
{
"affiliateNewTerms": {
"revenueShare": 50,
"cpi": 10,
"limitPeriod": 24,
"minWithdrawal": 50,
"recurringChargeOnly": false,
"isNetAmount": false
}
}
```
# Add Referral
## Add a manual referral for an affiliate
`POST` `https://platform.shoffi.app/API/affiliate/addReferral`
Use this endpoint to add a manual referral directly to an affiliate.
#### Request Body
| Name | Type | Description |
| ------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------ |
| apiKey\* | String | Your Shoffi API Key (Integrations → API Key) |
| appId\* | Integer | Your app ID |
| email\* | String | The affiliate email address |
| shopName\* | String | The full `.myshopify.com` store URL of the referred shop |
| calManualBegin\* | Boolean | Controls manual referral commission calculation. `true` uses the app installation date. `false` starts from today. |
```bash
curl -X POST \
https://platform.shoffi.app/API/affiliate/addReferral \
-H 'Content-Type: application/json' \
-d '{
"apiKey": "YourKey",
"appId": 00000000,
"email": "affiliate@example.com",
"shopName": "https://store.myshopify.com",
"calManualBegin": true
}'
```
## Parameters breakdown
* `email:`\
The affiliate email address.
* `shopName:`\
The full `.myshopify.com` store URL of the referred shop.
* `calManualBegin:`\
Controls how Shoffi calculates the manual referral commission.
* `true` calculates commission from the app installation date.
* `false` calculates commission from today.
For more about manual referral calculation modes, see [Manual referrals](/for-affiliates/manual-referrals).
# Affiliate Payment Request
## Create a payment request on behalf of an affiliate
`POST` `https://platform.shoffi.app/API/affiliate/requestPayment`
You can use this API to let affiliates request payments directly from your app or website if they have already earned more than the minimum withdrawal amount.
#### Request Body
| Name | Type | Description |
| --------------------------------------------- | ------- | -------------------------------------------- |
| apiKey\* | String | Your Shoffi API Key (Integrations → API Key) |
| appId\* | Integer | Your app ID |
| paypalEmail\* | String | The PayPal email account of the affiliate |
| email\* | String | The affiliate email address |
{% tabs %}
{% tab title="200: OK " %}
```json
{
"affiliateNewTerms": {
"revenueShare": 50,
"cpi": 10,
"limitPeriod": 24,
"minWithdrawal": 50
}
}
```
{% endtab %}
{% tab title="400: Bad Request " %}
```javascript
{
"status": 400,
"message": "Error details"
}
```
{% endtab %}
{% endtabs %}
```
curl -X POST 'https://platform.shoffi.app/API/affiliate/requestPayment' \
-H 'Content-Type: application/json' \
-d '{
"apiKey": "YourKey",
"appId": 00000000,
"affiliateDetails": {
"email": "tobias@lutke.com",
"paypalEmail": "tobias@lutke.com"
}
}'
```
{% hint style="warning" %}
**Please Note!**\
Some affiliates have already added their PayPal email address to Shoffi. In that case, **the PayPal account stays the existing one**, not the one you sent in the request.
You can see the final PayPal email address in the response data.
{% endhint %}
## Response example
```json
200 OK
Content-Type: application/json
```
```json
{
"affiliateDetails": {
"email": "tobias@lutke.com",
"firstName": "Tobias",
"lastName": "Lütke",
"nickName": "tobi"
},
"affiliatePerformance": {
"appProfit": 39.8,
"affiliateProfit": "7.96",
"paidToAffiliate": 0,
"linkViews": 3
},
"paypalAddress": "tobias@lutke.com"
}
```
# Connecting to new apps
## Discovering new apps
You can find all available apps on the `Market` page. The table shows each app's affiliate terms, such as `Commission rate` and `Minimum withdrawal`.
Once your connection with an app is approved, it will appear on the `Connections` page.
## The connection request
When you find an app you want to promote, you can connect with it using the `Join affiliate program` button. A pop-up appears where you can review the affiliate terms. Once you apply, the request is sent to the app owner.
Some app owners also share an invite link. Joining with an invite link still follows that app's approval setting: if the app owner reviews requests manually, you will need their approval before the connection appears as active on your `Connections` page.
# Referral links
## What are referral links?
The referral links are how Shoffi can associate an install with the affiliate.\
The links contain a unique key with information about the app and the specific affiliate who promotes it.
## Finding referral links
Affiliates can find the links for apps they are connected to on the `Connections` page.
Every app has a `Copy link` button under the `Actions` column. This link is **unique** to each affiliate profile and app.
You can also find the link on the app page, along with all the [connected app information](/for-affiliates/connected-app-information).
# Manual referrals
## What are manual referrals?
The manual referral form allows you to report referrals made without using your referral links. After submitting a referral manually, the app owner will review the request and approve or decline it.
## When to use manual referrals
{% hint style="warning" %}
**Please note!**\
Use manual referrals only if you are confident that a specific store installed the app following your advice and you are a registered affiliate for that app.
{% endhint %}
If you have used the referral link, the referral will show up in the next 24 hours, and **there is no need to report it manually**.
There are two reasons to submit a manual referral:
* You have installed the app manually or told a merchant to do so without your affiliate link.
* You sent the link to a merchant, more than 24 hours have passed, and you still cannot find the referral on the platform.
## How to add a manual referral
### From the `Referrals` page
Go to the `Referrals` page and click the "Add referral manually" button.
Fill in the form with the required data. Here is the data you will be requested to provide:
* **App name**\
Choose the app you referred.
* **Referred store URL**\
The full `.myshopify.com` domain of the store you referred, for example `https://store.myshopify.com`.
* **Referral date**\
The date you made the referral.
* **Additional info (optional)**\
Add any information that helps the app owner confirm the referral.
Once you finish, click `Submit` and wait for the app owner's approval.
### From the connected app details page
If you want to add several referrals to the same app, it can be easier to add them directly from the app's [connected app details](/for-affiliates/connected-app-information) page.
While submitting referrals manually from this page, you must provide only the date and store URL.
## Approving manual referrals
After an affiliate submits a manual referral, the app owner will receive a notification with the data. The app owner can review the request and decide whether to approve it.
## Adding manual referrals on behalf of an affiliate
The app owner can add manual referrals directly from the affiliate details page in the app owner dashboard.
{% hint style="warning" %}
**Please note!**\
Adding a manual referral on behalf of an affiliate will approve the referral immediately.
{% endhint %}
To do that, go to the specific affiliate page, click `Actions`, and choose `Add referral manually`.
## Manual referral commission calculation
When approving or adding a manual referral for an affiliate, you can choose from two commission calculation options:
1. **Calculate commission from Today**
The affiliate's commission starts from the moment of approval, regardless of the app's installation date.
2. **Calculate commission from the App installation date**\
This option calculates commission retroactively from the app's original installation date and assigns the corresponding revenue share to the affiliate.
# Payout requests
## How payout requests work
An affiliate can request payment once their profit from an app exceeds that app's minimum withdrawal amount.
Once the request is sent, the app owner will have a 60-day window to transfer the money to your PayPal account, unless you and the app owner explicitly agreed on an alternative payment method.
## Requesting a payout
Go to the `Connections` page, where you can find all the apps you are connected with.
Every app has a `Request payment` button under the `Actions` column. The button stays disabled until you reach the minimum withdrawal amount.
### Attaching an invoice
Some app owners require an invoice before they can pay you. When an app requires it, an `Attach an invoice link` window will appear after you click `Request payment`.
Paste a link to an invoice for the requested amount. The link must start with `https://` (for example, a link to an invoice hosted on Google Drive, Dropbox, or your invoicing tool). You cannot complete the payout request for that app until a valid invoice link is added.
The invoice link is shared with the app owner so they can review it before sending your payment.
### Adding an alternative payment method
By default, payouts are paid through PayPal.
You can add an alternative payment method to your Shoffi account, such as a bank account, Wise account, or another payment method.
Adding an alternative payment method does not automatically mean the app owner will pay you through that method.
If you want to receive a payout through an alternative payment method, you must contact the app owner directly and ask for it before they send the payment.
The app owner can choose whether to approve the alternative payment method. If they do not approve it, or if you do not ask for it explicitly, the payout will be paid through PayPal by default.
## Approving a payout
Once you receive the payment, you need to approve it. The `Approve payment` button is in the same place as the `Request payment` button.
## Payout issues and disputes
If an app owner does not send the payment within the 60-day payment window, unless the app's custom terms and conditions say otherwise, you should follow up.
If an app owner did not pay you on time, contact the app owner directly.
# Performance analytics
## Global analytics
On your main dashboard, you can find detailed graphs and performance metrics. You can change the date range to review performance over different periods.
## App-specific analytics
If you want more information about a specific app, go to the `Connections` page and click the app name or logo.
On the app-specific page, you will find detailed information about your performance in promoting the app.
# Connected app information
### The connected app details page
If you want more information about a specific app, go to the `Connections` page and click the app name or logo.
There you can find:
* Performance analytics
* Referral link
* Affiliate terms
* Resources
* Last updates
* App support email
# The markets
## Public Market
The Shoffi public market is a [public page](https://shoffi.app/market/) that lists affiliate programs from apps using a [subscription plan](https://shoffi.app/pricing/) that includes the Shoffi market.
The page is visible to everyone. Shoffi promotes it to attract new affiliates.
## In-app Market
The in-app market is the `Market` page on every affiliate's Shoffi account. Only registered affiliates have access to this page.
Apps using a [subscription plan](https://shoffi.app/pricing/) that includes the Shoffi market are visible in the in-app market by default. You can opt out in your app settings.
## Apps Visibility
The visibility of apps in the different markets is based on their subscription plan and app settings.
You can opt out of both markets if you want to invite only specific affiliates. To do that, uncheck `Visible on Shoffi` in your [app's affiliate terms](/for-app-owners/the-affiliate-terms).
# The affiliate commission
## Commission rate
The commission rate is the percentage of each transaction that an app owner pays an affiliate for transactions made by a referred store. It must be between **1% and 100%**. If you also set a CPI (cost per install) greater than `$0`, you may set the commission rate to **0%**.
Commission can apply for as long as the store pays for the app. This includes recurring, usage-based, and one-time payments.
**Gross amount vs. net amount**
Shoffi uses the **gross amount** from Shopify Partners to calculate affiliate commissions.
This means commissions are based on the full transaction amount before Shopify fees and other deductions. The **net amount** is the final amount paid out after fees such as processing fees, taxes, currency conversion, and other applicable charges. Because these deductions vary, Shoffi does not use the net amount for commission calculations.
## Different transaction types
* **Recurring payments:**
If the app charges a recurring fee, the affiliate gets a commission on each transaction. Annual subscriptions and payments count as earnings for the month when they were paid.
* **One-time payments**
If the app charges a one-time fee or for in-app purchases, the affiliate gets a commission on each transaction.
* **Usage-based charges**
If the app charges based on merchant usage, the affiliate gets a commission on each transaction.
## Commission period limit
This is the number of months an affiliate earns commission from the referred store's transactions. If there is no limit, the affiliate earns commission as long as the referral is active.
## Attribution window
Shoffi keeps a 30-day attribution window for referral links.
If a merchant visits the referral link and subscribes to the app from the same device in the next 30 days, Shoffi will count that as a successful referral.
# Disputes
### Delay in payment
When an affiliate issues a payment request, the app owner has 60 days to transfer the money to the affiliate’s PayPal account, unless the app’s custom terms and conditions state otherwise or both sides explicitly agreed on an alternative payment method.
If the affiliate does not receive the payment within the specified timeframe, they should contact Shoffi support to investigate the case. If the support team determines that the app owner is withholding commission without a justified reason, Shoffi reserves the right to remove the app from the platform or take other appropriate actions to protect affiliates.
### Fake Installs and Misuse
Shoffi is committed to maintaining a fair and trustworthy affiliate environment. To uphold the integrity of our platform, the following misuse is strictly prohibited:
* **Fake Store Installations:** Affiliates must not install Shoffi apps on fake or fraudulent Shopify stores to artificially inflate Cost Per Install (CPI) earnings.
* **Automated Installations:**
Using bots, scripts, or any automated tools to generate app installations or interactions is strictly forbidden.
#### Consequences of Misuse
If an affiliate is found to be misusing Shoffi by installing apps on fake stores or engaging in any activity that manipulates CPI earnings, Shoffi reserves the right to:
* **Immediate Termination:** Terminate the affiliate's participation in the program without prior warning.
* **Revocation of Earnings:** Withhold any pending payments or earnings accrued through fraudulent activities.
* **Blacklist from Future Programs:** Prevent the affiliate from rejoining Shoffi's affiliate programs in the future.
* **Legal Action:** Take legal action if necessary to protect Shoffi's interests and maintain the platform's integrity.
### Reporting Misuse
If you suspect any affiliate is misusing Shoffi or engaging in fraudulent activities, please contact our support team immediately. We take all reports seriously and will investigate thoroughly to ensure compliance with our policies.
### Shopify Partners Delayed Payments
In rare cases, transactions that already appeared on the Shopify Partners and Shoffi dashboards may be delayed longer than expected or ultimately not be paid by Shopify. To avoid paying affiliate commission on revenue you never received, use the 60-day window to confirm that the funds reached you before paying affiliates. If the payment is delayed for any reason, contact us and we will approve a delayed commission status for the affiliate until you are paid.