Build a Private Sales Channel App

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

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

Steps to build a private sales channel app

Step 1: Set up

Step 2: Sync Products and Inventory

  • 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.

    • 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.

    • 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 Eshopbox fulfillment Center and update such changes in your sales channel catalog.

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.

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

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

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.

https://{workspace}.myeshopbox.com/product-engine/api/v2/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

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 '
[
{
  "inventoryItemId": "21908536-2-38",
  "inventory": 21,
  "productId": null
}
]
'

Update inventory on inventoryItemId.

Step 3: Fulfill Orders

  • 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

    • if the inventory for the ordered product is not available in one location

    • all the items can’t be fit into one shipment due to packaging restrictions

    • 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

    • the inventory is not available for items ordered

    • 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.

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 -

  • 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

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.

Event Subtypes corresponding to which Eshopbox will send updates.

eventSubType

created

packed

dispatched

intransit

delivered

out_for_delivery

delivery_failed

delayed

cancelled

rto

rto_intransit

pickup_pending

  • Sample event when a shipment is created:

curl --location --request POST 'shipment_created' \
--header 'Content-Type: application/json' \
--data-raw ' {
    "customerOrderNumber": "KK100244",
    "vendorOrderNumber": "11920832654052201",
    "externalShipmentID": "KK100244-388-41",
    "externalWarehouseID": "Kapas Kraft Apparels Limited 1006",
    "externalChannelID": "TATA CLIQ VELOCY KAPAS KRAFT",
    "integrationType": "4",
    "defaultWarehouseCode": "2022",
    "orderDate": "2020-07-28 08:10:53",
    "portal_id": 12,
    "paymentType": "ONLINE",
    "order_id": 1971482,
    "channel_id": 388,
    "warehouse_id": 77,
    "account_id": 167,
    "region": "",
    "invoiceNumber": "INV-20/2110138",
    "boxType": "UNKNOWN",
    "isPriorityShipment": "0",
    "isGift": "0",
    "invoice_url": "",
    "invoiceDate": "2020-07-29 00:00:00",
    "label_url": "https://pyck-res-bucket.s3.amazonaws.com:443/DELHIVERY/2020-07-29/2098310542415.pdf",
    "labels": "",
    "shippingInfo": [],
    "boxAdditionalRecommendation": [],
    "dimension_length": "1",
    "dimension_width": "1",
    "dimension_height": "1",
    "weight": "431",
    "trackingID": "2098310542415",
    "packageID": "",
    "barcode": "",
    "courierName": "Delhivery",
    "created_at": "2020-07-28 13:44:23",
    "updated_at": "2020-07-29 10:42:33",
    "status": "dispatched",
    "remarks": "",
    "customerName": "John Doe",
    "customerContactNumber": "9998889998",
    "email": "johndoe@gmail.com",
    "channelSlug": "kapasKraft",
    "status_updated_at": "2020-07-29 11:26:50",
    "status_log": {
      "dispatched": "2020-07-29 11:26:50",
      "packed": "2020-07-29 10:42:38",
      "created": "2020-07-28 13:44:23"
    },
    "orderExternalCreatedAt": "2020-07-28 13:44:18",
    "shippingAddress": {
      "customerName": "John Doe",
      "addressLine1": "Kapas Kraft Apparels Limited",
      "addressLine2": "Banglore",
      "city": "bengluru",
      "state": "Karnataka",
      "postalCode": "560005",
      "countryCode": "IN",
      "countryName": "India",
      "contactPhone": "9998889998",
      "email": "johndoe@gmail.com"
    },
    "id": 1958732,
    "isCOD": "0",
    "track_payload": [],
    "packed_date": "2020-07-29 10:42:38",
    "items": [
      {
        "lineItemSequenceNumber": 57,
        "orderItemID": "BLCK103443-3781063",
        "itemID": "5df8c063737b791c70e35974",
        "sku": "BBAPLBB140117_40",
        "customerOrderItemID":"",
        "asin": "",
        "productName": "Men Black T-Shirt",
        "quantity": 1,
        "customerPrice": 499,
        "lineItemTotal": 499,
        "invoiceTotal": 499,
        "discount": 0,
        "taxRate": 0,
        "taxAmount": 0,
        "giftMessage": "",
        "giftLabelContent": "",
        "lineItemOrderStatus": "",
        "orderItemIDs": [
          "KK100244-5926961"
        ],
        "productImageUrl": "https://s3-eu-west-1.amazonaws.com/imagebucketeshopbox/Uzip/219045371-1-40/1.JPG",
        "productAdditionalInfo": {
          "size": "M",
          "color": "NA"
        },
        "expectedDeliveryDate": "2020-07-30",
        "shippingCharges": 0,
        "productUrl": "https://kapaskraft.auperator.co/product/edit-product/BBAPLMC144105_44"
      },
      {
        "lineItemSequenceNumber": 58,
        "orderItemID": "BLCK103443-3781067",
        "itemID": "5ebe805b34623261ac57dab8",
        "sku": "BBAPLBB140117_40",
        "customerOrderItemID":"",
        "asin": "",
        "productName": "Men Black T-Shirt",
        "quantity": 1,
        "customerPrice": 499,
        "lineItemTotal": 499,
        "invoiceTotal": 499,
        "discount": 0,
        "taxRate": 0,
        "taxAmount": 0,
        "giftMessage": "",
        "giftLabelContent": "",
        "lineItemOrderStatus": "",
        "orderItemIDs": [
          "KK100244-5926962"
        ],
        "productImageUrl": "https://s3-eu-west-1.amazonaws.com/imagebucketeshopbox/Uzip/219045371-1-40/1.JPG",
        "productAdditionalInfo": {
          "size": "XL",
          "color": "NA"
        },
        "expectedDeliveryDate": "2020-07-30",
        "shippingCharges": 0,
        "productUrl": "https://kapaskraft.auperator.co/product/edit-product/BBAPLMC144105_44"
      }
    ]
  }

Events will be pushed shipment status wise and each item object will have one quantity

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}

You can fetch the invoice pdf by sending a GET request to Invoice PDF endpoint

http://wms.eshopbox.com/api/fetchInvoicePDF/{customerOrderNumber}

Cancellations

  • 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 the 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 status is packed.

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.

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 ' {
    "customerOrderNumber": "KK100244",
    "vendorOrderNumber": "11920832654052201",
    "externalShipmentID": "KK100244-388-41",
    "externalWarehouseID": "Kapas Kraft Apparels Limited 1006",
    "externalChannelID": "TATA CLIQ VELOCY KAPAS KRAFT",
    "integrationType": "4",
    "defaultWarehouseCode": "2022",
    "orderDate": "2020-07-28 08:10:53",
    "portal_id": 12,
    "paymentType": "ONLINE",
    "order_id": 1971482,
    "channel_id": 388,
    "warehouse_id": 77,
    "account_id": 167,
    "region": "",
    "invoiceNumber": "INV-20/2110138",
    "boxType": "UNKNOWN",
    "isPriorityShipment": "0",
    "isGift": "0",
    "invoice_url": "",
    "invoiceDate": "2020-07-29 00:00:00",
    "label_url": "https://pyck-res-bucket.s3.amazonaws.com:443/DELHIVERY/2020-07-29/2098310542415.pdf",
    "labels": "",
    "shippingInfo": [],
    "boxAdditionalRecommendation": [],
    "dimension_length": "1",
    "dimension_width": "1",
    "dimension_height": "1",
    "weight": "431",
    "trackingID": "2098310542415",
    "packageID": "",
    "barcode": "",
    "courierName": "Delhivery",
    "created_at": "2020-07-28 13:44:23",
    "updated_at": "2020-07-29 10:42:33",
    "status": "cancelled",
    "remarks": "",
    "customerName": "John Doe",
    "customerContactNumber": "9998889998",
    "email": "johndoe@gmail.com",
    "channelSlug": "kapasKraft",
    "status_updated_at": "2020-07-29 11:26:50",
    "status_log": {
      "created": "2020-07-28 13:44:23"
    },
    "orderExternalCreatedAt": "2020-07-28 13:44:18",
    "shippingAddress": {
      "customerName": "John Doe",
      "addressLine1": "Kapas Kraft Apparels Limited",
      "addressLine2": "Banglore",
      "city": "bengluru",
      "state": "Karnataka",
      "postalCode": "560005",
      "countryCode": "IN",
      "countryName": "India",
      "contactPhone": "9998889998",
      "email": "johndoe@gmail.com"
    },
    "id": 1958732,
    "isCOD": "0",
    "track_payload": [],
    "packed_date": "2020-07-29 10:42:38",
    "items": [
      {
        "lineItemSequenceNumber": 57,
        "orderItemID": "BLCK103443-3781063",
        "itemID": "5df8c063737b791c70e35974",
        "customerOrderItemID":"",
        "sku": "BBAPLBB140117_40",
        "asin": "",
        "productName": "Men Black T-Shirt",
        "quantity": 1,
        "customerPrice": 499,
        "lineItemTotal": 499,
        "invoiceTotal": 499,
        "discount": 0,
        "taxRate": 0,
        "taxAmount": 0,
        "giftMessage": "",
        "giftLabelContent": "",
        "lineItemOrderStatus": "",
        "orderItemIDs": [
          "KK100244-5926961"
        ],
        "productImageUrl": "https://s3-eu-west-1.amazonaws.com/imagebucketeshopbox/Uzip/219045371-1-40/1.JPG",
        "productAdditionalInfo": {
          "size": "M",
          "color": "NA"
        },
        "expectedDeliveryDate": "2020-07-30",
        "shippingCharges": 0,
        "productUrl": "https://kapaskraft.auperator.co/product/edit-product/BBAPLMC144105_44"
      },
      {
        "lineItemSequenceNumber": 58,
        "orderItemID": "BLCK103443-3781067",
        "itemID": "5ebe805b34623261ac57dab8",
        "sku": "BBAPLBB140117_40",
        "customerOrderItemID":"",
        "asin": "",
        "productName": "Men Black T-Shirt",
        "quantity": 1,
        "customerPrice": 499,
        "lineItemTotal": 499,
        "invoiceTotal": 499,
        "discount": 0,
        "taxRate": 0,
        "taxAmount": 0,
        "giftMessage": "",
        "giftLabelContent": "",
        "lineItemOrderStatus": "",
        "orderItemIDs": [
          "KK100244-5926962"
        ],
        "productImageUrl": "https://s3-eu-west-1.amazonaws.com/imagebucketeshopbox/Uzip/219045371-1-40/1.JPG",
        "productAdditionalInfo": {
          "size": "XL",
          "color": "NA"
        },
        "expectedDeliveryDate": "2020-07-30",
        "shippingCharges": 0,
        "productUrl": "https://kapaskraft.auperator.co/product/edit-product/BBAPLMC144105_44"
      }
    ]
  }

Step 4: Manage Returns

  • 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.

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 created, picked up, pickup pending, pickup cancelled, out for pickup, in transit.

Event Subtypes corresponding to which Eshopbox will send updates.

eventSubType

created

approved

picked_up

out_for_pickup

pickup_cancelled

pickup_pending

intransit

delivered

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 'pickup_cancelled' \
--header 'Content-Type: application/json' \
--data-raw '{
    "externalChannelID": "TATA CLIQ VELOCY KAPAS KRAFT",
    "customerReturnNumber": "R4191129_1",
    "customerOrderNumber": "300975272",
    "order_id": 1869913,
    "pickupType": "reverse",
    "status": "pickup_cancelled",
    "refundAmount": 0,
    "cp_id": 25,
    "channel_id": 271,
    "expectedPickupDate": "",
    "trackingID": "1704610521931",
    "courierName": "EcomExpress Reverse",
    "customerName": "Sam",
    "customerContactNumber": "999999999",
    "email": "sam@gmail.com",
    "remarks": "Not attempted",
    "isCOD": "1",
    "channelSlug": "kapaskraft",
    "accountSlug": "kapaskraft",
    "pickupAddress": {
      "pickup_customerName": "Sam",
      "pickup_addressLine1": "Green Soul, reliable space",
      "pickup_addressLine2": "thane",
      "pickup_city": "Thane",
      "pickup_state": "Maharashtra",
      "pickup_postalCode": "421501",
      "pickup_countryCode": "IN",
      "pickup_countryName": "India",
      "pickup_contactPhone": "999999999",
      "pickup_email": "sam@gmail.com"
    },
    "dropAddress": {
      "drop_name": "Eshopbox Patli Gurgaon",
      "drop_address": "MJ Logistics Private Limited, Seabird Marine Services Pvt Ltd,Village Babra Bakirpur, Pataudi Road Near Adani Logistic Park,  ICD Patli, Gurgaon, Haryana(122503)",
      "drop_pincode": "122503",
      "drop_city": "Gurgaon",
      "drop_country": "India",
      "drop_state": "Haryana"
    },
    "latest_status": "pickup_cancelled",
    "status_updated_at": "2020-07-20 18:40:54",
    "status_log": {
      "pickup_cancelled": "2020-07-20 18:40:54",
      "out_for_pickup": "2020-07-20 09:50:39",
      "pickup_pending": "2020-07-19 12:49:42",
      "approved": "2020-07-19 11:54:45",
      "created": "2020-07-19 11:54:41"
    },
    "track_payload": {
      "clickPostTrackData": {
        "additional": {
          "is_rvp": true,
          "latest_status": {
            "clickpost_status_bucket_description": "Order placed",
            "location": "Maharashtra",
            "clickpost_status_bucket": 1,
            "remark": "Not attempted",
            "clickpost_status_code": 3,
            "clickpost_status_description": "PickupFailed",
            "status": "Scheduled",
            "timestamp": "2020-07-20T18:36:02Z",
            "reference_number": "R2711595139881136"
          }
        },
        "account_code": "EcomExpress Reverse",
        "location": "Maharashtra",
        "waybill": "1704610521931",
        "remark": "Not attempted",
        "status": "Scheduled",
        "clickpost_status_description": "PickupFailed",
        "cp_id": 25,
        "clickpost_status_code": 3,
        "timestamp": "2020-07-20T18:36:02Z"
      }
    },
    "items": [
      {
        "lineItemSequenceNumber": 331,
        "orderItemID": "300975273736427",
        "itemID": "5050410512025",
        "customerOrderItemID":"",
        "productName": "Burgandy Derby Leather shoes",
        "quantity": 1,
        "lineItemTotal": 2997,
        "discount": 0,
        "returnReason": "Received a different item",
        "item_image": "",
        "additionalInfo": "{\"customerUploadImageUrl\":\"\",\"comment\":\"\"}",
        "returnType": "refund",
        "productImageUrl": "https://cdn.schema.io/kapaskraft/5d52ab4fb051864dc113460e/dbe1d4a100607c5823ea30114834e39c",
        "productAdditionalInfo": {
          "size": "8",
          "color": "Burgandy"
        },
        "shippingCharges": 0,
        "productUrl": "kapaskraft.com/products/id/burgandy-derby-leather-shoes-bbshobb140952",
        "isExchange": "0"
      }
    ]
  }

Last updated