ChannelAdvisor Integration Overview

Purpose: Order Management System’s integration with ChannelAdvisor enables you to fulfill orders through the Amazon marketplace. This integration includes:

• sending items/SKUs and their available quantities to ChannelAdvisor: A periodic function creates a file to send all items/SKUs in your company to ChannelAdvisor, indicating the current available quantity of each. A system control value indicates the available quantity to include for non-inventory items, drop ship items, and other items without an inventory requirement, such as virtual gift cards and memberships. Each item/SKU is identified by a cross-reference code, if you have set it up; otherwise, the short SKU code is used. See Sending Current Inventory Information to ChannelAdvisor for details.

Note: The information sent to ChannelAdvisor includes only the short SKU or cross-reference code and the available quantity. It does not include item descriptions, images, or any other information.

• sending current pricing to ChannelAdvisor: A periodic function creates a file to send item/SKU pricing to ChannelAdvisor. Prices are from the Original Retail $ and List Price from the SKU record; you can also include a third price from your ChannelAdvisor offer. Only items/SKUs that are associated with your ChannelAdvisor offer are included. See Sending Current Prices to ChannelAdvisor for details.

• receiving orders from ChannelAdvisor: A periodic function sends a message requesting a list of orders from ChannelAdvisor and then uses the information in the response message to create each order in Order Management System, using a predefined order type as well as mapped values such as source code, ship via, and pay type. See Importing Orders from ChannelAdvisor for details.

• sending shipment confirmations to ChannelAdvisor: A periodic function sends a shipment confirmation message to ChannelAdvisor for each shipment of a ChannelAdvisor order. See Sending Shipment Confirmations to ChannelAdvisor for details.

• sending refund notifications to ChannelAdvisor: The Process Refunds function sends a message to ChannelAdvisor for each refund generated for a ChannelAdvisor order. When the function receives a confirmation response from ChannelAdvisor, it sets the refund to a processed status but does not actually generate the refund. See Submitting Refunds for ChannelAdvisor Orders for details.

Note: The ChannelAdvisor integration has been designed and tested to work for the Amazon Marketplace. To use the ChannelAdvisor integration with a marketplace other than Amazon, contact your Order Management System project manager.

Troubleshooting the ChannelAdvisor integration:

• Logging: The name of the log used for all communication with ChannelAdvisor is INTEGRATIONORDER, and the INTEGRATIONORDER_LOG_LEVEL controls the level of detail to include. Set this level to DEBUG to include details on all activity and to log all messages.

• Setup issues? See ChannelAdvisor Setup for details on the setup required for the integration. Also, each of the process overviews that follow include a summary of related setup.

In this chapter:

• Sending Current Inventory Information to ChannelAdvisor

• Sending Current Prices to ChannelAdvisor

• Importing Orders from ChannelAdvisor

• Sending Shipment Confirmations to ChannelAdvisor

• Submitting Refunds for ChannelAdvisor Orders

See also: ChannelAdvisor Setup.

Sending Current Inventory Information to ChannelAdvisor

Purpose: You send current inventory information to ChannelAdvisor through a periodic function that generates a file and transfers it to your SFTP server so that the ChannelAdvisor account can apply the inventory updates. The steps are described below.

Note: The periodic function does not include any additional information about the items/SKUs, such as descriptions or images.

A. Run the CAINV periodic function. The CAINV periodic function:

1. Creates a file: Creates a pipe-delimited file in the CA_INVENTORY_FILE_LOCAL_FOLDER on the Order Management System server, using the CA_INVENTORY_FILE_NAME.

If there is already a file of the specified name in that folder, the function overwrites it.

Note: You should create the CA_INVENTORY_FILE_LOCAL_FOLDER on your server if the folder does not already exist.

• Which items included? Includes all items and SKUs in the company, except for any items that are sold out or flagged as restricted. Items do not need to have records in your current ChannelAdvisor offer. The items are in alphanumeric order based on their original item code.

• Identifying items and SKUs: Identifies the item/SKU in the file with:

- the SKU Cross Reference record, if any, set up through Maintaining SKU Cross Reference Codes (MSKR) for the item/SKU and the ChannelAdvisor SKU X-Ref Offer (L92); otherwise,

- the short SKU for the item, if there is no SKU Cross Reference record for the item/SKU and ChannelAdvisor SKU X-Ref Offer (L92), or if that system control value is blank. If some but not all items/SKUs in your company have SKU Cross Reference records, then the file includes a combination of cross references and short SKUs.

• Calculating the available quantity:

- Standard calculation: Uses the standard availability calculation to determine the quantity to report to ChannelAdvisor (On hand - reserved - protected - reserve transfer quantity - backorder quantity), and indicates a quantity of zero if the result of this calculation is a negative number.

- Set items: Based on the set component with the lowest availability. For example, a set includes one unit of component AB100 with 100 units available and two units of item CD200 with 50 units available. The available quantity of the set is calculated as 25, since there are enough units of CD200 to make 25 sets.

- Include non-allocatable warehouses? Uses the Include Non-Allocatable Warehouses (I34) system control value to determine whether to include inventory in warehouses that are not flagged as Allocatable when calculating the available quantity in the inventory download file.

- Non-inventory? Uses the ChannelAdvisor Inventory Level Default (L91) as the available quantity for:

* items flagged for drop ship, regardless of whether they have an available quantity in the warehouse. A drop ship item might have a quantity in the warehouse if, for example, you received a return.

* non-inventory items, including virtual stored value cards, membership items, and subscription items

Note: A quantity of zero is always indicated for variable sets. As a result, you cannot sell these items through ChannelAdvisor.

Sample file contents: In the sample lines below, 1234619 is a short SKU, CACIN12345 is a SKU cross reference set up through Maintaining SKU Cross Reference Codes (MSKR), and the Quantity indicated for each (the last column) is the available quantity. The text UNSHIPPED is included as the Quantity Update Type for each item/SKU in the file.

Inventory Number|Quantity Update Type|Quantity

1234619|UNSHIPPED|13

CACIN12345 |UNSHIPPED|53

Note: The SKU cross references include trailing spaces up to the maximum field length of 40 positions.

2. Transfers the file to your SFTP server: The function copies the inventory file from your Order Management System server to the FTP Address + FTP Inventory Folder + CA_INVENTORY_FILE_NAME, using the FTP Username and FTP Password for access to the SFTP server. These settings are from the ChannelAdvisor account you have set up for your company using the Working with ChannelAdvisor Accounts (WCAA) option.

A copy of the inventory file remains on your Order Management System server until you delete it or replace it with an updated file.

B. ChannelAdvisor pulls the inventory file from your SFTP server. In ChannelAdvisor, you might set up and schedule an Inventory (pull) under Inventory > Settings > FTP/HTTP settings, where:

• URL = SFTP + FTP Address + FTP Inventory Folder + CA_INVENTORY_FILE_NAME

• File type = Pipe delimited

• Username and password = FTP Username and FTP Password

• File processing = All

• Apply Template = No Template Selected

Setup summary: To support the inventory upload to ChannelAdvisor, you need to complete the following setup:

• Create the CAINV periodic function and assign it to a scheduled periodic process.

• Specify the CA_INVENTORY_FILE_LOCAL_FOLDER and CA_INVENTORY_FILE_NAME.

Note: You should create the CA_INVENTORY_FILE_LOCAL_FOLDER on your server if the folder does not already exist.

• Use the Working with ChannelAdvisor Accounts (WCAA) option to specify your ChannelAdvisor account settings, including information on connecting to your SFTP server.

• If you are using a proxy server, define a PROXY_HOST and PROXY_PORT.

• To identify items/SKUs using cross references rather than short SKU numbers in ChannelAdvisor:

- Create a ChannelAdvisor offer and assign it to the ChannelAdvisor SKU X-Ref Offer (L92) system control value.

- Use the Maintaining SKU Cross Reference Codes (MSKR) option to assign cross reference codes.

• To control the availability calculation:

- Use the Include Non-Allocatable Warehouses (I34) system control value to determine whether to include inventory in warehouses that are not flagged as Allocatable when calculating the available quantity in the inventory download file.

- Use the ChannelAdvisor Inventory Level Default (L91) as the available quantity for drop ship and non-inventory items.

• Complete inventory (pull) setup in ChannelAdvisor as described above.

For more information: See ChannelAdvisor Setup for background on setup.

Sending Current Prices to ChannelAdvisor

Purpose: You send current pricing information to ChannelAdvisor through a periodic function that generates a file and transfers it to your SFTP server so that the ChannelAdvisor account can apply the pricing updates. The steps are described below.

A. Run the CAPRICE periodic function. The CAPRICE periodic function:

1. Creates a file: Creates a pipe-delimited file in the Local Price Folder on the Order Management System server, using the Price Filename. Both of these settings are from your entries for your ChannelAdvisor account through the Working with ChannelAdvisor Accounts (WCAA) option.

If there is already a file of that name in that folder, the function overwrites it.

• Which items included? The price file includes only items and SKUs in that are included in your current ChannelAdvisor offer. If the item has SKUs, and:

- if there is an Item Offer record and an Item Price record, but no SKU Offer or SKU Price records for any SKUs, then all SKUs are included.

- if there are any SKU Offer and SKU Price records for any SKUs, then only the SKUs with SKU Offer and SKU Price records are included.

To prevent a situation in which some SKU’s might be included in the file without prices, do not create an Item Offer without also creating an Item Price.

• Identifying items and SKUs: The function identifies the item/SKU in the file with:

- the SKU Cross Reference record, if any, set up through the Maintaining SKU Cross Reference Codes (MSKR) for the item/SKU and the ChannelAdvisor SKU X-Ref Offer (L92); otherwise,

- the short SKU for the item, if there is no SKU Cross Reference record for the ChannelAdvisor SKU X-Ref Offer (L92), or if the system control value is blank.

• Which prices are included? The file includes:

- Buy It Now Price: from the Original retail $ in the SKU table.

- Retail Price: from the List price in the SKU table.

- Additional price: from the most current SKU Price (based on Effective date), if any, for your ChannelAdvisor offer; otherwise, from the most current Item Price. The label of this price field is from the Price output name specified for the ChannelAdvisor offer through the Work with ChannelAdvisor Offers Screen option.

Sample file contents: In the sample lines below, 1234619 is a short SKU, and CACIN12345 is a SKU cross reference set up through the Maintaining SKU Cross Reference Codes (MSKR). The prices are derived as described above.

Inventory Number|Buy It Now Price|Retail Price|second chance offer price

CACIN12345 |11.11|13.13|7.77

1234619|1.99|1.5|1.11

Note: The SKU cross references include trailing spaces up to the maximum field length of 40 positions.

2. Transfers the file to your SFTP server: The function copies the price file from your Order Management System server to the FTP Address + FTP Price Folder + Price Filename, using the FTP Username and FTP Password for access to the SFTP server. These settings are from the ChannelAdvisor account you have set up for your company using the Working with ChannelAdvisor Accounts (WCAA) option.

A copy of the price file remains on your Order Management System server until you delete it or replace it with an updated file.

B. ChannelAdvisor pulls the price file from your SFTP server. In ChannelAdvisor, you might set up and schedule an Inventory (pull) under Inventory > Settings > FTP/HTTP settings, where:

• URL = SFTP + FTP Address + FTP Price Folder + Price Filename

• File type = Pipe delimited

• Username and password = FTP Username and FTP Password

• File processing = All

• Apply Template = No Template Selected

Setup summary: To support the price upload to ChannelAdvisor, you need to complete the following setup:

• Create the CAPRICE periodic function and assign it to a scheduled periodic process.

• Use the Working with ChannelAdvisor Accounts (WCAA) option to specify your ChannelAdvisor account settings, including information on your SFTP server and the file and folder on your Order Management System where you create the price file.

Note: You should create the Local Price Folder on your server if the folder does not already exist.

• If you are using a proxy server, define a PROXY_HOST and PROXY_PORT.

• To identify items/SKUs using cross references rather than short SKU numbers in ChannelAdvisor:

- Create a ChannelAdvisor offer and assign it to the ChannelAdvisor SKU X-Ref Offer (L92) system control value.

- Use the Maintaining SKU Cross Reference Codes (MSKR) option to assign cross reference codes.

• Use the Work with ChannelAdvisor Offers Screen option to set up your ChannelAdvisor offer, including the Price output field name.

• Specify the Original retail $ and the List price in the SKU table.

• Optionally, set up Item Offer and Price Records and/or SKU Offer and Price Records for each item/SKU you sell through a ChannelAdvisor marketplace to include a third price in the price file, using the Price output name.

• Complete inventory (pull) setup in ChannelAdvisor as described above.

For more information: See ChannelAdvisor Setup for background on setup.

Importing Orders from ChannelAdvisor

Purpose: You can periodically request new orders from ChannelAdvisor through a periodic function, which creates the orders in Order Management System. The steps and details on data mapping are described below.

A. Run the CAORDERUP periodic function. The CAORDUP periodic function:

1. Requests new orders: The function sends the GetOrderListRequest message to ChannelAdvisor, using the CHANNELADVISOR_ORDER_URL specified in the cwdirectcp_interface.properties file and the account number and credentials specified through the Working with ChannelAdvisor Accounts (WCAA) option.

Maximum orders? Each batch can include a maximum of 50 orders. The CHANNELADVISOR_ PULL_ORDERS_MAX property controls how many orders the function processes. For example, set the property to 100 to have the function process a maximum of two full batches.

2. Receives and creates new orders: The function receives new orders from ChannelAdvisor in the GetOrderListResponse message, mapping data as follows:

- company number: From the company number specified for the CAORDUP periodic function.

- order type: from the ChannelAdvisor Order Type (L90).

- source code: from the Source associated with the marketplace originating the order. The function determines the marketplace from the ItemSaleSource passed for the order, and uses the Source for the matching marketplace, as set up through the Work with ChannelAdvisor Marketplaces Screen. Your marketplace needs to match a ChannelAdvisor Site Token value.

- alternate order number: from the CartID.

- entered by user: your default user.

- order message lines: from:

* the ChannelAdvisor client order identifier, preceded by CA; for example, CA#28839571

* your ChannelAdvisor account number; for example, ACCT#cc7bab31-22cc-49d2-a833-be878721520b

* an additional order message line indicating None

These order message lines are flagged not to print (Print Nowhere).

- ship via: from the ship via whose Integration carrier and Integration service class match the ShippingCarrier and ShippingClass passed for the order.

- customer name and address: from the ShippingInfo and BillingInfo passed for the order. If no BillingInfo is passed, the ShippingInfo is used as the sold-to customer information; otherwise, the BillingInfo is used as the sold-to customer information. Some marketplaces may never pass BillingInfo.

* Sold-to different from ship-to? The system searches for a matching sold-to customer using the Include Telephone Number in Customer Search (I20) and Remote Order Values (F70) system control values. If the sold-to customer name and address are different from the ship-to name and address, the periodic function creates an order-level ship-to. The system might change the sold-to customer information to something slightly different from the ship-to name and address passed if it finds a matching customer using your customer search and selection criteria; in this case, an existing sold-to customer who differs somewhat from the ship-to information passed may be assigned to the order. See the Include Telephone Number in Customer Search (I20) and Remote Order Values (F70) system control values for background.

* Business or residence? The Delivery code is set to B for the sold-to or ship-to address if there is a company name; otherwise, the Delivery code is set to R.

* Opt-in/out: If the EmailOptIn from ChannelAdvisor is set to False, the customer’s Opt-in/out flag is set to 03; otherwise, if the EmailOptIn is set to True, the customer’s Opt-in/out flag is set to 01.

* Identifying the country: The periodic function uses the country’s two-position ISO code to map the customer’s country.

- email address: from the BuyerEmailAddress passed for the order.

- items: mapped from the short SKU or the SKU cross reference, as described under Sending Current Inventory Information to ChannelAdvisor.

- shipping and tax: Calculated based on the amounts in the OrderLineItemItem element if the CA type for the pay type is set to Item Level (consistent with the Amazon and eBay with premium tax marketplaces); otherwise, calculated from the amounts in the OrderLineItemInvoice element and prorated across the lines on the order if the CA type for the pay type is set to Order Level (consistent with the eBay marketplace without premium tax). See Working with Pay Types (WPAY) for background.

Note: Tax on freight is included in the line-level or order-level tax amount.

- price override reason for each order line: uses a reason code of W.

- payment method: from the CA cross reference # for a pay type. The function uses the ItemSaleSource passed for an order to identify the marketplace set up through Working with ChannelAdvisor Accounts (WCAA), and assigns the payment method whose CA cross reference # matches the marketplace. Your marketplace needs to match a ChannelAdvisor Site Token value.

- suppress refund flag for the payment method: set to N, so that refunds are not suppressed, and you can use the process described under Submitting Refunds for ChannelAdvisor Orders.

3. Notifies ChannelAdvisor that each order was received: The function sends a status export status update (SetOrderList) to ChannelAdvisor for each received order, indicating that the order was successfully created.

Error? If a new order is in error, it is assigned to the Default Batch for E-Commerce Orders in Error (G41).

Setup summary: In addition to the setup required for the inventory and price uploads, complete the following setup to support the order import:

• Create the CAORDUP periodic function and assign it to a scheduled periodic process.

• Specify the CHANNELADVISOR_ORDER_URL.

• Use the Working with ChannelAdvisor Accounts (WCAA) option to specify your ChannelAdvisor account settings, including your credentials, as well as the marketplaces and their related source codes. Your marketplace needs to match a ChannelAdvisor Site Token value.

• Use Establishing Order Types (WOTY) to set up the ChannelAdvisor order type, and assign it to the ChannelAdvisor Order Type (L90) system control value.

• Use Establishing Price Override Reason Codes (WPOR) to create a price override reason code of W.

• Use Setting Up the Country Table (WCTY) to specify a 2-position ISO country code for each country where you will ship orders.

• Use Working with Pay Types (WPAY) to create a pay type for each marketplace, and assign a CA cross reference # to identify the marketplace to each.

• Use Working with Ship Via Codes (WVIA) to specify the Integration carrier and Integration service class to map ship vias to carriers that might be used for ChannelAdvisor orders.

For more information: See ChannelAdvisor Setup for background on setup.

Changing orders after creation: A pop-up window opens in order maintenance if you attempt to maintain a ChannelAdvisor order, indicating that any changes must also be made in ChannelAdvisor. There is no mechanism to automatically send changes to ChannelAdvisor except for shipment confirmation or refunds.

Sending Shipment Confirmations to ChannelAdvisor

Purpose: You can periodically send order shipment notifications to ChannelAdvisor through a periodic function. described below.

A. Confirm shipment. When billing an order whose order type matches the ChannelAdvisor Order Type (L90), the billing async job creates a CAS trigger record. The trigger record identifies the company, order number, and invoice number for the shipment.

B. Run the CASHIPMENT periodic function. For each unprocessed CAS trigger record, the CASHIP periodic function passes a SubmitOrderShipmentList message:

• Uses the ChannelAdvisor account number and credentials specified through the Working with ChannelAdvisor Accounts (WCAA) option.

• Passes the ChannelAdvisor clientOrderIdentifier to identify the order.

• Always indicates a ShipmentType of Partial.

• Maps each item using the short SKU or the SKU cross reference, as described under Sending Current Inventory Information to ChannelAdvisor, and indicates the Quantity shipped of each item.

• Indicates the trackingNumber for the shipment, if available in the Manifest Upload Audit table. If there are multiple tracking numbers for a shipment, the tracking number that billed first is included.

• Passes the Integration carrier and Integration service class from the ship via used as the ShippingCarrier and ShippingClass.

• Sends the shipment confirmations to the CHANNELADVISOR_SHIPPING_URL.

The message does not specify any shipping charges or a shipment date if different from the current date.

Setup summary: In addition to the setup required for the inventory and price uploads and order import, complete the following setup to support shipment confirmations:

• Create the CASHIP periodic function and assign it to a scheduled periodic process.

• Specify the CHANNELADVISOR_SHIPPING_URL.

For more information: See ChannelAdvisor Setup for background on setup.

Submitting Refunds for ChannelAdvisor Orders

Purpose: When you use the Processing Refunds (MREF) option, the function submits any pending refunds for ChannelAdvisor orders to ChannelAdvisor, and does not actually generate these refunds. The processing steps are described below.

Note: The Processing Refunds by Order Number (MRFO) option does not perform ChannelAdvisor refund processing. You need to use the Processing Refunds (MREF) option.

Identifying ChannelAdvisor orders: To be included, an order must have an order type matches the ChannelAdvisor Order Type (L90) system control value, and its payment method must have an CA cross reference # that matches a marketplace set up through Working with ChannelAdvisor Accounts (WCAA).

Which activities generate refund requests? Returns generate refund requests, while exchanges do not:

• Returns without exchanges: refund request is passed to ChannelAdvisor

• Even exchanges (where the exchange item's price is the same as the returned item's price): no refund request is passed to ChannelAdvisor

• Uneven exchanges (where the exchange item's price is not the same as the returned item's price): no refund request is passed to ChannelAdvisor; instead, an Order Transaction History message is written: Refund could not be sent - Ord Has Exchg. You can then process any refund manually through ChannelAdvisor.

Note: When an uneven exchange is made for an order, no subsequent refund requests are sent to ChannelAdvisor.

Item-level or order-level shipping and tax? Based on the setting of the CA type specified for the payment method for the marketplace, the SubmitOrderRefund message includes:

• an item-level RefundItems element that breaks out the Amount, ShippingAmount, and both ShippingTaxAmount and TaxAmount (both tax amounts including the full tax and tax on freight, if any) in the request element of the message if the CA type for the payment method is set to Item Level (consistent with the Amazon and eBay with premium tax marketplaces).

• an order-level Amount, including merchandise, tax, and shipping, in the request element of the message if the CA type for the payment method is set to Order Level (consistent with the eBay marketplace without premium tax).

See Working with Pay Types (WPAY) for background.

When you submit the Processing Refunds (MREF) function, it:

A. Submits the refund to ChannelAdvisor: The SubmitOrderRefund message is submitted to the CHANNELADVISOR_ORDER_URL, and includes:

• the ChannelAdvisor account number and credentials specified through the Working with ChannelAdvisor Accounts (WCAA) option.

• ClientOrderIdentifier: the ChannelAdvisor order number.

• SellerRefundID: identifies the refund in Order Management System; formatted as 12345-1.0-2.0 where 12345 is the Order Management System order number, 1.0 is the ship-to number, and 2.0 is the refund number.

• AdjustmentReason: set to GeneralAdjustment.

• SKU: the ChannelAdvisor item identifier for the returned item.

• Quantity: the quantity returned.

• Amount: the extended refund amount, if the CA type for the payment method is set to Order Level, or just the merchandise amount if the CA type for the payment method is set to Item Level. See above for a discussion.

• ShippingAmount: the shipping amount refunded. Included only if the CA type for the payment method is set to Item Level; otherwise, the shipping amount is included in the Amount element. See above for a discussion.

• TaxAmount: The tax amount refunded. Included only if the CA type for the payment method is set to Item Level; otherwise, the tax amount is included in the Amount element. See above for a discussion.

Note:

• Each of the amounts described above is passed as an absolute value and not as a negative amount, and includes an explicit decimal

• ChannelAdvisor passes tax on freight at the line level in the submit order list message. If the tax amount in the SubmitOrderRefund message does not include tax on freight, then this amount is not refunded.

• A credit against an order that does not include the return of a shipped item (for example, if the order line is canceled) does not generate a refund request to ChannelAdvisor.

B. Sets the refund status to I. This status indicates ChannelAdvisor pending.

C. Updates the refund as processed: If ChannelAdvisor accepts the refund, then the system proceeds with standard refund processing and changes the refund’s status to P (processed), performing each standard update, such as credit invoice creation; however, the system does not actually generate the refund, or create records in the Print Check or Bank Reconciliation tables. See Summary of Refund Processing Updates and Reports for background. Otherwise, if ChannelAdvisor does not accept the refund, then the refund status remains I.

Setup summary: See the setup required for the inventory and price uploads, order import, and shipment confirmations, described above, and see ChannelAdvisor Setup for background on setup.

Cancellations

The ChannelAdvisor integration does not currently support submitting refunds that are not associated with an item return. As a result, when you cancel an item on a ChannelAdvisor order, you cannot process the refund using the process described above. Instead, you need to cancel the orders manually in ChannelAdvisor.

To identify orders with cancellations: Query the Order Transaction History table for Transaction note entries that contain the text Refund could not be sent - no items and a User of CAREFUND. These are the orders that require manual cancellation in ChannelAdvisor.