Build a marketplace app
- Yashika Saini (Unlicensed)
- Ajay Sharma
- Mayur Karwa
A marketplace app is a public app. A Public app is created if you want to build an integration for a larger audience and you want multiple users to install the app.
This guide will outline step by step process how you can build a public app on the Eshopbox platform.
Before you start
This guide assumes that you are familiar with the following steps:
Create an app in the Partner Dashboard.
You should authenticate your app using OAuth. Make sure you included following scopes while requesting authorization code:
Action | Scope |
|---|---|
Create/Update product | read:products, write:products |
Read Inventory | read:inventory |
Create/Update Product Availability | read:product_listings, write:product_listings |
Create/Update Order | read:orders, write:orders |
Create/Update Returns | read:returns, write:returns |
Create/Update Payout | read:payouts, write:payouts |
Select the intended audience to be Public while creating an app.
Steps to build a marketplace app
Following are the steps to build a marketplace app:
Step 1: Set Up
You are required to configure authentication. Refer Authentication document for setup.
Step 2: Create Triggers
Triggers are events that start the workflows. These events can be internal events in Eshopbox or your App. You cannot manually start a workflow. Triggers let Apps Script run a function automatically when a certain event occurs.
You are required to create the following triggers in your app.
New Order*: This trigger starts the workflow whenever an order is created on your app.
Product Update: This trigger starts the workflow whenever a product is created or updated in your app.
Order Cancelled By Customer: This trigger starts the workflow whenever a customer cancels an order in your app.
New Return: This trigger starts the workflow whenever a new return is created in your app.
New Payout: This trigger starts the workflow whenever you make a payment to the seller.
Step 3: Actions
An action is an event an Automation workflow performs after it is triggered.
You are required to create the following create and search actions in your app:
Create Actions: These actions add new data to your app.
Updated Inventory Count: This action updates the inventory count in your app when there is a change in the inventory (addition/ removal).
Update Order Status: This action updates the order status in your app when there is a change in the order status in the Eshopbox app.
Update Return Status: This action updates the return status in your app when there is a change in the return status in the Eshopbox app.
Verify Manifest: This action verifies the shipments created by the Eshopbox app.
Search Action: These actions finds data in apps and optionally create new items if the search returns no results.
Search Invoice: If your app generates the invoice then you create a search invoice action in your app. Eshopbox will get invoice details from your app through this search action.
Search Shipping Label: If your app generates the shipping label then, you create a search shipping label action in your app. Eshopbox will get shipping label details from your app through this search action.
Step 4: Automation Templates
Automation Template is a pre-configured integration between two apps. They are the fastest way to automate workflow. You are required to create the following automation templates.
Syncing products to Eshopbox
Select the Product Update trigger from your app.
Select Find Product search action from the Eshopbox app.
In the form fill Name of the Product(SKU) for which the event was triggered.
Add a condition to check if the product type is BASE.
Select Type key and the exactly matches filter. In the value type BASE.
If the condition is true then further add a condition to check if the product already exists, select search action’s Sku key, and exists filter.
If true, select Eshopbox Create Base Product action.
If false, select Eshopbox Update Base Product action.
If the condition is false then add a condition to check if the product type is KIT.
Select Type key and the exactly matches filter. In the value type KIT.
If the condition is true then further add a condition to check if the product already exists, select search action’s Sku key, and exists filter.
If true, select Eshopbox Create KIT action.
If false, select Eshopbox Update KIT action.
If the condition is false then, add a condition to check if the product already exists, select search action’s Sku key, and exists filter.
If true, select Eshopbox Create Virtual Combo action.
If false, select Eshopbox Update Virtual Combo action.
Map the following eshopbox action keys with your app’s trigger keys. Refer product document to map the keys.
Tracking inventory updates
Select Inventory Level Change trigger from the Eshopbox app.
Select Update Inventory Count action from your app.
Map the eshopbox trigger fields with your action fields. Refer the table for Eshopbox Trigger Fields:
key | Description |
|---|---|
productId | Unique Product Id |
inventory | Inventory count |
variantId | Update product inventory along variantId (seller SKU code) |
Submit an order for fulfillment
Select the New Order trigger from your app.
Select Create Product action from the Eshopbox app.
Map your trigger fields with eshopbox action fields. Refer order endpoint to map the fields.
Tracking fulfillment status
Select the Order Status Update trigger from the Eshopbox app.
Select the Update Inventory Count action from your app.
Map the eshopbox trigger fields with your action fields. Refer the table for Eshopbox Trigger Fields:
Key | Description |
|---|---|
resource |
|
eventType | it defines the CRUD format of the event |
eventSubType | describes the event status |
accountSlug | the account which has generated the event |
actor |
|
version | used for versioning the events |
request_data | request body |
response_data.customerOrderNumber | order number for which a shipment is created |
response_data.vendorOrderNumber | the unique number provided by the merchant itself |
response_data.externalShipmentID | the unique number of shipment in a channel |
response_data.integrationType |
|
response_data.externalWarehouseID | warehouse reference number of a shipment |
response_data.externalChannelID | sales channel name |
response_data.defaultWarehouseCode | warehouse code |
response_data.orderDate | order created date time |
response_data.portal_id | id of a portal |
response_data.paymentType | payment Method of order |
response_data.order_id | system-generated id of an order |
response_data.channel_id | id of a sales channel |
response_data.warehouse_id | unique warehouse id |
response_data.account_id | id of warehouse |
response_data.region | region of shipment |
response_data.invoiceNumber | invoice number of a shipment (generated at the time of packed ) |
response_data.boxType | box type |
response_data.isPriorityShipment | 1 if shipment is priority |
response_data.isGift | is gift(1if it is a gift else 0) |
response_data.invoice_url | invoice url of a shipment |
response_data.invoiceDate | date time on which the invoice has been generated |
response_data.label_url | label url of a shipment |
response_data.labels |
|
response_data.shippingInfo | shipping information |
response_data.boxAdditionalRecommendation | box additional information |
response_data.dimension_length | length of a shipment |
response_data.dimension_width | width of a shipment |
response_data.dimension_height | height of a shipment |
response_data.weight | weight of a shipment |
response_data.trackingID | tracking id generated for a shipment |
response_data.packageID | package id generated for a shipment |
response_data.barcode | barcode generated for a shipment |
response_data.courierName | courier name belongs to the trackind id |
response_data.created_at | create timestamp of shipment |
response_data.updated_at | update timestamp of shipment |
response_data.status | latest status of shipment |
response_data.remarks | latest remark on shipment |
response_data.customerName | billing customer name |
response_data.customerContactNumber | billing contact name |
response_data.email | billing email id of a customer |
response_data.channelSlug | unique slug of a channel |
response_data.status_updated_at | latest status updated date time |
response_data.status_log | statuses of a shipment |
response_data.orderExternalCreatedAt |
|
response_data.shippingAddress | shipping address details |
response_data.id | system generated unique id for a shipment |
response_data.isCOD | Type of order (1 if order is cod,0 if order is prepaid) |
response_data.track_payload | latest track payload object of a shipment |
response_data.packed_date | shipment packed date |
response_data.items[].lineItemSequenceNumber | incremental id of each item in a order |
response_data.items[].orderItemID | unique generated id by eshopbox |
response_data.items[].itemID | variant id of item (seller SKU code) |
response_data.items[].quantity | quantity of the item |
response_data.items[].sku | sku of item |
response_data.items[].asin | asin of item |
response_data.items[].productName | name of the item |
response_data.items[].customerPrice | unit price of item |
response_data.items[].invoiceTotal | total price of item |
response_data.items[].lineItemTotal | total price of item |
response_data.items[].discount | discount on item |
response_data.items[].taxRate | tax rate on item |
response_data.items[].taxAmount | tax amount on item |
response_data.items[].giftMessage | gift message |
response_data.items[].giftLabelContent | gift label |
response_data.items[].lineItemOrderStatus | Item Status |
response_data.items[].orderItemIDs | ids against each order items |
response_data.items[].productImageUrl | product image url of item |
response_data.items[].productAdditionalInfo | additional info of item(color, size) |
response_data.items[].expectedDeliveryDate | expected delivery date of an order |
response_data.items[].shippingCharges | shipping charges of item |
response_data.items[].productUrl | product url of item |
previous_data |
|
resource_type |
|
account_slug |
|
custom |
|
Customer cancellation
Select the Order Cancelled by Customer trigger from your app.
Select Cancel Order from the Eshopbox app.
Map your trigger fields with eshopbox action fields. Refer to cancel order endpoint to map the fields.
Create a return
Select the New Return trigger from your app.
Select Create Return from the Eshopbox app.
Map your trigger fields with eshopbox action fields. Refer to the return endpoint to map the fields.
Track return status
Select the Return Status Update trigger from the Eshopbox app.
Select the Update Return Status action from your app.
Map the eshopbox trigger fields with your action fields. Refer the table for Eshopbox Trigger Fields:
Key | Description |
|---|---|
resource | returnShipment |
eventType | it defines the CRUD format of the event |
eventSubType | describes the event status |
accountSlug | the account which has generated the event |
actor |
|
version | used for versioning the events |
request_data | request body |
response_data.customerOrderNumber | order number for which a shipment is created |
response_data.customerReturnNumber | unique Number against a sales channel Return Request |
response_data.order_id | system-generated id of an order |
response_data.pickupType | reverse |
response_data.refundAmount | amount to be refunded |
response_data.externalChannelID | sales channel name |
response_data.cp_id |
|
response_data.status | return status |
response_data.courierName | courier name of return |
response_data.trackingID | tracking id of return |
response_data.channel_id | id of a sales channel |
response_data.customerName | billing customer name |
response_data.customerContactNumber | billing contact name |
response_data.email | billing email id of a customer |
response_data.remarks | return remarks |
response_data.isCOD | 1 if order is cod,0 if order is prepaid |
response_data.channelSlug | unique slug of a channel |
response_data.accountSlug | account against which event is generated |
response_data.pickupAddress | pick up address of returned items |
response_data.dropAddress | drop address of returned items |
response_data.latest_status | latest status of return |
response_data.status_updated_at | timestamp of status update |
response_data.status_log | status details |
response_data.track_payload |
|
response_data.items[].returnReason | reason of return |
response_data.items[].item_image | item original image |
response_data.items[].additionalInfo | additional information of return item |
response_data.items[].returnType |
|
response_data.items[].lineItemSequenceNumber | incremental id of each item in a order |
response_data.items[].orderItemID | unique generated id by eshopbox |
response_data.items[].itemID | variant id of item (seller SKU code) |
response_data.items[].quantity | quantity of the item |
response_data.items[].productName | name of the item |
response_data.items[].lineItemTotal | total price of item |
response_data.items[].discount | discount on item |
response_data.items[].productImageUrl | product image url of item |
response_data.items[].productAdditionalInfo | additional info of item(color, size) |
response_data.items[].isExchange | is exchange |
response_data.items[].shippingCharges | shipping charges of item |
response_data.items[].productUrl | product url of item |
previous_data |
|
resource_type |
|
account_slug |
|
custom |
|
Add a payout
Select the New Payout trigger from your app.
Select Add a payout from the Eshopbox app.
Map your trigger fields with eshopbox action fields. Refer to the payout endpoint to map the fields.
Step 5: Turn Your App Into Sales Channel
The sales channel represents where you sell your products. Turning your app into a sales channel will enable you to fulfill orders.
Following are the steps to turn your app into a sales channel:
Choose a portal
Select an existing portal
Create a new portal:
Portal Type: a market place
Portal Name (unique): This can be the name of the APP.
Portal Logo Url: Logo URL of Portal.
Select the integration model
Invoice Settings: If you generate the invoice then create an Invoice Search Action in your app.
Shipping Label Settings: If you assign the couriers for shipment then create a Shipping Label Search in your app.
The * Actions/Triggers are mandatory for any marketplace app but Eshopbox highly recommends you to create all the above-mentioned actions and triggers.