> For the complete documentation index, see [llms.txt](https://docs.shoffi.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shoffi.app/for-app-owners/adding-a-new-app.md). # 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.md#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`. ![](https://774894163-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZJ53rrid2U7mef6xl6Ks%2Fuploads%2FqmOchCsZajqOpcUqUiP4%2FScreenshot%20\(27\).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 ![](https://774894163-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZJ53rrid2U7mef6xl6Ks%2Fuploads%2FNKMCI61rsa0C9YFngTgU%2FWhatsApp%20Image%202021-12-29%20at%208.41.33%20AM.jpeg?alt=media\&token=eb1f6a30-f1fd-4183-89ba-e5a0f4cdf1f4) 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.md) 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.md) — 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.