View Source

The sales channel represents where you sell your products. Sales channels apps help you to integrate your sales channels with Eshopbox. A private app is created if you are building a custom integration for a particular workspace and not for a general larger audience.

This guide will outline step by step process how you can build an app on the Eshopbox platform to connect with your custom sales channel.

Before you start

This guide assumes that you're familiar with the following steps:

Create an app in the Partner Dashboard. Select the intended audience to be Private while creating an app.
You should authenticate your app using OAuth. Make sure you included following scopes while requesting authorization code:
- read: products
- write: products
- read:product_listings
- write:product_listings
- read: inventory
- read: orders
- write:orders
- read:returns
- write:returns

Step by step guide

Step 1: Set up

Enable a custom sales channel in your workspace.
Your app will need the auto-generated sales channel code while creating orders, returns, etc.

Step 2: Sync Products and Inventory

Apps and Automations > Build a Private Sales Channel App > Copy of Inventory and Product Availability-Page-1 (1) (1).png

You add new products to your sales channel catalog.
New products should be configured in your Eshopbox workspace as well. Your app should verify if these products are already configured in Eshopbox.
1. If the product is already configured, your app should mark the product as available on the Sales Channel. This will ensure the app can track the change in the inventory level of this product.
2. If no, your app should configure the product in your Eshopbox workspace and mark it available on your sales channel.
Now, your app should track inventory changes in the Eshobox fulfillment Center and update such changes in your sales channel catalog.

note

While updating inventory in your sales channel catalog, your app should be able to make adjustments for any orders you have received on the sales channel but not yet sent for fulfillment to Eshopbox. Know more

Syncing products to Eshopbox

Following are the steps that need to be implemented in your app to automate syncing products to Eshopbox

Your app should be able to track whenever there is a new product added to your sales channel catalog.
Your app should search for the product in the Eshopbox workspace. To search for products, send a GET request to products endpoint
GET 'https://{workspace}.myeshopbox.com/product-engine/api/v1/products/{productSku}'

where {workspace}, is workspace name and {productSku} is Name of the Product (SKU)

Check for a condition if the product exists in Eshopbox. If the product doesn't exist in Eshopbox then it returns an error message "Failed: Name of the product(SKU) does not exist"
Configure a new product in Eshopbox by sending a POST request to Products endpoint
POST 'https://{workspace}.myeshopbox.com/product-engine/api/v1/products'

where {workspace} is your workspace name. Eshopbox verifies the request body and creates a draft product in case any of the mandatory information is missing or incorrect. Such draft products are visible in the Eshopbox workspace and you can edit the product to add mandatory fields or make corrections.

Update the product availability by performing a POST request to Mark Product Availability API
POST 'https://{workspace}.myeshopbox.com/product-engine/api/v1/productListing'

where {workspace} is the workspace name.

Tracking inventory updates

Following are the steps that need to be implemented in your app to sync inventory across Eshopbox and your sales channel

To register a webhook, send a POST request to Webhook endpoint.

POST 'https://{workspace}.myeshopbox.com/api/v1/webhook'

where {workspace} is your workspace name.

Eshopbox will send updates to the registered webhook URL. Sample event:

curl --location --request POST 'https://CLIENT-URL' \
--header 'Content-Type: application/json' \
--data-raw '{
  "skus": [{
    
    "ean": "1180552RN-406-40",
    "stock": "20"
  }, {
    "ean": "2170100125-1-40",
    "stock": "2"
  }, {
    "ean": "1180120SL-2628-42",
    "stock": "5"
  }]
}'

Step 3: Fulfill Orders

Apps and Automations > Build a Private Sales Channel App > Inventory and Product Availability-Page-3 (1).png

The customer places an order on your Sales channel. You verify if the payment is captured in case of a prepaid order, or verify contact information or any other checks in case of Pay On Delivery order.
You send all the confirmed orders to Eshopbox for fulfillment.
Eshopbox will plan shipments for the order. Sometimes multiple shipments are created against a single order. This can happen for various reasons
1. if the inventory for the ordered product is not available in one location
2. all the items can’t be fit into one shipment due to packaging restrictions
3. one of the items is not available and may be shipped later.
Eshopbox will start processing the items and create an invoice for each shipment.
Eshopbox will assign the shipping provider and mark it as Ready to Ship.
Once the shipping provider picks up the shipment from Eshopbox FC, it will be marked as Shipped.
Eshopbox tracks the status of the shipment in the shipping provider network
The shipping provider delivers the shipment.
At any of the steps if Eshopbox may sideline the order if
1. the inventory is not available for items ordered
2. the shipping address in the order is not serviceable
  You may get in touch with the customer and make appropriate changes to order so that it can be fulfilled.

Submit an order for fulfillment

Following are the steps that need to be implemented in your app to automate the submission of orders for fulfillment

Track for any new confirmed orders on your sales channel.
Submit this order for fulfillment to Eshopbox by sending a POST request to the Order endpoint.
POST 'http://wms.eshopbox.com/api/order
please use auto-generated channel code as created in the Eshopbox workspace while enabling a new sales channel. (LINK)
Make sure your pricing information submitted along with order complies for following cases -
- Cart discounts
- Item discounts
- Shipping fees
- Part payments
- Gift cards
- Loyalty points
In case you want to want certain items of the shipments to be shipped together?or don’t want Eshopbox to split shipments
In case you want to assign FC

Tracking fulfillment status

Following are the steps that need to be implemented in your app to automate the submission of orders for fulfillment

To register a webhook, send a POST request to Webhook endpoint.
POST 'https://{workspace}.myeshopbox.com/api/v1/webhook'
where {workspace} is your workspace name

Eshopbox will send updates to the registered webhook URL whenever a shipment is created, canceled, delayed, delivered, in transit, dispatched, delivery is failed, out for delivery, packed, pickup pending, return to origin(RTO), RTO in transit. Sample event when a shipment is created

curl --location --request POST 'shipment_created' \
--header 'Content-Type: application/json' \
--data-raw '{
	"eventType":"shipment_created",
	"externalShipmentID":"300008696_1",
	"externalChannelID": "CLIENT",	
	"externalWarehouseID":"BDGUR103",
	"notificationDatetime":"2018-04-06T09:28:03Z",
	"attributes":{
		"status":"CREATED",
		"statusUpdatedAt":"2018-04-06T08:28:03Z",
		"customerOrderNumber":"300008696",
		"boxType":"NC25",
		"isGift":"0",
		"paymentType":"Pre-Paid",
		"items": [
			{
			    "lineItemSequenceNumber": 2331,
			    "itemID": "5050406281126",
			    "quantity": 1,
			    "productName": "Chinley Walk",
			    "customerPrice": 2220,
			    "lineItemTotal": 2620,
			    "taxRate": 18,
			    "taxAmount": 400,
			    "giftMessage": "",
			    "giftLabelContent":"",
				"lineItemOrderStatus":""
			    
			},
			{
			    "lineItemSequenceNumber": 2332,
			    "itemID": "5050407947922",
			    "quantity": 1,
			    "productName": "Cushox Step",
			    "customerPrice": 3172,
			    "lineItemTotal": 3919,
			    "taxRate": 18,
			    "taxAmount": 747,
			    "giftMessage": "",
			    "giftLabelContent":""
			    
			}
		]
	}
}'

Fetching Invoice

For each shipment Eshopbox will generate an invoice, you can fetch the invoice details by sending a GET request to Invoice endpoint.

http://wms.eshopbox.com/api/invoice-detail/{customerOrderNumber}

Cancellations

Apps and Automations > Build a Private Sales Channel App > Inventory and Product Availability-Page-6 (1).png

When a customer cancels the order, your app is required to send a cancellation request to Eshopbox.
Eshopbox will process the cancellation and send an update to your app.
Eshopbox may cancel the order when inventory is not available or address is not serviceable, in these cases, Eshopbox will send cancellation status to your app.

Request for cancellation from customer

When a customer requests a cancellation, you are required to create a cancellation request in Eshopbox. A customer can cancel the order before the shipment is packed.

To cancel an order, send a POST request to the Order endpoint.
POST http://wms.eshopbox.com/api/cancel-order
You are required to register a webhook so that when the cancellation is processed Eshopbox can update your app.

Cancellation from Eshopbox

You are required to register a webhook so that when Eshopbox cancels an order it can update your app.

To register a webhook, send a POST request to Webhook endpoint.
POST 'https://{workspace}.myeshopbox.com/api/v1/webhook'
where {workspace} is your workspace name.

Eshopbox will send updates to the registered webhook URL. Sample event:

curl --location --request POST 'shipment_cancelled' \
--header 'Content-Type: application/json' \
--data-raw '{
	"eventType":"shipment_cancelled",
	"externalChannelID": "CLIENT",	
	"notificationDatetime":"2018-08-02T18:28:03Z",
	"attributes":{
		"customerOrderNumber":"300008696",
		"status":"CANCELLED",
		"statusUpdatedAt":"2018-04-07T18:18:03Z",
		"items": [
			{
				"lineItemSequenceNumber" : 121,
			    "itemID": "5050406281126",
			    "quantity": 1,
                "remark": "ordered wrong item"
			    
			},
			{
				"lineItemSequenceNumber" : 122,
			    "itemID": "5050407947922",
			    "quantity": 1,
			    "remark": "Bought it from somewhere else"
			    
			}
		]
	}
}'

Step 4: Manage Returns

Apps and Automations > Build a Private Sales Channel App > re-Page-5.png

If there is a return request on your app, you are required to schedule the return and update it to Eshopbox.
Return is created in Eshopbox
Eshopbox will send return status to your app.

Syncing returns with Eshopbox

Whenever there is a return request on your app, then communicate this activity to eshopbox.

To create a return, send a POST request to Return endpoint.
POST 'http://wms.eshopbox.com/api/return'

Track return status

You are required to register a webhook to track the returns. Eshopbox will send updates whenever a return is approved, canceled, received and approved, received and rejected, created, picked up, pickup delay, pickup failed, self-ship, out for pickup, refund initiated, in transit.

To register a webhook, send a POST request to Webhook endpoint.
POST 'https://{workspace}.myeshopbox.com/api/v1/webhook'
where {worskpace} is your workspace name.

Eshopbox will send updates to the registered webhook URL. Sample event when a return is approved:

curl --location --request POST 'return_approved' \
--header 'Content-Type: application/json' \
--data-raw '{
	"eventType":"return_approved",
	"customerReturnNumber":"R3000323",
	"externalChannelID": "CLIENT",
	"notificationDatetime": "2018-08-06 15:20:22",
	"refundAmount" : "2123",
	"attributes":{
		"statusUpdatedAt":"2018-04-17 16:18:27",
		"customerOrderNumber":"403-3131237-00007001",
		"status":"RETURN_APPROVED",
	
    "items":
    [
    	{
    		"lineItemSequenceNumber": 1,
            "orderItemID": "3000012-12184",
            "itemID": "5050407320718",
            "sku": "BBSHOCL35979_10",
            "quantity": "1",
            "returnReason": "customer cancel",
            "additionalInfo":{
            	"image":"",
            	"comments":""
            },
            "itemImage":""
    	}
	]
	}
}
'