Guides

Leverage Swell's flexible model system to expand upon their base functionalities. In this case, you can implement additional business logic to accommodate your marketplace. By building off of the /products and /orders models, you can add associations for vendors.

You can edit the /products model to include vendor_id as a field to establish an association between a vendor and a product. This will also allow querying for a vendor's specific products.

You can accomplish this through either the API or the model editor within the Swell dashboard.

Use the following:
Adding vendor_id to /products
await swell.put('/:models/products/fields', {
	vendor_id: {
		type: 'objectid',
		required: true // Optional
	}
});
Add directly from the dashboard

You can also accomplish this through the Swell dashboard through the Developer tools. To do so, navigate to the Products model under your Models tab, and add a field.

Adding vendor_id to the product model
  1. Go to Developer > Models
  2. Select the Products model
  3. Select Add Field; then choose Lookup
  4. Under Label type Vendor
  5. Select Customers for Lookup collection
  6. Select Details for the Admin field location. Specify this to your preference for displaying (or hiding) the field in the desired location.
  7. Save.

With the addition of the vendor_id, you can now create new products with an association to a vendor.

Associate product with a vendor
await swell.post('/products', {
	name: 'Swell T-Shirt',
	price: 120,
	type: 'standard',
	active: true,
	vendor_id: '609590e5d0ef5f42c5e1ce01' // Notes the id of the vendor account
});

You can also fetch all of a vendor's products by referencing the vendor's vendor_id.

Fetch product associated to a vendor_id
await swell.get('/products', {
	where: { vendor_id: '609590e5d0ef5f42c5e1ce01'},
	limit 25 // Optional, can be up to 1000
});

This will return all the products belonging to a vendor, which can then be rendered with a vendor-specific dashboard.

Similarly to products, it is also necessary to associate orders to vendors. Instead of adding the relation to the order itself, you can add the relation within an order's items array.

Update the orders model to include the vendor_id of each item added to the items array since an order might include items from multiple vendors. The vendor_id is retrievable from inputted products automatically using the formula.

Associate order to a vendor
await swell.put('/:models/orders/fields/items/fields', {
	vendor_id: {
		type: 'objectid',
		formula: 'product.vendor_id'
	}			
});

The following query will fetch orders containing products related to a particular vendor. Swell offers native support for most MongoDB query operators.

Fetch orders associated to a vendor
await swell.get('/orders', {
	where: {
		items: {$elemMatch: {'vendor_id': '609590e5d0ef5f42c5e1ce01'}}
	}
});

On your vendor dashboard, you'll want to filter the items array to only show the item that belongs to the specific vendor, as the query will return the entire order.

Vendors can fulfill order items by adding shipments onto orders. To create a shipment and fulfill items, simply post to the /shipments endpoint.

Adding shipments to orders
await swell.post('/shipments', {
	order_id: '60a3cd3ac2c46f30b6cb3b5d', // Required
	items: [ // Required
		{
			order_item_id: '60a3cd3ac2c46f30b6cb3b2a', // This is the id in the items array within an order
			product_id: '60a3cc9f23ead02dff477b89',
			quantity: 1
		}
	],
	tracking_code: '787374451654' // Optional
});

Swell allows you to assign multiple shipments to one order so that each vendor can fulfill their items separately with individual tracking numbers. When viewing orders from the Swell dashboard, orders that have unfilled items will display the partially fulfilled status until the order has associated all items to shipments.

Now that we've laid the foundation for the marketplace logic, we can move on to the next step: creating payouts for vendors on the marketplace. We'll need to ensure that they are able to set up and receive their payments by implementing payout logic specifically for a marketplace.