@vendure/docs 0.0.0-202601161541

package/docs/guides/how-to/google-oauth-authentication/index.mdx

@@ -0,0 +1,494 @@
+---
+title: "Google OAuth Authentication"
+---
+
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+:::info
+The complete source of the following example plugin can be found here: [example-plugins/google-auth-plugin](https://github.com/vendurehq/examples/tree/publish/examples/shop-google-auth)
+:::
+
+**Google OAuth authentication** allows customers to sign in using their Google accounts, providing a seamless experience that eliminates the need for password-based registration.
+
+This is particularly valuable for **consumer-facing stores** where users prefer the convenience and security of Google's authentication system, or for **B2B platforms** where organizations use Google Workspace.
+
+This guide shows you how to **add Google OAuth support** to your Vendure store using a custom [AuthenticationStrategy](/reference/typescript-api/auth/authentication-strategy/) and Google Identity Services.
+
+An **AuthenticationStrategy** in Vendure defines how users can log in to your store. Learn more about [authentication in Vendure](/guides/core-concepts/auth/).
+
+## Creating the Plugin
+
+**First, use the Vendure CLI** to create a new plugin for Google authentication:
+
+```bash
+npx vendure add -p GoogleAuthPlugin
+```
+
+This creates a basic [plugin](/guides/developer-guide/plugins/) structure with the necessary files.
+
+## Installing Dependencies
+
+**Google authentication requires** the Google Auth Library for token verification:
+
+```bash
+npm install google-auth-library
+```
+
+This library handles ID token verification securely on the server side, ensuring the tokens received from Google are authentic.
+
+## Creating the Authentication Strategy
+
+**Now create the Google authentication strategy.** Unlike traditional OAuth flows that use authorization codes, Google Identity Services provides **ID tokens directly**, which we verify server-side:
+
+```ts title="src/plugins/google-auth-plugin/google-auth-strategy.ts"
+import {
+  AuthenticationStrategy,
+  ExternalAuthenticationService,
+  Injector,
+  Logger,
+  RequestContext,
+  User,
+} from '@vendure/core';
+import { OAuth2Client } from 'google-auth-library';
+import { DocumentNode } from 'graphql';
+import { gql } from 'graphql-tag';
+
+export type GoogleAuthData = {
+  token: string;
+}
+
+export interface GoogleAuthOptions {
+  googleClientId: string;
+  onUserCreated?: (ctx: RequestContext, injector: Injector, user: User) => void;
+  onUserFound?: (ctx: RequestContext, injector: Injector, user: User) => void;
+}
+
+export class GoogleAuthStrategy implements AuthenticationStrategy<GoogleAuthData> {
+  readonly name = 'google';
+  private client: OAuth2Client;
+  private externalAuthenticationService: ExternalAuthenticationService;
+  private logger: Logger;
+  private injector: Injector;
+
+  constructor(private options: GoogleAuthOptions) {
+    // Initialize Google OAuth2Client for token verification
+    this.client = new OAuth2Client(options.googleClientId);
+    this.logger = new Logger();
+  }
+
+  init(injector: Injector) {
+    // Get services we'll use for customer management
+    this.externalAuthenticationService = injector.get(ExternalAuthenticationService);
+    this.injector = injector;
+  }
+
+  defineInputType(): DocumentNode {
+    // Define the GraphQL input type for the authenticate mutation
+    return gql`
+      input GoogleAuthInput {
+        token: String!
+      }
+    `;
+  }
+
+  async authenticate(ctx: RequestContext, data: GoogleAuthData): Promise<User | false> {
+    try {
+      // Step 1: Verify the Google ID token
+      const ticket = await this.client.verifyIdToken({
+        idToken: data.token,
+        audience: this.options.googleClientId,
+      });
+
+      const payload = ticket.getPayload();
+
+      if (!payload || !payload.email) {
+        this.logger.error('Invalid Google token or missing email', 'GoogleAuthStrategy');
+        return false;
+      }
+
+      // Step 2: Check if this Google user already has a Vendure account
+      const existingUser = await this.externalAuthenticationService.findCustomerUser(
+        ctx,
+        this.name,
+        payload.sub, // Google's unique user ID
+      );
+
+      if (existingUser) {
+        // User exists, log them in
+        this.logger.verbose(`User found: ${existingUser.identifier}`, 'GoogleAuthStrategy');
+        this.options.onUserFound?.(ctx, this.injector, existingUser);
+        return existingUser;
+      }
+
+      // Step 3: Create a new customer account for first-time Google users
+      const createdUser = await this.externalAuthenticationService.createCustomerAndUser(ctx, {
+        strategy: this.name,
+        externalIdentifier: payload.sub, // Store Google user ID
+        verified: payload.email_verified || false, // Use Google's verification status
+        emailAddress: payload.email,
+        firstName: payload.given_name || 'Google',
+        lastName: payload.family_name || 'User',
+      });
+
+      this.options.onUserCreated?.(ctx, this.injector, createdUser);
+
+      return createdUser;
+    } catch (error) {
+      this.logger.error(`Google authentication failed: ${error.message}`, 'GoogleAuthStrategy');
+      return false;
+    }
+  }
+}
+```
+
+The strategy uses Google's [OAuth2Client](https://googleapis.dev/nodejs/google-auth-library/latest/classes/OAuth2Client.html) to verify ID tokens and Vendure's [ExternalAuthenticationService](/reference/typescript-api/auth/external-authentication-service/) to handle customer creation.
+
+Key differences from other OAuth flows:
+- **ID Token Verification**: Google provides signed JWT tokens that we verify directly
+- **No Code Exchange**: Unlike GitHub OAuth, there's no authorization code to exchange
+- **Email Verification**: We respect Google's email verification status
+- **Fallback Names**: Provides defaults if Google profile lacks name information
+
+## Registering the Strategy
+
+**Now update the generated plugin file** to register your authentication strategy:
+
+```ts title="src/plugins/google-auth-plugin/google-auth-plugin.plugin.ts"
+import { PluginCommonModule, VendurePlugin } from '@vendure/core';
+
+import { GoogleAuthStrategy } from './google-auth-strategy';
+
+export interface GoogleAuthPluginOptions {
+  googleClientId: string;
+}
+
+@VendurePlugin({
+  imports: [PluginCommonModule],
+  configuration: (config) => {
+    const options = GoogleAuthPlugin.options;
+
+    if (options?.googleClientId) {
+      config.authOptions.shopAuthenticationStrategy.push(
+        new GoogleAuthStrategy({ googleClientId: options.googleClientId })
+      );
+    }
+    return config;
+  },
+})
+export class GoogleAuthPlugin {
+  static options: GoogleAuthPluginOptions;
+
+  static init(options: GoogleAuthPluginOptions) {
+    this.options = options;
+    return GoogleAuthPlugin;
+  }
+}
+```
+
+## Adding to Vendure Config
+
+**Add the plugin** to your Vendure configuration:
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+import { GoogleAuthPlugin } from './plugins/google-auth-plugin/google-auth-plugin.plugin';
+
+export const config: VendureConfig = {
+  // ... other config
+  plugins: [
+    // ... other plugins
+    GoogleAuthPlugin.init({
+      googleClientId: process.env.GOOGLE_CLIENT_ID!,
+    }),
+  ],
+  // ... rest of config
+};
+```
+
+## Setting up Google OAuth App
+
+**Before you can test the integration,** you need to create a Google OAuth 2.0 Client:
+
+1. **Go to** the [Google Cloud Console](https://console.cloud.google.com/)
+2. **Create a new project** or select an existing one
+3. **Navigate to** **APIs & Services → Credentials**
+4. **Click** **"Create Credentials" → "OAuth 2.0 Client ID"**
+5. **Select** **"Web application"** as the application type
+6. **Configure the client:**
+   - **Name**: Your app name (e.g., "My Vendure Store")
+   - **Authorized JavaScript origins**: `http://localhost:3001`
+   - **Authorized redirect URIs**: `http://localhost:3001/sign-in`
+
+:::note
+The **localhost URLs** shown here are for **local development only.** In production, replace `localhost:3001` with your actual domain (e.g., `https://mystore.com`).
+:::
+
+7. **Click "Create"** and copy the Client ID
+
+**Add the client ID** to your environment:
+
+```bash title=".env"
+GOOGLE_CLIENT_ID=your_google_client_id.apps.googleusercontent.com
+```
+
+## Frontend Integration
+
+### Creating the Sign-in Component
+
+**For the frontend,** we'll use Google's official Identity Services library, which provides a **secure and user-friendly sign-in experience:**
+
+```typescript title="components/GoogleSignInButton.tsx"
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useRouter } from 'next/navigation';
+
+const GOOGLE_CLIENT_ID = process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID;
+
+declare global {
+  interface Window {
+    google: any;
+    handleCredentialResponse?: (response: any) => void;
+  }
+}
+
+export function GoogleSignInButton() {
+  const router = useRouter();
+  const [pending, setPending] = useState(false);
+
+  useEffect(() => {
+    // Define the callback function globally
+    window.handleCredentialResponse = async (response: any) => {
+      setPending(true);
+      try {
+        const result = await authenticateWithGoogle(response.credential);
+
+        if (result?.success) {
+          router.replace('/account');
+        } else {
+          console.error('Authentication failed:', result?.message);
+        }
+      } catch (error) {
+        console.error('Google authentication error:', error);
+      } finally {
+        setPending(false);
+      }
+    };
+
+    // Load Google Identity Services
+    if (!window.google && GOOGLE_CLIENT_ID) {
+      const script = document.createElement('script');
+      script.src = 'https://accounts.google.com/gsi/client';
+      script.async = true;
+      script.onload = () => {
+        window.google.accounts.id.initialize({
+          client_id: GOOGLE_CLIENT_ID,
+          callback: window.handleCredentialResponse,
+        });
+      };
+      document.head.appendChild(script);
+    }
+
+    return () => {
+      delete window.handleCredentialResponse;
+    };
+  }, [router]);
+
+  const handleGoogleSignIn = () => {
+    if (!GOOGLE_CLIENT_ID) {
+      console.error('Google Client ID not configured');
+      return;
+    }
+
+    if (window.google) {
+      window.google.accounts.id.prompt();
+    } else {
+      console.error('Google SDK not loaded');
+    }
+  };
+
+  return (
+    <button
+      onClick={handleGoogleSignIn}
+      disabled={pending}
+      className="flex items-center justify-center w-full px-4 py-2 border border-gray-300 rounded-md shadow-sm text-sm font-medium text-gray-700 bg-white hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500"
+    >
+      {pending ? (
+        'Authenticating...'
+      ) : (
+        <>
+          <svg className="w-5 h-5 mr-2" viewBox="0 0 24 24">
+            <path fill="#4285F4" d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"/>
+            <path fill="#34A853" d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"/>
+            <path fill="#FBBC05" d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"/>
+            <path fill="#EA4335" d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"/>
+          </svg>
+          Continue with Google
+        </>
+      )}
+    </button>
+  );
+}
+```
+
+### Creating the Authentication Function
+
+**Create a server action** to handle the Google authentication:
+
+```typescript title="actions/auth.ts"
+'use server';
+
+import { gql } from 'graphql-request';
+
+const AUTHENTICATE_MUTATION = gql`
+  mutation AuthenticateWithGoogle($input: AuthenticationInput!) {
+    authenticate(input: $input) {
+      ... on CurrentUser {
+        id
+        identifier
+        channels {
+          code
+          token
+          permissions
+        }
+      }
+      ... on InvalidCredentialsError {
+        authenticationError
+        errorCode
+        message
+      }
+      ... on NotVerifiedError {
+        errorCode
+        message
+      }
+    }
+  }
+`;
+
+export async function authenticateWithGoogle(token: string) {
+  try {
+    const result = await vendureClient.request(AUTHENTICATE_MUTATION, {
+      input: {
+        google: {
+          token
+        }
+      }
+    });
+
+    if (result.authenticate.__typename === 'CurrentUser') {
+      // Authentication successful
+      return { success: true, user: result.authenticate };
+    } else {
+      // Handle authentication error
+      return {
+        success: false,
+        message: result.authenticate.message
+      };
+    }
+  } catch (error) {
+    console.error('Google authentication error:', error);
+    return {
+      success: false,
+      message: 'Authentication failed'
+    };
+  }
+}
+```
+
+**Add your Google Client ID** to the frontend environment:
+
+```bash title=".env.local"
+NEXT_PUBLIC_GOOGLE_CLIENT_ID=your_google_client_id.apps.googleusercontent.com
+VENDURE_API_ENDPOINT=http://localhost:3000/shop-api
+```
+
+**The Google Identity Services flow works as follows:**
+
+1. **User clicks "Continue with Google"** → Google popup appears
+2. **User signs in with Google** → Google returns an ID token
+3. **Frontend sends the token to Vendure** → Vendure verifies token with Google
+4. **If valid, Vendure creates/finds customer** → User is logged in
+
+## Using the GraphQL API
+
+**Once your plugin is running,** Google authentication will be **available in your shop API:**
+
+<Tabs>
+<TabItem value="Mutation" label="Mutation" default>
+
+```graphql
+mutation AuthenticateWithGoogle {
+  authenticate(input: {
+    google: {
+      token: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
+    }
+  }) {
+    ... on CurrentUser {
+      id
+      identifier
+      channels {
+        code
+        token
+        permissions
+      }
+    }
+    ... on InvalidCredentialsError {
+      authenticationError
+      errorCode
+      message
+    }
+    ... on NotVerifiedError {
+      errorCode
+      message
+    }
+  }
+}
+```
+
+</TabItem>
+<TabItem value="Response" label="Response">
+
+```json
+{
+  "data": {
+    "authenticate": {
+      "id": "1",
+      "identifier": "user@gmail.com",
+      "channels": [
+        {
+          "code": "__default_channel__",
+          "token": "session_token_here",
+          "permissions": ["Authenticated"]
+        }
+      ]
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+## Customer Data Management
+
+**Google-authenticated customers** are managed like any other Vendure [Customer](/reference/typescript-api/entities/customer/):
+
+- **Email**: Uses the user's actual Google email address
+- **Verification**: Inherits Google's email verification status
+- **External ID**: Google's unique user ID (`sub` claim) for future authentication
+- **Profile**: First and last names from Google profile, with fallbacks
+- **Security**: No password stored - authentication handled entirely by Google
+
+This means **Google users work seamlessly** with Vendure's [order management](/guides/core-concepts/orders/), [promotions](/guides/core-concepts/promotions/), and all customer workflows.
+
+## Testing the Integration
+
+**To test your Google OAuth integration:**
+
+1. **Start your Vendure server** with the plugin configured
+2. **Navigate to your storefront** and click "Continue with Google"
+3. **Complete the Google OAuth flow** when prompted
+4. **Verify customer creation** in the Vendure Dashboard
+5. **Test repeat logins** to ensure existing customers are found correctly

package/docs/guides/how-to/multi-vendor-marketplaces/index.md

@@ -0,0 +1,197 @@
+---
+title: "Multi-vendor Marketplaces"
+---
+
+# Multi-vendor Marketplaces
+
+Vendure v2.0 introduced a number of changes and new APIs to enable developers to build multi-vendor marketplace apps.
+
+This is a type of application in which multiple sellers are able to list products, and then customers can create orders containing products from one or more of these sellers. Well-known examples include Amazon, Ebay, Etsy and Airbnb.
+
+This guide introduces the major concepts & APIs you will need to understand in order to implement your own multi-vendor marketplace application. 
+
+## Multi-vendor plugin
+
+All the concepts presented here have been implemented in our [example multi-vendor plugin](https://github.com/vendurehq/vendure/tree/master/packages/dev-server/example-plugins/multivendor-plugin). The guides here will refer to specific parts of this plugin which you should consult to get a full understanding of how an implementation would look.
+
+:::caution
+**Note:** the [example multi-vendor plugin](https://github.com/vendurehq/vendure/tree/master/packages/dev-server/example-plugins/multivendor-plugin) is for educational purposes only, and for the sake of clarity leaves out several parts that would be required in a production-ready solution, such as email verification and setup of a real payment solution.
+:::
+
+![The Dashboard Aggregate Order screen](./aggregate-order.webp)
+
+## Sellers, Channels & Roles
+
+The core of Vendure's multi-vendor support is Channels. Read the [Channels guide](/guides/core-concepts/channels/) to get a more detailed understanding of how they work.
+
+Each Channel is assigned to a [Seller](/reference/typescript-api/entities/seller/), which is another term for the vendor who is selling things in our marketplace.
+
+So the first thing to do is to implement a way to create a new Channel and Seller.
+
+In the multi-vendor plugin, we have defined a new mutation in the Shop API which allows a new seller to register on our marketplace:
+
+```graphql title="Shop API"
+mutation RegisterSeller {
+  registerNewSeller(input: {
+    shopName: "Bob's Parts",
+    seller: {
+      firstName: "Bob"
+      lastName: "Dobalina"
+      emailAddress: "bob@bobs-parts.com"
+      password: "test",
+    }
+  }) {
+    id
+    code
+    token
+  }
+}
+```
+
+Executing the `registerNewSeller` mutation does the following:
+
+- Create a new [Seller](/reference/typescript-api/entities/seller/) representing the shop "Bob's Parts"
+- Create a new [Channel](/reference/typescript-api/entities/channel) and associate it with the new Seller
+- Create a [Role](/reference/typescript-api/entities/role) & [Administrator](/reference/typescript-api/entities/administrator) for Bob to access his shop admin account
+- Create a [ShippingMethod](/reference/typescript-api/entities/shipping-method) for Bob's shop
+- Create a [StockLocation](/reference/typescript-api/entities/stock-location) for Bob's shop
+
+Bob can now log in to the Dashboard using the provided credentials and begin creating products to sell!
+
+### Keeping prices synchronized
+
+In some marketplaces, the same product may be sold by multiple sellers. When this is the case, the product and its variants
+will be assigned not only to the default channel, but to multiple other channels as well - see the 
+[Channels, Currencies & Prices section](/guides/core-concepts/channels/#channels-currencies--prices) for a visual explanation of how this works.
+
+This means that there will be multiple ProductVariantPrice entities per variant, one for each channel. 
+ 
+In order
+to keep prices synchronized across all channels, the example multi-vendor plugin sets the `syncPricesAcrossChannels` property
+of the [DefaultProductVariantPriceUpdateStrategy](/reference/typescript-api/configuration/product-variant-price-update-strategy#defaultproductvariantpriceupdatestrategy)
+to `true`. Your own multi-vendor implementation may require more sophisticated price synchronization logic, in which case
+you can implement your own custom [ProductVariantPriceUpdateStrategy](/reference/typescript-api/configuration/product-variant-price-update-strategy).
+
+## Assigning OrderLines to the correct Seller
+
+In order to correctly split the Order later, we need to assign each added OrderLine to the correct Seller. This is done with the [OrderSellerStrategy](/reference/typescript-api/orders/order-seller-strategy/) API, and specifically the `setOrderLineSellerChannel()` method.
+
+The following logic will run any time the `addItemToOrder` mutation is executed from our storefront:
+
+```ts
+export class MultivendorSellerStrategy implements OrderSellerStrategy {
+  // other properties omitted for brevity   
+    
+  async setOrderLineSellerChannel(ctx: RequestContext, orderLine: OrderLine) {
+    await this.entityHydrator.hydrate(ctx, orderLine.productVariant, { relations: ['channels'] });
+    const defaultChannel = await this.channelService.getDefaultChannel();
+  
+    // If a ProductVariant is assigned to exactly 2 Channels, then one is the default Channel
+    // and the other is the seller's Channel.
+    if (orderLine.productVariant.channels.length === 2) {
+      const sellerChannel = orderLine.productVariant.channels.find(
+        c => !idsAreEqual(c.id, defaultChannel.id),
+      );
+      if (sellerChannel) {
+        return sellerChannel;
+      }
+    }
+  }
+}
+```
+
+The end result is that each OrderLine in the Order will have its `sellerChannelId` property set to the correct Channel for the Seller.
+
+## Shipping
+
+When it comes time to choose a ShippingMethod for the Order, we need to ensure that the customer can only choose from the ShippingMethods which are supported by the Seller. To do this, we need to implement a [ShippingEligibilityChecker](/reference/typescript-api/shipping/shipping-eligibility-checker/) which will filter the available ShippingMethods based on the `sellerChannelId` properties of the OrderLines.
+
+Here's how we do it in the example plugin:
+
+```ts
+export const multivendorShippingEligibilityChecker = new ShippingEligibilityChecker({
+  // other properties omitted for brevity   
+    
+  check: async (ctx, order, args, method) => {
+    await entityHydrator.hydrate(ctx, method, { relations: ['channels'] });
+    await entityHydrator.hydrate(ctx, order, { relations: ['lines.sellerChannel'] });
+    const sellerChannel = method.channels.find(c => c.code !== DEFAULT_CHANNEL_CODE);
+    if (!sellerChannel) {
+      return false;
+    }
+    for (const line of order.lines) {
+      if (idsAreEqual(line.sellerChannelId, sellerChannel.id)) {
+        return true;
+      }
+    }
+    return false;
+  },
+});
+```
+
+In the storefront, when it comes time to assign ShippingMethods to the Order, we need to ensure that
+every OrderLine is covered by a valid ShippingMethod. We pass the ids of the eligible ShippingMethods to the `setOrderShippingMethod` mutation:
+
+```graphql
+mutation SetShippingMethod($ids: [ID!]!) {
+  setOrderShippingMethod(shippingMethodId: $ids) {
+    ... on Order {
+      id
+      state
+      # ...etc
+    }
+    ... on ErrorResult {
+      errorCode
+      message
+    }
+  }
+}
+```
+
+Now we need a way to assign the correct method to each line in an Order. This is done with the [ShippingLineAssignmentStrategy](/reference/typescript-api/shipping/shipping-line-assignment-strategy/) API.
+
+We will again be relying on the `sellerChannelId` property of the OrderLines to determine which ShippingMethod to assign to each line. Here's how we do it in the example plugin:
+
+```ts
+export class MultivendorShippingLineAssignmentStrategy implements ShippingLineAssignmentStrategy {
+  // other properties omitted for brevity   
+    
+  async assignShippingLineToOrderLines(ctx: RequestContext, shippingLine: ShippingLine, order: Order) {
+    // First we need to ensure the required relations are available
+    // to work with.
+    const defaultChannel = await this.channelService.getDefaultChannel();
+    await this.entityHydrator.hydrate(ctx, shippingLine, { relations: ['shippingMethod.channels'] });
+    const { channels } = shippingLine.shippingMethod;
+  
+    // We assume that, if a ShippingMethod is assigned to exactly 2 Channels,
+    // then one is the default Channel and the other is the seller's Channel.
+    if (channels.length === 2) {
+      const sellerChannel = channels.find(c => !idsAreEqual(c.id, defaultChannel.id));
+      if (sellerChannel) {
+        // Once we have established the seller's Channel, we can filter the OrderLines
+        // that belong to that Channel. The `sellerChannelId` was previously established
+        // in the `OrderSellerStrategy.setOrderLineSellerChannel()` method.
+        return order.lines.filter(line => idsAreEqual(line.sellerChannelId, sellerChannel.id));
+      }
+    }
+    return order.lines;
+  }
+}
+```
+
+## Splitting orders & payment
+
+When it comes to payments, there are many different ways that a multi-vendor marketplace might want to handle this. For example, the marketplace may collect all payments and then later disburse the funds to the Sellers. Or the marketplace may allow each Seller to connect their own payment gateway and collect payments directly.
+
+In the example plugin, we have implemented a simplified version of a service like [Stripe Connect](https://stripe.com/connect), whereby each Seller has a `connectedAccountId` (we auto-generate a random string for the example when registering the Seller). When configuring the plugin we also specify a "platform fee" percentage, which is the percentage of the total Order value which the marketplace will collect as a fee. The remaining amount is then split between the Sellers.
+
+The [OrderSellerStrategy](/reference/typescript-api/orders/order-seller-strategy/) API contains two methods which are used to first split the Order from a single order into one _Aggregate Order_ and multiple _Seller Orders_, and then to calculate the platform fee for each of the Seller Orders:
+
+- `OrderSellerStrategy.splitOrder`: Splits the OrderLines and ShippingLines of the Order into multiple groups, one for each Seller.
+- `OrderSellerStrategy.afterSellerOrdersCreated`: This method is run on every Seller Order created after the split, and we can use this to assign the platform fees to the Seller Order.
+
+## Custom OrderProcess
+
+Finally, we need a custom [OrderProcess](/reference/typescript-api/orders/order-process/) which will help keep the state of the resulting Aggregate Order and its Seller Orders in sync. For example, we want to make sure that the Aggregate Order cannot be transitioned to the `Shipped` state unless all of its Seller Orders are also in the `Shipped` state.
+
+Conversely, we can automatically set the state of the Aggregate Order to `Shipped` once all of its Seller Orders are in the `Shipped` state.