Skip to main content

Documentation Index

Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt

Use this file to discover all available pages before exploring further.

Shopify vendor onboarding is only available in Spree Enterprise Edition.
This guide covers vendors who’ll connect their Shopify store to your marketplace. For other vendor types, see WooCommerce Vendor Onboarding and Manual/CSV Vendor Onboarding.
Shopify is one of the most common platforms your prospective vendors will already be running on, so it’s worth setting up a smooth, automated path for them to join your marketplace. With the right setup in place, a Shopify vendor can connect their store in just a few clicks — products, inventory, orders, and shipping all sync between Shopify and your marketplace automatically. Onboarding a Shopify vendor has two distinct parts: a one-time Admin Setup that the marketplace owner completes per vendor in their Shopify Partners account and Spree admin, and a much shorter Vendor Onboarding flow that the vendor themselves completes after receiving the install link.

​
Prerequisites

Before you can onboard Shopify vendors, you’ll need:
  • A Shopify Partners account — this is where you’ll create the custom Shopify apps used to connect each vendor’s store.
  • The spree_multi_vendor Enterprise gem installed on your Spree instance.

​
Admin Setup

This section is for the marketplace owner. It’s a one-time setup per vendor — once complete, the vendor only needs to install the app and complete a few onboarding tasks.

​
1. Create the Shopify App

Each Shopify vendor requires their own dedicated app, created from your Shopify Partners account.
  1. Sign in to your Shopify Partners account and open the Dev Dashboard.
  2. Click Create app.
  3. Give the app a name that identifies which vendor it’s for. We recommend writing the name in kebab-case (lowercase words separated by hyphens), e.g., example-vendor.
  4. You’ll be redirected to the Versions → Create version page. Fill in the form using the values below:
    • App name - already pre-filled from the previous step.
    • App URL - <app-base-url>/shopify/apps/<app-handle> (e.g., https://spree-marketplace.com/shopify/apps/example-vendor).
      • The <app-handle> can be set arbitrarily but must be unique across all your Shopify apps. We recommend using the app name from step 3 (already in kebab-case).
    • Embed app in Shopify admin - leave unchecked.
    • Preferences URL - leave empty.
    • Webhooks API Version - 2025-07.
    • Scopes - paste the following list exactly: 
      write_orders,read_inventory,read_products,read_fulfillments,read_locations,read_translations,read_locales,read_shipping
    • Optional scopes - leave empty.
    • Use legacy install flow - leave unchecked.
    • Redirect URLs - add both of the following:
      • <app-base-url>/shopify/apps/<app-handle>/auth
      • <app-base-url>/shopify/apps/<app-handle>/auth_callback
  5. Click Release at the bottom of the form, then confirm in the modal that appears.
After completing these steps, you should see an overview of the version you just released. The completed Create version form in the Shopify Dev Dashboard with all required fields filled in

​
2. Get the App’s Credentials

Spree needs the app’s Client ID and Secret to authenticate against Shopify.
  1. In the Shopify Dev Dashboard, select the app you just created.
  2. Open the app’s Settings page.
  3. Copy and save both the Client ID and the Secret.
The app Settings page in the Shopify Dev Dashboard with the Client ID and Secret fields

​
3. Register the App in Spree

Now register the new Shopify app inside your Spree admin so the marketplace can communicate with it.
  1. In the Spree admin dashboard, navigate to Settings → Shopify Apps.
The Shopify Apps page in the Spree admin dashboard listing any existing connected apps
  1. Click New Shopify App in the top right corner.
  2. Fill in the form and click Create:
    • Handle - must match the <app-handle> you used in step 1 (e.g., example-vendor).
    • Name - can be anything, but we recommend matching the handle for consistency.
    • Client ID - paste the Client ID from step 2.
    • Secret - paste the Secret from step 2.
The New Shopify App form in Spree with Handle, Name, Client ID, and Secret fields With the app created and connected to Spree, the next step is to generate the install link the vendor will use to connect their store.
  1. From the app’s Overview page in the Shopify Partner dashboard, click Select distribution method.
The Shopify app Overview page with the Select distribution method button highlighted
  1. Choose Custom Distribution and click Select. Confirm in the modal.
The distribution method dialog with Custom Distribution selected
  1. Fill in the Distribution form:
    • Store domain - the vendor’s Shopify store domain, formatted as either <shopify-domain>.myshopify.com or admin.shopify.com/store/<shopify-domain> (e.g., admin.shopify.com/store/jessicas-gym).
    • Allow multi-store install for one Plus organization - check this option.
  2. Click Generate link and confirm in the modal.
  3. Copy the install link and save it — you’ll send this to the vendor in step 5.
The generated install link displayed in the Shopify Dev Dashboard, ready to copy Send the install link you saved in step 4 to the vendor through any communication channel — email, Slack, or whatever you normally use. From here, the rest of the flow is on the vendor — see the Vendor Onboarding section below for what they’ll experience.
Vendor accounts are matched by the Shopify store owner’s email address. If you’re connecting multiple Shopify stores that share an owner email, each store will need a unique email set under Shopify Store Settings → General → Store details.
If you’re testing the flow yourself, make sure you’re signed out of the marketplace owner account before opening the install link — otherwise installation will fail. If that happens, simply open the install link again.

​
Vendor Onboarding

This section is for the vendor. Once you’ve received the install link from the marketplace owner, follow these steps to connect your Shopify store and complete your onboarding.

​
1. Install the Shopify App

  1. Open the install link the marketplace owner sent you.
  2. Log in to Shopify and select the store you’ll be connecting to the marketplace.
The Shopify store selection screen the vendor sees after opening the install link
  1. Accept the app installation.
The Shopify app installation acceptance screen with the Install button

​
2. Create Your Vendor Account

After accepting the installation, you’ll be redirected to a Spree onboarding screen and asked to create a vendor account. The Spree vendor account creation screen presented after the vendor accepts the Shopify app installation Fill in the form and submit. A few minutes after submitting, your Shopify products will start appearing in your Spree vendor dashboard.

​
3. Complete Your Onboarding Tasks

When you arrive at your vendor dashboard, you’ll see a Getting Started checklist. Most tasks are auto-completed for Shopify vendors thanks to the integration, but a few still need your attention. The Getting Started onboarding checklist in the Spree vendor dashboard

​
Auto-Completed Tasks

The following tasks are marked complete automatically when you install the app — just verify the imported information is correct:
  • Connect or Create a Shop — completed by the app installation itself.
  • Add Billing Address — imported from your Shopify store’s billing details.
  • Add Returns Address — imported from your Shopify store’s address.
  • Add Returns Policy — imported from your Shopify store, provided you have a returns policy configured there.

​
Confirm Shipping Rates

Your Shopify shipping methods and rates are synced automatically, but you still need to confirm them to mark this task complete. Navigate to Settings → Shipping in your vendor dashboard and click Confirm Shipping Rates in the top right corner. The Shipping Methods page in the vendor dashboard with the Confirm Shipping Rates button
You can edit existing shipping methods or add new ones at any time after onboarding is complete.

​
Connect Your Stripe Account

Stripe is used by the marketplace to process payments and send your payouts. To receive your earnings, you’ll need to connect a Stripe account.
  1. Click on Connect Stripe Account in your onboarding checklist.
  2. Click Connect your bank account to be guided through Stripe’s short onboarding process.
  3. Follow the Stripe prompts to set up a new account or connect an existing one.
The Connect Stripe Account task expanded in the onboarding checklist An existing Stripe account isn’t required — you can create one as part of this flow. The whole process usually takes around five minutes. Once connected, you’ll receive payouts whenever you ship orders.
If you’re not the one handling your company’s financials, you can invite another team member to complete this step instead.
Some marketplaces use payment providers other than Stripe. If that’s the case, you’ll be prompted to connect your bank account through a different flow — your marketplace owner will let you know the specifics.

​
What Syncs Between Shopify and the Marketplace

Once your Shopify store is connected, the following data syncs automatically:
  • Active products are imported into the marketplace catalog.
  • Inventory levels sync in both directions in real-time.
  • Shipping methods and rates sync from Shopify to the marketplace.
  • Orders placed on the marketplace appear in your Shopify dashboard for fulfillment, just like normal Shopify orders.
  • Fulfillment status and shipment tracking sync back to the marketplace and trigger customer notifications automatically.
  • Price updates made in Shopify sync to the marketplace.
  • Content updates (descriptions, images) sync to the marketplace, unless the marketplace owner has edited them.
You can choose which products to list on the marketplace by adding or removing the marketplace sales channel on each product in your Shopify admin.

​
Next Steps

Once onboarding is complete, your products will be sent to the marketplace owner for review. Once they’re approved, they’ll go live on the storefront, and you can manage your business primarily from your Shopify dashboard. For other vendor types, see WooCommerce Vendor Onboarding or Manual/CSV Vendor Onboarding.