BigCommerce Channel Setup

The purpose of this integration is to allow retailers with one or more BigCommerce (BC) Storefronts to use CORESense (CS) for order, product and inventory management, order fulfillment and point of sale.

Request Development to setup BigCommerce as a channel in the client’s Backoffice:

Run patchify or import 2021-04-01-dev-278-bigcommerce.sql and 2021-08-09-dev-278-product-export-update.sql SQL changes.
Enable BigCommerce Module by adding a boolean value $CONFIG['channels']['bigcommerce']['enabled'] = true; to config.inc.

Setup Braintree account

Setup Braintree account for credit card processing
Setup MiniBC account – this is used to capture the credit card information needed by CORESense to capture payments and issue refunds.

Prep for Setup of BigCommerce Storefront integration in CORESense

Create BigCommerce API account
1. This process must be completed by a BigCommerce User with the ‘Store Owner’ designation.
2. Go to Advance Settings -> API Accounts -> Create API Account -> Create V2/V3 API Token.
  1. Set the Permissions as shown in Appendix A: BC Access Permissions
  2. Once you complete the process per instruction found in BigCommerce, save the settings and then copy down the following fields:
    1. Access Token
    2. Client Id
    3. Store URL
    4. Store Hash
Create a new BigCommerce channel using the backoffice config tool.
Create order item custom fields for the BC Gift Certificate Code and BC Gift Wrapping Message, if being used.
Create CORESense ‘Digital’ Type products to use for BC Gift Certificates and Gift Wrapping.
Go to Technical Configurations and create a new Order Status for BigCommerce Order exceptions and Return exceptions. These are used to flag Orders or Returns imported from BigCommerce that have an exception that did not allow them to import/export all information.

Setup the new BigCommerce Store Channel

Go to System Setting Manager -> Channels -> BigCommerce
1. Select the channel just created from the dropdown menu.
2. Enter following API fields and select save:
  - Access Token
  - Client Id
  - Store URL
  - Store Hash
  - MininBC Access Token - Required if you want do payment capture and refund in CORESense. Only works with Braintree.
Clicking on Save button will start the integration process which includes attaching webhooks, importing category and order statuses.
Goto System Settings>Payment Processors>Link Merchant Accounts with Channels and map the Braintree Merchant Account to the BC channel

Create BigCommerce Data Feeds

Go to Data Feed Manager and create 3 exports and 1 import feed.
1. Export Feeds
  - Create feed for BigCommerce Product Export, BigCommerce Inventory Update and BigCommerce Return Export feed type with invocation set to Scheduled
2. Import Feed
  - Create a feed for BigCommerce Order Import Feed Type with Invocation Triggered and ensure to add one Local Transport Method with arbitrary filename into it.

Complete Setup of the New BigCommerce Store Channel

Category Mapping - Map BigCommerce categories to CORESense Categories
Default User: - CORESense use that will be assigned as the salesman for orders import from BigCommerce.
Exception Order Status: Order status to be assigned in the event of an error during order import.
Exception Return Status: Return status to be assigned in the event of an error during return import.
Gift Certificate Code Custom Field: Choose order item custom field to map with gift certificate.
Gift Certificate Product Mapping: Choose CORESense product id to map BigCommerce Gift Certificates too.
Gift Wrapping Message Custom Field: Choose order item custom field to map with gift certificate.
Gift Wrapping Product: Choose CORESense product id to map BigCommerce Gift Wrapping too.
Inventory Update Feed: Select Inventory data feed.
Limit Available Warehouses: Select warehouse(s) to use for inventory feed.
Order Import Feed: Select order import data feed.
Order Locking: Indicate whether orders should be locked on import.
Order Status for Import: BigCommerce order status for import into CORESense.
Order Status Mapping: Mapping of CORESense order status to BigCommerce. CORESense will update order status in BigCommerce based on this mapping.
Payment Method Mapping: Map BigCommerce payment methods to CORESense receivable types.
Product Custom Fields: Map CORESense Product General Attribute Custom fields that will be exported to BigCommerce in product export feed.
Product Image Fields: Select additional image fields to be exported to BigCommece in product export feed.
Shipping Method Mapping: Map CORESense and BigCommerce shipping methods.
Payment Method Mapping: Map BigCommerce Payment Methods to CORESense Receivable Types and payment processor.
1. internet class payment types (e.g., PayPal (Braintree), ApplePay (Braintree), Sezzle) should be mapped to BC API.
2. The BC API payment processor is created under Payment Processor using the BigCommerce processor type. This needs to be done before Payment Method Mapping.
Unlimited Stock Level: Enter quantity to send if a CORESense SKU is designated as 'unlimited' qty.
Variant Options Mapping: Specify BigCommerce option type and sort order for CORESense configurations.
Reset BigCommerce Data Feeds - Specify Product ID or leave blank to refresh all inventories in your BigCommerce store. This is going to take a while depending upon number of products enabled for this channel.
BigCommrce Misc Tools
1. Refresh Order Statuses - Refreshes the BigCommerce order statues selectable in Order Status for Import.
2. Refresh Categories - Refreshes the BigCommerce categories selectable in the Category Mapping.
3. Refresh Failed Order Import Queue - Sends failed orders back to import queue for import.
  1. The Setup>Technical Configuration>Bigcommerce Order Import Queue table shows orders that are queued for import and their status including orders that have failed to import.

Setup the BigCommerce specific product channel attributes

For new or existing products, go to Product Manager>Channels>BigCommerce <Channel Name> and complete the BigCommerce specific ‘Channel General Attributes for <Channel Name> (BigCommerce), set via the batch product update or via the data import tool.

CS will support the following BC ‘Channel General Attributes ‘

Active/Inactive – determines, along with models.void whether a product is created or updated in BC. i.e if this setting is Active and models.void is ‘n’, then the product is created and updated in BigCommerce.

Product Visibility – true/false (sets the is_visible field in BigCommerce), True, the product will be displayed. If false, the product will be hidden from view

Availability – available, disabled, preorder

Availability of the product. Availability options are:

available - the product can be purchased on the storefront;
disabled - the product is listed in the storefront, but cannot be purchased;
preorder - the product is listed for pre-orders.
- The user cannot select this option. It set automatically set if Pre-Orders is enabled and the Product Pre-Order flag is set to ‘yes’. If this is the case, the setting is displayed but is greyed out and not editable.

Availability Description – test, max length 255

Availability text displayed on the checkout page, under the product title. Tells the customer how long it will normally take to ship this product, such as: ‘Usually ships in 24 hours

Custom URL - Custom title for the product page. If not defined, the product name will be used as the meta title.

Inventory Tracking - The type of inventory tracking for the product. Values are:

none - inventory levels will not be tracked;
product - inventory levels will be tracked using the inventory_level and inventory_warning_level fields;
variant - inventory levels will be tracked based on variants, which maintain their own warning levels and inventory levels.

Inventory Warning Level - Integer

Inventory warning level for the product. When the product’s inventory level drops below the warning level, the store owner will be informed. ‘product’ inventory tracking must be enabled.

Inventory Availability Calculation:

In Stock
In Stock + On PO – Backordered
In Stock + Vendor Available Inventory (Will vendor quantity only if SKU type is dropship or just-in-time)

Is Condition Shown - Flag used to determine whether the product condition is shown to the customer on the product page.

Is Featured - Flag to determine whether the product should be included in the featured products panel when viewing the store.

Is Free Shipping - Flag used to indicate whether the product has free shipping. If true, the shipping cost for the product will be zero.

Is Price Hidden - Flag to indicate if the product price is hidden

Maximum Order Quantity - The maximum quantity an order can contain when purchasing the product.

Minimum Order Quantity - The minimum quantity an order must contain, to be eligible to purchase this product.

Preorder Only - If set to true then on the preorder release date the preorder status will automatically be removed. If set to false, then on the release date the preorder status will not be removed.

Preorder Message - Custom expected-date message to display on the product page.

Price Hidden Label - If is_price_hidden is true, the value of price_hidden_label is displayed instead of the price. (NOTE: To successfully set a non-empty string value with is_price_hidden set to true, the availability value must be disabled.)

Page Title - Custom title for the product page. If not defined, the product name will be used as the meta title.

Meta Description - Custom meta description for the product page. If not defined, the store’s default meta description will be used.

Meta Keywords - Custom meta keywords for the product page. If not defined, the store’s default keywords will be used.

Release Date - Custom expected-date message to display on the product page.

Sort Order - Priority to give this product when included in product lists on category pages and in search results.

Search Keywords - A comma-separated list of keywords that can be used to locate the product when searching the store.

Tax Class Id - The ID of the tax class applied to the product.

Reset BigCommerce Data Feeds

Specify Product ID or leave blank to refresh all inventories in your BigCommerce store. This is going to take a while depending upon number of products enabled for this channel

BigCommerce Misc Tools

Refresh Orders Statuses: Should be selected after changes to order status mapping.
Refresh Categories: Should be selected after changes to Catropgy mapping.

Integration Notes

Product image should be in common folder (if the path is relative and not absolute). Reason being is, that directory is shared among multiple servers hosted in CS and we would be pre-pending office-spmretail.coresense.com to the image URL and it going to remote downloaded by BigCommerce product import service.
We're associating billing address as order shipping details to particular orders having Gift Certificate purchased because it is mandatory to have shipping address associated to order item in CS.
We try to match customers by BigCommerce ID first, if not matched then we do a lookup on Contact entity by billing address details like first, last, address, city state zip phone and email fields, else we create it and map it otherwise.
While pushing returns to BC, CS will try to match the returned amount with BC first by retrieving a refund quote, if it does match we push it, else we just pass the amount suggested by BC refund quotes.
There is no API available to delete a variant image, alternatively, we could send an empty value to remove that image in the create API but there is a validation on that field so we couldn't do that way either.
In this release, transactions that occurred on BC orders with credit card checkout (without card being saved in customer vault) are only able to handle refunds by Braintree Payment Processor. This means if order's credit card gateway is other than Braintree during checkout, then refund to CC isn't doable.
MiniBC (A replacement cart checkout experience with the ability to vault customer's credit card) is tightly coupled with this integration due to the requirement.
Returns processed in CS will be exported to BC
Edits made to Orders in CS are not synched to BC

Additional Notes

We're doing a batch import of the orders (cap limit is 50 on every cycle i.e max 50 can be imported at a time) since the last order was found. Let's say BC has 1000 orders our CRON ran and stored the timestamp of the last order. Reason for this is to insure there is adequate time for mininBC to return payment token.
BC Staff Notes show up in both the Order Manager and Customer Manager under ‘Support’ Comments.
The BC ‘orderId’ is saved on the CS Order in the Salesman Info section.
If order is Voided in CS, the Order will be marked as ‘Cancelled’ in BC.
If the order is canceled in BC, then, optionally the Order in CS will be voided, if it can be voided.
When BC is enabled in a CS back office, a ‘Promotional Discount’ Deal is created called ‘BC Order Item Disc’. All BC applied_discounts are associated with the ‘BC Order Item Disc’ Deal.
When BC is enabled in a CS back office, an Order Deal is created called ‘BC Order Disc’ and an Order Shipping Deal is created called ‘BC Shipping Disc.’.
All BC Coupon Codes are associated with the ‘BC Order Deal’ or the ‘BC Order Shipping Deal’.
BigCommerce has validation on Product Title which means duplicate product name aren’t allowed.
Swatch Images - It is mandatory to set swatch images on every option value under the swatch option type at BigCommerce side. If any of the standard/upgrade fields doesn't have an image updated then changes can't be seen on BC after feed export. For the sake of consistency swatch image should have the flexibility to be used in the following order:
1. System will try to pick an image from "Main Image" field for the corresponding configuration option.
2. If not above, then "Swatch Image" will be used.
3. If not then variant main image will be used.
4. If it gets fail to pick any of the 3 possible options above then Variant option wouldn't be set as swatch.

Trouble Shooting

Errors found during import are noted under Order History comments and the order will be placed into an exception status.

A typical error is 'no product found' which means the order came into CORESense with a product that does not exist in CORESense. This generally happens when a product is added in BC but not CORESense. All products need to be created in CORESense and exported to BC. This creates the entry in the Setup>Technical Configuration>BigCommerce Entity Relation table. This table is used by CORESense to match products and configurations coming in from BC with the correct product in CORESense.

Data Feed errors can be viewed in the Setup>Technical Configurations>Data Feed Errors table. Search by Data Feed Id which can be found in the Data Feed or Data Feed Export tables.

The Bigcommerce Order Import Queue table in Setup technical configuration shows orders that are queued for import and their status including orders that have failed to import.

In Data Feed Manager under History, clicking View will bring up the logs for that data feed import. This may also provide information on data feed errors.