How to create multi-store orders

What you’ll learn

• What is Multi Store
  • Including a review of data models
• How to create multi-store orders with orderCreate

What is a Multi-Store?

In order to answer “what is multi-store”, it’s worth reviewing the individual seller model used by the majority of operators using Marketplacer.

Individual Seller Model

Despite the name, in the Individual Seller Model (ISM) we typically do have multiple sellers. Individual in this context refers to the fact that each one of those sellers:

• Manages their own products
• Manages the stock for those products

So while it could be possible (depending on the policies of the marketplace operator) for each of those sellers to “sell the same product”, i.e. they both sell the same Brand, Size and Color of a particular pair of trainers, these products would be hosted in Marktplacer as separate product instances.

The diagram below depicts this.

Here you can see:

• We have 2 separate sellers
• The sellers are selling the “same” product (referred to as an Advert in Marketplacer)
  • These adverts have unique IDs from a Marketplacer perspective, in this case 1 & 2
• These adverts each have 2 variants, each of which has been assigned a unique Marketplacer ID (1, 2, 3, & 4)
  • In Marktplacer it is at the variant level where we store:
    • The stock position (called countOnHand in the API data model)
    • The Barcode (or EAN)
    • The SKU

For all intents and purposes these products are totally separate, managed by different sellers. The marketplace operator could however choose to surface those products on the front end eCommerce system as they liked, e.g. they could present a “Buy Box” or something similar.

Placing orders

With the individual seller model, orders are created by supplying the variantId to the orderCreate mutation. A simplified example of this is shown below:

mutation {
  orderCreate(
    input: {
      order: {
        firstName: "John"
        surname: "Doe"
        phone: "0405510000"
        emailAddress: "john.doe@marketplacer.com"
        address: {
          address: "80 Market Street"
          city: "Melbourne"
          country: { code: "AU" }
          postcode: "3000"
          state: { name: "Queensland" }
        }
      }
      lineItems: [
        {
          variantId: "VmFyaWFudC0x"
          quantity: 2
          cost: { amount: 1000 }
        }
      ]
    }
  ) {
    order {
      id
      legacyId
      invoices {
        nodes {
          id
          legacyId
          lineItems {
            id
          }
        }
      }
    }
    errors {
      field
      messages
    }
  }
}

For the purposes of this conversation we’re really interested in the lineItems section of the mutation, here you can see we supply:

• variantId - this is a Base64 version of the variant Id
  • For more information on Marketplacer IDs please refer to this article.
• quantity - this is the number of the given variant that you want to purchase
• cost.amount - this is the total cost in the lowest denominated currency unit for the entire order
  • Here we supply a cost object that can contain both amount and tax fields, in this example we have chosen just to supply the amount

For more detail on how to place orders using the individual seller model, please refer to the main order create article here.

Multi-Store Model

With the multi-store model we introduce some new concepts:

• A Parent Store
• Parent Store Products
• Child Stores (these are the “multi-stores”)
• Inventory

The diagram below includes these new concepts:

The important takeaways from this model are:

• We have a Parent Seller that has a number of Child Sellers (in this case 3)
  • You can have more than 1 Parent Seller per Marketplacer instance
• Parent Sellers have a catalog of “Parent Products” that they control. In this example we have 1 parent product with 2 variants
  • Parent Sellers can sell these products themselves, (the Individual Seller Model), but in our example we’ll suggest that they don’t.
  • You can see in this example that the countOnHand of the Parent Product Variants are all zero
• The Child Sellers can then choose which of the parent products they want to sell, and can therefore hold an Inventory position for those parent products
• Child Sellers can also sell their “own” products, (the Individual Seller Model), alongside Parent Products, however there may be business enforced limitations on this based on the terms and conditions of the marketplace Operator.

To summarize the inventory holdings of each child seller, you can refer to the table below.

The use-case for multi-store

Multi-stores can be used in a number of different scenarios, however a common use-case we see is that of the franchise - i.e. each individual outlet (possibly located in a particular geography) each sell the same range of products, but have their own inventory. When customers then come to purchase those products from a central eCommerce store, the customer can pick the franchise that they want to purchase the products from. This purchase decision could be driven by geography (certainly in the case of click and collect orders), or simply because of stock availability.

Placing orders

With the multi seller model, orders are created by supplying the variantId and the inventoryId to the orderCreate mutation.

A simplified example of this is shown below:

mutation {
  orderCreate(
    input: {
      order: {
        firstName: "John"
        surname: "Doe"
        phone: "0405510000"
        emailAddress: "john.doe@marketplacer.com"
        address: {
          address: "80 Market Street"
          city: "Melbourne"
          country: { code: "AU" }
          postcode: "3000"
          state: { name: "Queensland" }
        }
      }
      lineItems: [
        {
          variantId: "VmFyaWFudC0x"
          inventoryId: "SW52ZW50b3J5LTI="
          quantity: 2
          cost: { amount: 1000 }
        }
      ]
    }
  ) {
    order {
      id
      legacyId
      invoices {
        nodes {
          id
          legacyId
          lineItems {
            id
          }
        }
      }
    }
    errors {
      field
      messages
    }
  }
}

In this example we are passing:

• variantId: VmFyaWFudC0x - This is “Variant 1”
• inventoryId: SW52ZW50b3J5LTI= - This is “Inventory 2”

Therefore, for this order we’re placing an order with Child Seller 2 (as they are the holders of Inventory #2).

Further examples

As described in the Individual Seller Model, you can provide multiple line items for different sellers to orderCreate, and this will:

• Create 1 Order
• Create Invoices for each seller participating on the order

This model can be applied to multi-store also, below we’ll detail 2 further examples:

• Example 1: Provide multiple multi-store line items (different child stores)
• Example 2: Generate a “mixed” order (same child store):
  • 1x Multi Store Line Item
  • 1x Individual Store Line Item

Example 1

In this example, we stick entirely with the multi-store model, and order 2 products from 2 different child sellers:

mutation {
  orderCreate(
    input: {
      order: {
        firstName: "John"
        surname: "Doe"
        phone: "0405510000"
        emailAddress: "john.doe@marketplacer.com"
        address: {
          address: "80 Market Street"
          city: "Melbourne"
          country: { code: "AU" }
          postcode: "3000"
          state: { name: "Queensland" }
        }
      }
      lineItems: [
        {
          variantId: "VmFyaWFudC0x"
          inventoryId: "SW52ZW50b3J5LTI="
          quantity: 1
          cost: { amount: 500 }
        }
        {
          variantId: "VmFyaWFudC0y"
          inventoryId: "SW52ZW50b3J5LTQ="
          quantity: 1
          cost: { amount: 500 }
        }
      ]
    }
  ) {
    order {
      id
      legacyId
      invoices {
        nodes {
          id
          legacyId
          lineItems {
            id
          }
        }
      }
    }
    errors {
      field
      messages
    }
  }
}

Here the 2 line items we are supplying are:

• Line Item 1
  • variantId: VmFyaWFudC0x - This is “Variant 1”
  • inventoryId: SW52ZW50b3J5LTI= - This is “Inventory 2”
• Line Item 2
  • variantId: VmFyaWFudC0y - This is “Variant 2”
  • inventoryId: SW52ZW50b3J5LTQ= - This is “Inventory 4”

This will result in:

• The creation of 1 order
  • The creation of 1 Invoice for Child Seller 2 (Line Item 1)
  • The creation of 1 Invoice for Child Seller 3 (Line Item 2)

Example 2

In this example, we’ll mix a multi-store line item, and an individual seller item - both of which will be for the same Child Seller:

mutation {
  orderCreate(
    input: {
      order: {
        firstName: "John"
        surname: "Doe"
        phone: "0405510000"
        emailAddress: "john.doe@marketplacer.com"
        address: {
          address: "80 Market Street"
          city: "Melbourne"
          country: { code: "AU" }
          postcode: "3000"
          state: { name: "Queensland" }
        }
      }
      lineItems: [
        {
          variantId: "VmFyaWFudC0x"
          inventoryId: "SW52ZW50b3J5LTI="
          quantity: 1
          cost: { amount: 500 }
        }
        {
          variantId: "VmFyaWFudC05OQ=="
          quantity: 1
          cost: { amount: 2000 }
        }
      ]
    }
  ) {
    order {
      id
      legacyId
      invoices {
        nodes {
          id
          legacyId
          lineItems {
            id
          }
        }
      }
    }
    errors {
      field
      messages
    }
  }
}

Here the 2 line items we are supplying are:

• Line Item 1
  • variantId: VmFyaWFudC0x - This is “Variant 1”
  • inventoryId: SW52ZW50b3J5LTI= - This is “Inventory 2”
• Line Item 2
  • variantId: VmFyaWFudC05OQ== - This is “Variant 99”
  • This is a variant Id (not shown on our diagram) for an Individual Seller Product created and belonging to Child Seller 2

This will result in:

• The creation of 1 order
  • The creation of 1 Invoice for Child Seller 2 (2x Line Items)