# 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:**
Must be your App Store listing, starting with `https://apps.shopify.com/`. 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`.
.png?alt=media\&token=ce0ae7cb-0069-414e-b6c9-a2615d479933)
* **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 (recommended)
Once your Partners API connection is validated, the app screen shows the **Big Query Integration** card. This is the default, no-code way for Shoffi to track affiliate installs. 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 (advanced)
Only use this option if you can't use BigQuery and prefer to send install data from your app code. It is hidden by default: click **Advanced** at the bottom of the integration card on the app screen to see your Shoffi key, test key, and POST request code. If your app already uses the POST request, this section opens automatically.
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, then **Advanced** at the bottom of the integration card. 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 send the POST request from a test app or staging environment. The call still returns HTTP **200**, so you can confirm your code is reaching Shoffi. Always read the JSON body — a 200 does not mean the request is ready for production.
**Example — production key and a valid `XFF`:**
```json
{
"status": 200,
"message": "OK",
"warnings": []
}
```
**Example — you used the test key.** Installs sent with the test key are not tracked. Change to your production key before you go live:
```json
{
"status": 200,
"message": "Received with warnings",
"warnings": [
{
"code": "POST-TEST-KEY",
"message": "You are using your TEST api_key (the key ending with _test). Installs sent with the test key are not tracked. When you go live, use your production api_key without the _test suffix."
}
]
}
```
You'll also get a warning (still HTTP 200) if the `XFF` value is wrong — for example missing, a placeholder like `0.0.0.0` or `11.1111.111.111`, a local address like `127.0.0.1` or `169.254.x.x`, the text `unknown`, or an XFF sent together with a port. Use the merchant's real `x-forwarded-for` value, without a port.
Once you push your code to production, change the test key to the real one.
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 XFF, 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 a matching production request, the integration status changes to `Under review`, not straight to `Completed`. Review can take up to 48 hours. Your app is ready for affiliates only after it is `Completed`.
#### When HTTP 200 still leaves the app Incomplete
A response like this only means the endpoint accepted the JSON:
```json
{
"status": 200,
"message": "OK",
"warnings": []
}
```
**Incomplete** means Shoffi has a valid Partner API connection and has not yet matched a post-install call to this live app. Work through this list before waiting on review:
* **Production key.** The test key (the one ending in `_test`) returns 200 and does not track installs. The call that should change status uses the production key from `My Apps` → `Edit app` → **Advanced**.
* **Live app, not a dev app.** `appId` is the numeric id in the live app's Partner Dashboard URL (`https://partners.shopify.com/{partnerId}/apps/{appId}`). The JSON key is `appId` (capital I). A dev-app id, a Shoffi id, or demo shop data stays Incomplete even when Shopify shows installs.
* **New development store.** Install and open the live app on a development store created for this test. Reinstalling on a store you already used does not count as that check.
* **Real XFF.** Read `x-forwarded-for` on the request where your app receives the shop domain during install. Do not send a placeholder, `unknown`, a local address, or an XFF with a port. The value must be the XFF of the merchant who installed the app. Do not send your own server's XFF, or the XFF added by your DNS or Cloudflare.
* **A second test when daily installs are low.** If the live app has no more than 2 organic installs per day, run the check again: install and open the live app on a second new development store, from a different computer. Two installs from different networks give Shoffi two different merchant XFF values, which confirms the `XFF` is the merchant's. That check speeds up approval.
* **Leave the call in the app.** Send it after every install and every reinstall. A merchant who installed years ago, uninstalled, and comes back through an affiliate is only attributed if this request runs again. Removing the code after one test stops future matches.
You do not read the affiliate link yourself to decide whether to call Shoffi. Send the post-install for the install. Shoffi matches the shop to the referral.
This request is only how Shoffi attributes affiliate installs. Recurring charges and usage charges are read later from the Shopify Partner API. You do not send a revenue event.
When a matching production call is stored, status changes to **Under review**, not straight to **Completed**. Review can take up to 48 hours. If it stays **Incomplete**, the stored calls are still the test key, the wrong app id, or a shop that is not a new install of the live app.
### 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. `My Apps` shows a warning that this app has not finished integration, with a link to continue the setup.
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. For post-install matches, CPI is charged on the next nightly update that includes that shop from Shopify. If Shopify never reports the shop, CPI is not charged. Owner-approved manual referrals are charged when you approve them.
* **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 to every payout request for this app before they can submit it — either upload a PDF (up to 2MB) or paste an `https://` link. You can review that invoice from payment details on the `Payouts` page before paying.
* **Disable manual referrals:**\
If enabled, affiliates cannot submit manual referrals for this program. You can still add referrals yourself from the affiliate connection page, and the Shoffi API `addReferral` endpoint still works.
* **Custom Terms And Conditions (optional):**\
A link to a webpage with your own affiliate program terms. When set, affiliates see and must acknowledge that link when joining.
## Advanced Terms
On the app page, **Disable manual referrals**, **Require invoice**, and **Custom Terms And Conditions** live under **Advanced Terms**, which is collapsed by default. When you edit a group or a single affiliate’s terms, Advanced Terms shows **Disable manual referrals** only (Require invoice and custom terms stay app-wide).
Changing only these Advanced Terms settings does not send a terms-changed notification or email to affiliates. Affiliates are notified when you change commission terms such as rate, period, CPI, or minimum withdrawal.
## 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. They are not notified if you only change **Disable manual referrals**.
{% 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. They are not notified if the new group only differs by **Disable manual referrals**.
{% 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
On a computer, hover a name on the `Affiliates` page to see that affiliate's nickname, email, promotion strategy, alternative payment, and any additional info they shared. Click the email in that card to copy it. The card does not appear on a phone.
Click a name on the `Affiliates` page (or on a group page) to open the affiliate connection page, where you can see the same details and perform actions such as editing affiliate terms or removing an affiliate. Performance includes **Unpaid Commission** (affiliate profit minus paid) so you can see what is still owed without calculating it.
You can download a CSV of your affiliates from the `Affiliates` page with **Export**. The file includes each affiliate’s referral link along with their terms and performance.
### 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`.
Affiliates are notified when you change commission terms (rate, period, CPI, or minimum withdrawal). They are not notified if you only change **Disable manual referrals**.
### 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 when requesting a payout — either by uploading a PDF (up to 2MB) or by pasting an `https://` link. You can review that invoice from the payout’s payment details on the `Payouts` page (download a hosted PDF, or open an external link) before sending the payment.
You can also download a full payouts CSV from `Actions` → `Export to CSV`. That file includes each payout’s alternative payment details and invoice URL when the affiliate provided an external link (those cells are empty when they did not, including when only a PDF was uploaded).
### 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). That file is PayPal-only (email, currency, and amount for requested payouts). Use **Export to CSV** if you need alternative payment details or invoice URLs.
# 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 `Edit token`.
3. Paste a **new** Partners API client access token from Shopify (not the one already saved in Shoffi). It starts with `prtapi_`, and the API client needs the `View financials` and `Manage apps` permissions. If you paste the current token, Shoffi blocks Validate and asks you to create a new one first.
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. Affiliates are not notified if you only change **Advanced Terms** (Disable manual referrals, Require invoice, or Custom Terms And Conditions).
{% endhint %}
## Integration errors on My Apps
If an app's status is **Incomplete**, `My Apps` shows a warning that the app has not finished integration. Open the app and finish the remaining steps.
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).
## App ID already exists
The new-app form rejects a Shopify app id that is already connected to a Shoffi account. You cannot claim or overwrite it from the form.
[Contact support](https://shoffi.app/contact-support/) with the numeric App ID and the account email that should own it. Support checks where it is connected and removes it from the other account. After that, submit the app again.
If you still have the original Shoffi login, use that account instead of creating a second one. Apps on a deactivated account are not editable until you subscribe again and re-enter the Partner API token. See [Frozen and Deactivated accounts](/subscriptions/frozen-and-deactivated-accounts#coming-back-after-deactivation).
## Deleting an app
There is no delete button. [Contact support](https://shoffi.app/contact-support/) and name the app.
Support confirms before removing it, because affiliates on that program are notified. Removal is not instant; support does it and writes back when it is done.
`Partner ID` and `App ID` on an app you are keeping stay locked. To point Shoffi at a different Shopify app, that is a delete-and-add, not an edit. A new Partner API token for the same app is self-serve: `My Apps` → `Edit app` → `Shopify partner details` → `Edit token`.
## The plan is already full
Each plan has a cap on integrated apps. The form will not add another app past that cap. See [Plan limits](/subscriptions/plan-limits#integrated-apps).
* Upgrade from `Settings` → `Change plan` if you need more apps.
* Or tell support which existing app to remove. Affiliates on the removed app are notified, then you can add the new one.
Support sometimes raises the cap for a single account. That is an exception, not a control in the dashboard.
# 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 cannot change data. They can still export CSV files (affiliates, referrals, and payouts) because those downloads are read-only. They cannot import affiliates, invite affiliates, run Mass Payout, or mark payouts as paid.
* **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 can go to a new email, or to someone who already has an affiliate account. An email that already belongs to an app owner account cannot be added as a team member.
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.
On the signup page they enter a password, their first name, their last name, and a **nickname**. The nickname is their unique handle on Shoffi (letters and numbers only). First and last name can match someone else; the nickname cannot. If that nickname is already taken, they will see an error on that field — they can pick a different nickname and submit again without needing a new invite.
**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. Webhooks are available on the **Growth** plan and above.
* **API Key** — create and manage the Shoffi API Key used to authenticate calls to the [Shoffi API](/the-shoffi-api/introduction-to-shoffi-api).
If you move to a plan without Integrations, Shoffi keeps any webhooks you already saved but does not send events until Integrations is available again.
***
## Webhook tab
### Creating a new integration
1. **Navigate to the Integrations page**
* In your Shoffi dashboard, click **Integrations** in the left-hand menu. App owners and Editors (write permission) can open this page; Viewers cannot.
* 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 **https** URL where Shoffi will send the webhook events (e.g., `https://example.com/webhook`). Use a public domain name — not an IP address, and not `http://`.
* **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"
}
```
***
### Webhook URL requirements
* Must start with `https://`.
* Must be a public domain name (not an IP address and not localhost).
* Must accept HTTP POST and return a `2xx` response when Shoffi sends the validation request and later event payloads.
### Slack incoming webhooks
You can paste a Slack **Incoming Webhook** URL (`https://hooks.slack.com/services/...`) directly into Shoffi. Slack only displays the `text` field in the channel, so for Slack URLs Shoffi puts the event JSON into `text` (for example `{"type":"REFERRAL","appName":"Demo App",...}`). Other webhook URLs keep the same JSON as before (no extra `text` field).
If you want more control over the Slack message (formatting, which fields appear, routing by event type), use **Zapier** instead: Catch Hook in Shoffi, then a Slack action in the Zap.
### 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, including **Slack** (add a Slack action such as **Send Channel Message**). You can also paste a Slack Incoming Webhook URL directly into Shoffi if you do not need Zapier.
* **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` → **Advanced**.
The Shoffi API is available on the Growth, Pro, and Enterprise plans. Creating a key requires one of those plans. Your account can make up to **4 API requests per second** (the same limit on every plan that includes the API). See [Introduction to Shoffi API](/the-shoffi-api/introduction-to-shoffi-api) for details.
### 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 cannot opt in
Shoffi Metrics needs a working Shopify Partners access token. If the Metrics page asks you to refresh the token, or My Apps shows a credentials warning, open the app, refresh the token under Shopify partner details, then try again. See [Refreshing your Partners API client access token](/for-app-owners/managing-your-apps#refreshing-your-partners-api-client-access-token).
#### 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/).
### Downgrading after you have been on a paid plan
The Free plan is only for a new account that has not subscribed to a paid plan yet. After the account has been on Growth (or another paid plan), it cannot be moved back to Free.
Your affiliates stay on the account either way. Downgrading does not delete them.
To move to a lower paid plan, such as Starter, contact support. Support checks that the number of integrated apps fits the destination plan. If it does not, you choose which apps to keep. See [Plan limits](/subscriptions/plan-limits#integrated-apps).
Leaving Shoffi completely is `Account cancellation` at the bottom of the subscription page. Cancellation is immediate. Affiliates are notified and can request a withdrawal even under the minimum. It is not the same action as a downgrade, and it does not put the account on Free.
# 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 Growth, Pro, and Enterprise plans. Your account can make up to **4 API requests per second**. 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` → **Advanced**. 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 the Growth, Pro, and Enterprise plans. Every plan that includes the API uses the same rate limit: **4 requests per second** for your account (shared across all of your apps). If you go over that limit, the API returns an error asking you to retry shortly. 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,
"recurringChargeOnly": false,
"isNetAmount": false,
"disableManualReferrals": false
},
"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,
"disableManualReferrals": 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`.
* `disableManualReferrals:`\
When `true`, the affiliate cannot submit manual referrals for this connection. Default is `false`. Owner and API `addReferral` are not blocked.
## 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,
"disableManualReferrals": 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`.
* `disableManualReferrals:`\
When `true`, the affiliate cannot submit manual referrals for this connection. Default is `false`. Owner and API `addReferral` are not blocked.
## Response example
```json
200 OK
Content-Type: application/json
```
```json
{
"affiliateNewTerms": {
"revenueShare": 50,
"cpi": 10,
"limitPeriod": 24,
"minWithdrawal": 50,
"recurringChargeOnly": false,
"isNetAmount": false,
"disableManualReferrals": 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.
{% hint style="info" %}
This endpoint works even when `disableManualReferrals` is enabled for the affiliate. That setting only blocks affiliates from submitting manual referrals themselves.
{% endhint %}
#### 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.
{% hint style="info" %}
Some app owners disable manual referrals for their program. When that happens, the "Add referral manually" action is not available for that app, and you should use your affiliate link for new referrals instead.
{% endhint %}
## 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. On the connection page, **Unpaid Commission** shows your profit minus what has already been paid.
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` window will appear after you click `Request payment`.
You can either:
* Upload a PDF invoice (maximum 2MB), or
* Paste a link to an invoice. The link must start with `https://` (for example, a link to an invoice on Google Drive, Dropbox, or your invoicing tool).
You cannot complete the payout request for that app until a valid invoice is added.
The invoice 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. That includes **Unpaid Commission**, which is your profit minus what has already been paid, so you do not have to calculate the remaining balance yourself.
# 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, including **Unpaid Commission** (your profit minus what has already been paid)
* 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.
## Cost per install (CPI)
CPI is a fixed bonus the app owner can pay for each successful install, in addition to (or instead of) revenue share.
For installs matched through the app's post-install integration, CPI is added on the next nightly update that includes that shop from Shopify — not instantly when the merchant installs. Affiliates see it on the connection after that update. If Shopify never reports the shop, CPI is not added.
Owner-approved [manual referrals](/for-affiliates/manual-referrals) still credit CPI when they are approved.
## 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.
