3 System Operations
ChannelAdvisor Integration
Topics in this part: The following topics describe the integration between Order Administration and ChannelAdvisor.
-
ChannelAdvisor Integration Overview provides an overview of the various components of the integration.
-
ChannelAdvisor Setup provides information on the setup required within Order Administration to support the integration.
-
Working with ChannelAdvisor Accounts (WCAA) describes the screens you use to up accounts, marketplaces, and offers for integration with ChannelAdvisor.
ChannelAdvisor Integration Overview
Purpose: Order Administration’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 Administration, 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 Administration project manager.
Troubleshooting the ChannelAdvisor integration:
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 topic:
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 through a web service request 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 comma-separated value file in the CA_INVENTORY_FILE_LOCAL_FOLDER, using the CA_INVENTORY_FILE_NAME.
If there is already a file of that name in the folder, the function overwrites it.
If the file size exceeds 125MB, splits the file into smaller files.
-
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 a teapot with 75 units available, and four units of a teacup with 100 units available. The available quantity of the set is calculated as 25, since there are enough units of the teacup to make 25 tea 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
2. Sending the file to ChannelAdvisor: The function uses a web service request to transmit the file to ChannelAdvisor at the URL from the CA_SERVICES_URL_PREFIX concatenated with the CA_PRODUCT_SERVICE_SUFFIX.
3. Backing up successful and failed files: The function renames
files using a unique sequence number, for example: inventory_123456.txt
, where the CA_INVENTORY_FILE_NAME is inventory
and 123456
is the job ID, and:
-
If the file creation and transmission was successful, the function saves a copy of the file in the
inventory/archive
subfolder of the CA_INVENTORY_FILE_LOCAL_FOLDER. -
If the file creation and transmission was unsuccessful, the function saves a copy of the file in the
inventory/failed
subfolder of the CA_INVENTORY_FILE_LOCAL_FOLDER.
4. Deleting backed up files: The function deletes any existing
files in the inventory
subfolder of the CA_INVENTORY_FILE_LOCAL_FOLDER that are
older than the CA_MAXBACKUP_DAYS defined in Working with Admin Properties (CPRP).
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_NAME.
-
Use the Working with ChannelAdvisor Accounts (WCAA) option to specify your ChannelAdvisor account settings, including information on authentication in ChannelAdvisor.
-
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 ChannelAdvisor to 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 comma-separated value file in the Local Price Folder using the Price Filename. Both of these settings are from your ChannelAdvisor account in the Working with ChannelAdvisor Accounts (WCAA) option.
If there is already a file of that name in the folder, the function overwrites it.
If the file size exceeds 125MB, splits the file into smaller files.
-
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, andCACIN12345
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:
If you clear out one of these price fields after it was previously populated, the next time you send the price file the field is passed as blank. When this occurs, ChannelAdvisor does not clear out the current value for the price. For example, the Buy It Now Price is currently set to 12.34, and you delete the price. The next time the CAPRICE function runs, it includes a blank Buy It Now Price, but ChannelAdvisor skips this entry and leaves the Buy It Now Price set to 12.34. -
2. Sending the file to ChannelAdvisor: The function uses a web service request to transmit the file to ChannelAdvisor at the URL from the CA_SERVICES_URL_PREFIX concatenated with the CA_PRODUCT_SERVICE_SUFFIX.
3. Backing up successful and failed files: The function renames
files using a unique sequence number, for example: caprice_123456.txt
, where caprice
is the Price Filename and 123456
is the job ID, and:
-
If the file creation and transmission was successful, the function saves a copy of the file in the
pricing/archive
subfolder of the CA_INVENTORY_FILE_LOCAL_FOLDER. -
If the file creation and transmission was unsuccessful, the function saves a copy of the file in the
pricing/failed
subfolder of the CA_INVENTORY_FILE_LOCAL_FOLDER.
4. Deleting backed up files: The function deletes any existing
files in the pricing
subfolder of the CA_INVENTORY_FILE_LOCAL_FOLDER that are
older than the CA_MAXBACKUP_DAYS defined in Working with Admin Properties (CPRP).
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 ChannelAdvisor authentication information.
-
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 Administration. 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 ChannelAdvisor carrier and ChannelAdvisor service class match the
ShippingCarrier
andShippingClass
passed for the order. -
customer name and address: from the
ShippingInfo
andBillingInfo
passed for the order. If noBillingInfo
is passed, theShippingInfo
is used as the sold-to customer information; otherwise, theBillingInfo
is used as the sold-to customer information. Some marketplaces may never passBillingInfo
.-
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 toFalse
, the customer’s Opt-in/out flag is set to 03; otherwise, if theEmailOptIn
is set toTrue
, 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 theOrderLineItemInvoice
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 ChannelAdvisor carrier and ChannelAdvisor 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
ofPartial
. -
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 ChannelAdvisor carrier and ChannelAdvisor service class from the ship via used as the
ShippingCarrier
andShippingClass
. -
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 theAmount
,ShippingAmount
, and bothShippingTaxAmount
andTaxAmount
(both tax amounts including the full tax and tax on freight, if any) in therequest
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 therequest
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 Administration; formatted as12345-1.0-2.0
where12345
is the Order Administration order number,1.0
is the ship-to number, and2.0
is the refund number. -
AdjustmentReason
: set toGeneralAdjustment
. -
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 theAmount
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 theAmount
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.
ChannelAdvisor Setup
Purpose: Order Administration’s integration with ChannelAdvisor requires the setup described below.
In this topic:
Additional required setup:
-
Working with ChannelAdvisor Accounts (WCAA): See this help topic for information on configuring your ChannelAdvisor accounts in Order Administration.
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 Administration project manager.ChannelAdvisor Properties
Set the integration properties and logging properties, described below, to support the ChannelAdvisor integration.
Integration properties:
Property | Description |
---|---|
CA_INVENTORY_FILE_NAME located in Working with Customer Properties (PROP) |
The file name for the CAINV periodic function to use when creating a file of current inventory levels for items. See Sending Current Inventory Information to ChannelAdvisor for background. |
CA_INVENTORY_FILE_LOCAL_FOLDER located in Working with Admin Properties (CPRP) |
The folder on the Order Administration server where the CAINV periodic function writes the inventory file. Note: This setting is defined by Oracle and cannot be changed. |
CA_MAXBACKUP_DAYS located in Working with Admin Properties (CPRP) |
The number of days to store ChannelAdvisor archived or failed price and inventory export files before they are eligible for deletion. The CAINV and CAPRICE periodic functions delete the inventory or price files if they are eligible based on the setting of this property. Defaults to 30. If this property is blank, files are eligible for deletion after 30 days. |
CA_PRODUCT_SERVICE_SUFFIX located in Working with Customer Properties (PROP) |
The suffix to include in the URL used for the ChannelAdvisor price and inventory integration. The CAINV and CAPRICE periodic functions use a web service request to pass the generated price and inventory files to ChannelAdvisor. The URL is composed of the CA_SERVICES_URL_PREFIX concatenated
with the CA_PRODUCT_SERVICE_SUFFIX, for example: Defaults to |
CA_SERVICES_URL_PREFIX located in Working with Customer Properties (PROP) |
The prefix to include in the URL used for the ChannelAdvisor price and inventory integration, as described above under the CA_PRODUCT_SERVICE_SUFFIX. Defaults to |
CHANNELADVISOR_ORDER_URL located in Working with Customer Properties (PROP) |
The URL for:
|
CHANNELADVISOR_SHIPPING_URL located in Working with Customer Properties (PROP) |
The URL for the CASHIP periodic function to use when sending shipment confirmations to ChannelAdvisor; see Sending Shipment Confirmations to ChannelAdvisor for background. |
CHANNELADVISOR_ PULL_ORDERS_MAX located in Working with Customer Properties (PROP) |
The maximum number of orders that the GetOrderList function processes at once before sending the notification to ChannelAdvisor that the orders were successfully received and created. Each batch can include up to 50 orders. For example, if you set this property to 100, the function imports two batches of 50 orders. If no maximum is specified, a default of 50 orders applies. |
ChannelAdvisor: Related System Control Values
The system control values related to the ChannelAdvisor integration are listed below.
System Control Value | Setting |
---|---|
The order type to assign to orders from ChannelAdvisor. |
|
The available quantity to submit to ChannelAdvisor for drop ship, non-inventory, gift card, subscription, and membership items. |
|
The offer you use to set up cross references between the ChannelAdvisor item identifier and the Order Administration item/SKU. Must also be set up through the Create ChannelAdvisor Offer Screen. |
Additional system control value requirement: The Tax Included in Price (E70) system control value needs to be unselected for to prevent errors when creating new customers from ChannelAdvisor.
ChannelAdvisor: Periodic Functions
Build and schedule one or more periodic processes to include the following periodic functions:
Periodic Function | Purpose | More Information |
---|---|---|
Run this periodic function to request access to ChannelAdvisor for the specified AccountID. Before running this periodic function, enter connection information in the Parameter field using the following format:
For example:
Note: This periodic function should be run one time for each account as part of initial setup of the ChannelAdvisor integration.In addition, once you establish a connection with ChannelAdvisor, you can change the Parameter field to the following format:
For example:
Run the periodic function to write information to the Application log about the status of the access to ChannelAdvisor. |
||
Generates a file of current inventory levels to send ChannelAdvisor. |
||
Generates a file of current pricing for items sold through the ChannelAdvisor integration. |
||
Sends ChannelAdvisor a request for new orders and creates orders based on the information in the order response message. |
||
Sends shipment confirmation messages to Channel Advisor. |
For more information: See Scheduling Jobs for an overview.
Refunds? There is no periodic function to send refunds to ChannelAdvisor; the Processing Refunds (MREF) function sends refunds for ChannelAdvisor orders.
Pricing Setup for ChannelAdvisor
Set up the following prices for the CAPRICE periodic function to extract when building the price file to send to ChannelAdvisor:
-
Buy It Now Price: from through the Original retail $ in the SKU table
-
Retail Price: from through the List price in the SKU table
-
Additional price: the function uses the most current SKU Price (based on Effective date), if any, for your ChannelAdvisor offer, set up through the Create ChannelAdvisor Offer Screen and the ChannelAdvisor SKU X-Ref Offer (L92); otherwise, it uses the most current Item Price. The label of the additional price field is from the Price output name specified for the ChannelAdvisor offer through the Work with ChannelAdvisor Offers Screen option.
Note:
Any SKU or Item Prices you set up for the ChannelAdvisor offer should have a quantity of 1.Mapping Data between ChannelAdvisor and Order Administration
Purpose: In order to map data correctly from ChannelAdvisor to Order Administration, you need to set up cross references in Order Administration. This required setup is described briefly below.
Mapping Data | Menu Option | Used By | Notes |
---|---|---|---|
Sku cross ref for the ChannelAdvisor SKU X-Ref Offer (L92) |
The CAINV, CAPRICE, CAORDUP, and CASHIP periodic functions. See ChannelAdvisor Integration Overview for process overviews. |
The offer needs to match the ChannelAdvisor SKU X-Ref Offer (L92) system control value. |
|
CA cross reference # and CA type for a pay type Note: Should be a cash/check pay type. |
Working with Pay Types (WPAY) and Working with ChannelAdvisor Accounts (WCAA) |
The CAORDUP periodic function and the Processing Refunds (MREF) option. See Importing Orders from ChannelAdvisor and Submitting Refunds for ChannelAdvisor Orders. |
The function
uses the The CA type indicates whether to calculate tax and shipping at the item level (consistent with the Amazon and eBay with premium tax marketplaces) or the order level (consistent with the eBay marketplace without premium tax). |
ChannelAdvisor carrier and ChannelAdvisor service class for a ship via |
The CAORDUP and CASHIP periodic functions. See Importing Orders from ChannelAdvisor and Sending Shipment Confirmations to ChannelAdvisor. |
||
ChannelAdvisor Order Type (L90) |
The CAORDUP periodic function. See Importing Orders from ChannelAdvisor. |
This order type also determine which orders to include when sending shipment confirmations and refunds to ChannelAdvisor. See Sending Shipment Confirmations to ChannelAdvisor and Submitting Refunds for ChannelAdvisor Orders. |
|
Source associated with a marketplace |
Working with Source Codes (WSRC) and Working with ChannelAdvisor Accounts (WCAA) |
The CAORDUP periodic function. See Importing Orders from ChannelAdvisor. |
The function
uses the the The source code must use a line-level freight method. |
price override reason code of W |
The CAORDUP periodic function. See Importing Orders from ChannelAdvisor. |
You need to use a price override reason code of W, and cannot change this default. |
|
ISO country code |
The CAORDUP periodic function. See Importing Orders from ChannelAdvisor. |
The ISO code must be set to the country’s two-position ISO country code. |
E-Commerce Setup
Purpose: You must perform basic setup in Order Administration and on the web storefront before you can use the E-commerce interface in Order Administration. Setup requirements include:
-
system control values
-
supporting tables for download to web storefront
-
additional system applications
Web storefront: Additionally, you must configure the web storefront to meet your business requirements. You can modify the sample storefront or create your own; however, configuration of the web storefront is outside the scope of this document.
In this topic:
System Control Values Related to E-Commerce
Purpose: The system control values related to e-commerce are described briefly in the table below.
Create application area: Before you can set several e-commerce system control values, you must create the EDC application area. You can create an application area by selecting Create at the Work with System Values/Features screen in Work with System Control Values (WSYS). Additionally, you must assign the application group ALL to the EDC application area. You can assign this application group by:
-
selecting Application Group for the application area at the Work with System Values/Features screen; you advance to the Work with Application Group screen
-
selecting Create to advance to the Create Application Group screen. Here, you can create the ALL application group for the EDC application area.
Each of the e-commerce system control values listed below should be assigned to this application area and group.
System Control Value | Description |
---|---|
Defines the available quantity to trigger the automatic download of availability information of an item. The quantity you define here is a default; you can also specify a Avail thrshld (Item-level availability threshold) for an item, and/or a Availability threshold (item class-level) for an item class. |
|
Defines whether to identify partially reserved, partially backordered items as RESERVED, BACKORDER, or PARTIAL on the web storefront. |
|
Hold Reason for Failed E-Commerce Maintenance Transactions (H11) |
Specifies the hold reason code to assign to orders when a customer attempts, and fails, to maintain it from the web storefront. |
Specifies the program to use to create order maintenance confirmations to send to customers via email. |
|
Defines whether Order Administration generates the E-Commerce Customer Merge Web XML File (CustomerMergeWeb) when you run the customer sold to merge/purge program. |
|
Defines whether the system includes prepaid (cash/check payment category 1) payment types in the e-commerce pay type extraction. |
Additional system control values:
System Control Value | Description |
---|---|
Controls the Expected delivery date to pass to the web storefront for items without open (unreceived) purchase orders. The system also includes information on whether the date was derived from a purchase order, or defaulted based on this system control value. You can use either a periodic function or a message to pass item availability information to the web storefront; see E-Commerce Download Overview for general information, and see E-Commerce Item Availability Processing for details. |
|
Used when you process catalog requests through the web storefront. |
|
SKU Element Description 1 (G37) |
Define the SKU element descriptions to appear on the web storefront. |
For more information: See Order API-Related System Control Values for a list of values related to creating orders you receive from the web storefront in the Order Administration Web Services Guide on https://support.oracle.com My Oracle Support (ID 2953017.1).
Table Setup for Download
Purpose: In addition to the tables you must set up for order entry through Order Administration, you can set up the following table to facilitate processing orders through the web storefront.
Table | Purpose | To Set Up |
---|---|---|
E-Mail Template |
To define the text to appear in system-generated emails to customers, such as backorder notices and soldout notifications. |
Additional Setup
Purpose: In addition to the setup you must perform to process orders through order entry, you might need to set up the following information specifically for e-commerce orders.
Additional Table Settings
-
Items: You can set the Avail thrshld (Item-level availability threshold) as an override to the item-class level threshold or the Quantity Available Threshold for Inventory Downloads (G36) system control value.
-
Item class: You can set the Availability threshold (item class-level) as an override to the Quantity Available Threshold for Inventory Downloads (G36) system control value.
-
Customers: Set the Opt in/Opt out flag to indicate when to communicate with the customer by email. Also, you will need to specify the Email address to correspond with the customer by email.
-
Order type: Set the Email notification flag to indicate whether to communicate with customers by email on order-related correspondence, such as backorder or soldout notifications.
E-Commerce Periodic Functions
Order Administration-
ECSHCNF: Sends shipment and return confirmation emails; see Sending Internet Order Ship Confirmation (ESCF). This function should use the program name ECR0154.
-
ECOMERR: Creates the batch OM Transaction Error Listing. This function should use the program ECR0295.
-
ECX0358: Extracts updated customer user fields to the EC Customer Extended (EXCSTE) staging table.
Oracle Retail Promotion Engine Integration
Order Administration is integrated to the Oracle Retail Promotion Engine Cloud Service (ORPE) following the v23.2.401.0 update. When configured, Order Administration will bypass some of the inherent promotional pricing options during order entry, making a REST call to provide the order (cart) details for evaluation by ORPE. The promotion engine performs a comprehensive evaluation of the cart, identifies the applicable offers, and responds with the discounted price applied for qualifying merchandise lines. If shipping rewards are included in the response, Order Administration performs additional validation and calculations before they are applied to the order.
Retailers define deals and promotions using Customer Engagement and then automatically propagate the promotion data to ORPE. This allows the retailers to submit orders (carts) from various external systems (ecommerce, point of sale, order management, and so on) to be centrally evaluated against a single source of promotion data.
The following features in Order Administration will communicate with ORPE for applying promotions:
-
Modern View Order Entry
-
Classic View Order Entry when editing / accepting a batch of orders in error
-
CWOrderIn version 12.0 when it indicates discounts are not already applied
-
Customer Membership Child Order Generation (EGMO)
The following features will not communicate with ORPE: Order Maintenance, OB Fulfillment Order Creation, and ChannelAdvisor.
Note:
Order Administration Modern View Order Summary does NOT communicate with ORPE when an existing order is maintained. If a new line is added in maintenance, it will be priced based on the Order Administration price method hierarchy. If an existing line quantity is changed in maintenance, the price will remain unchanged. The line will not be re-evaluated by Order Administration, and it will not be sent to ORPE for evaluation.Order Administration Classic View does not allow the reprice function with ORPE enabled, nor does it call ORPE during interactive order entry or order maintenance. However the Edit/Accept batch process triggered from Classic View does call ORPE to evaluate orders which have corrected within the Error Batch.
All promotion details successfully applied by ORPE are stored for display within the Modern View user interface (UI) and incorporated into various outbound API’s and integration files including:
-
Modern View Order Summary and Invoice tabs
-
CWInvoiceOut version 7.0
-
CWOrderOut version 12.0
-
CWEmailOut version13.0
-
ReSA RTLog Output File
-
ORCE POSLog Output File
ORPE Setup Requirements
Required Properties: The following properties are available to configure the integration with ORPE:
-
oms.promotion.engine.service.url (PROP): The full URL for the promotion engine service. Provided by your Oracle representative. Defaults to blank.
-
oms.promotion.engine.service.timeout (CPRP): The number of seconds to wait before deal requests from Order Administration to the ORPE Promotion time out. Defaults to 500 seconds.
-
oms.promotion.engine.service.token.url (CPRP): The URL to use when requesting a token for Oauth authentication. Provided by your Oracle representative. Defaults to blank.
-
orce.coupon.service.url.suffix (PROP): The suffix to append to the ORCE_CUSTOMER_SERVICE_PREFIX for Serialized ORCE Coupon Service for validation and redemption of a serialized coupon.
Note:
When calling the ORCE Coupon Service, Order Administration builds the URL using the ORCE_CUSTOMER_SERVICE_PREFIX, SCV L50 and the orce.coupon.service.url.suffix value.Authentication configuration: To configure the promotion engine integration, use ORPE Promotion and ORCE Coupon Service at the Work with Outbound Web Service Authentication screen (WWSA). Only OAuth authentication is supported. Client ID and Client Secret will be delivered blank by default for each company.
Required system control value settings: Use the following system control values to enable use of ORPE:
-
Use ORPE Promotion Engine (M77): Select this system control value to enable use of ORPE for a specific company. Required for ORPE Integration.
-
Price Override Reason for ORPE Discounts (M78): Select the price override reason code to apply to order lines that are discounted through use of the Promotion Engine. Required for ORPE Integration.
-
Use ORCE Serialized Coupons (M79): Select this system control value to use Serialized Coupons with ORPE.
-
ORCE Serialized Coupon Prefix Length (M80): This system control value stores the Serialized coupon codes prefix length value. It must match the value defined in Property Configuration Promotion Coupon Length within ORCE.
Also, the following existing system control values are used:
-
Allow Manual Entry of Promotion Code (I63): Must be selected to see the new Coupons section within in the Order Summary panel.
-
ORCE Integration Item ID (L38): Required for ORPE Integration.
-
ORCE Organization Descriptor (L50): Required for Serialized Coupons with ORPE.
-
Display Order Line Discount Messages (F01): Impacts display of ORPE promotion details.
-
Display Discount On Order Recap Screen (D38): Impacts display of ORPE promotion details.
-
Default Location for ORCE Integration (K69): Required for integration with ORCE and ORPE.
Order API Enhancements
The Order API (CWOrderIn) now allows the ability to indicate the order should be sent to ORPE for promotions to be applied. Additionally, it includes new attributes to allow an external merchant application to pass discount details already applied by ORPE externally. The changes include:
-
The already_eval_by_promote attribute was renamed to already_eval_by_promo_engine.
When a new Order Broker Fulfillment Delivery or Retail Pickup order is created, if already_eval_by_promo_engine is set to Y, this indicates the order already has all discounts applied and should not call ORPE for additional discounting. Likewise, when a new Order Broker Fulfillment Delivery or Retail Pickup order goes into Error, during the Edit/Accept process, the system will not call ORPE when the ORPE integration is enabled.
-
A new repeating element (Shipping_Rewards) was added within the ship to element, allowing retailers to include shipping award details that were already applied by an external system.
A new repeating element (Discount_Rewards) was added within the item element, allowing retailers to include order line discount details that were already applied by an external system.
Note:
The Order API does not currently support ORCE coupon codes or targeted customer promotions when passed in from an external merchant application. See the Order Administration Web Services Guide on My Oracle Support (ID 2953017.1) for more information.Deal Types and Promotions
The Order Administration integration now supports the ORPE deal types included below. These deal types are configured in Customer Engagement.
-
BOGO: Buy X Get X and Buy X Get Y
-
LINE ITEM: Line Item Discount
-
GROUP PRICE: Kit
-
SUBTOTAL: Transaction Discount
For each supported deal type, Order Administration will allow shipping awards to optionally apply an Override Shipping Method (Ship Via) and/or the ability to define a discount from the following options:
-
an Override Price (flat shipping fee),
-
an Amount Off (Order Administration deducts the value from the shipping calculation) or
-
a Percent Off (Order Administration calculates the discount percentage amount then deducts the value from the shipping calculation)
Note:
All Shipping Award discount options are applied within Order Administration as a shipping override.The Order Administration integration currently supports product and coupon promotion types (both single-use and multi-use coupons) and incorporates cart data for evaluation of location qualifiers and promotion audience rules (exclusive and non-exclusive).
Note:
Coupon Codes are not supported through the Order API. They are only supported when entered through Modern View Order Entry.Coupons the integration with ORPE supports two options for coupon promotions, (Serialized and Non-Serialized).
-
A Serialized Coupon allows the retailer to generate coupons, each with a unique serial number, generally for a one-time use. Depending on user authority, a contact center agent may have the ability to allow a previously redeemed serialized coupon to be submitted to ORPE. In this situation, ORPE will apply the coupon discount as long as the cart meets the coupon requirements.
-
If the Contact Center user has authority to the Allow Redeemed ORCE Serialized Coupon to be Overridden secured feature, they can submit a previously redeemed serialized coupon to ORPE by clicking a new attempt Reuse button. For example: If the coupon represented a 10% discount on handbags, it would be automatically applied as long as the cart included a handbag.
-
-
A Non-Serialized Coupon allows a retailer to define a coupon code for the promotion which can be used multiple times. For example, the coupon code ‘SHOE20’ may represent a coupon code that a customer can use multiple times to receive a 20% discount on a shoe purchase.
For Failed redeems due to a communication failure with ORCE or another issue, the retailer can generate a report through Customer Reports or RDS based on the Order Transaction History record where the serialized coupon was not redeemed.
About location qualifiers: When submitting the cart information to ORPE, Order Administration includes location identifier (value from SCV K69 – Default Location for ORCE Integration), so that ORPE can evaluate and either qualify or exclude the cart based on location rules defined for the promotion in ORCE.About audience rules: Audience rules can be defined within each promotion created from the ORCE UI. By default, the audience defaults to All which means that the promotion is available to anyone. (Everyone who buys the items included in the promotion, gets the offer discount.) However, the retailer can optionally define the promotion audience as Exclusive or Non-Exclusive and include additional selections options.
Note:
To identify customers that are included in exclusive promotions, Order Administration first makes a call to ORCE using the retrieveCustomer method. Any Exclusive Promotion details included in the response are then submitted with the cart for ORPE evaluation. If the cart qualifies for the exclusive promotion, the respective discounts are applied to the order.Targeted Customer Promotions: the integration with ORPE supports applying customer targeted promotions tied to a customer in ORCE. These promotions are set up as Audience Rules within the promotion in ORCE.
-
Exclusive Audience: When the retailer defines the promotion audience as Exclusive, this means that only the customers identified in the target group (segment) are eligible to receive the promotion.
-
Non-Exclusive Audience: When the retailer defines the promotion audience as Non-Exclusive, this means that all customers are eligible to receive the promotion.
During Modern View Order Entry, if the customer exists in ORCE and qualifies for an Exclusive Promotion, that will automatically be passed into ORPE as additional qualifiers in the cart and the respective discounts are applied to the order.
Order Entry Changes in Modern View
Modern View Order Entry has been changed when SCV Use ORPE Promotion Engine (M77) is enabled to support the deal types and promotions. The following now occurs:
-
The Promotion Code and the Discount Percent fields are hidden from view.
-
When Allow Manual Entry of Promotion Code (I63) system control value is enabled there is a new Coupons section in the Order Summary panel.
-
When using a source code with price method Reg Plus Reprice and the Add Coupon Code button is selected from the Coupons section of the Order Summary panel, a modal window opens so that the user can enter coupon codes. Entered coupons are evaluated during order review, rather than immediately upon closing the modal window, since additional order changes may be incorporated.
-
If the source code used at order entry has price method other than Reg Plus Reprice, a warning message is displayed within the Coupons section advising Source code does not support Coupons and the Add Coupon Code button is not displayed.
-
-
At the Review step, or after Refresh Order if changes were added, the Coupons section may display a message indicating that Codes were not applied; this occurs if any serialized coupons were previously redeemed or coupons were submitted for evaluation but were not applied.
-
At the Final Submit step, a System Update entry is written in the Order Activity tab when:
-
a coupon code is entered but not successfully applied by ORPE.
-
a serialized coupon is successfully applied by ORPE and it is successfully redeemed or not.
-
If the Contact Center user has authority to the Allow Redeemed ORCE Serialized Coupon to be Overridden secured feature, they can submit a previously redeemed serialized coupon to ORPE by clicking a new Attempt Reuse link. For example: If the coupon represented a 10% discount on handbags, it would be automatically applied as long as the cart included a handbag.
Discount Display in Modern View Order Entry and Summary
Discount Information
New order discount tables are updated with promotional order line discounts and shipping reward information applied by ORPE. The data in the tables is used to display discount history within Modern View and to compile discount information when sending order information to downstream systems (POSLog, RTLog, InvoiceOut, OrderOut, and so on.). The Order Shipping Discount tables contain the shipping awards information resulting from the ORPE applyDeals response. The Order Detail Discount History tables holds the order line discount information resulting from the ORPE applyDeals response.
Item Level Discounts
When the offer price is greater than the unit price, the system now displays the offer price with a strike through before the discounted Unit Price. This is controlled by Display Order Line Discount Messages (F01) system control value.
Additionally, hovering over a new icon will display the discount details for each promotion applied, including the unit discount amount and the associated deal description. If the promotion was triggered by a coupon, the coupon code is included in parenthesis following the deal description.
Order Level Discounts
The Order Total section now displays an icon in front of each of the labels that include an ORPE discount (Merchandise and/or Shipping). This is controlled by Display Discount On Order Recap Screen (D38) system control value.
Additionally, an informational message will display below the totals for each ORPE discount type (Merchandise and/or Shipping) showing the total promotion discounts for the order.
Note:
The calculated Merchandise Discounts and Shipping Discounts are limited to discounts applied by ORPE. If additional discounts were applied based on price methods, manual price overrides, and so on, those discounts would not be reflected in the Merchandise Discounts or Shipping Discounts.When no ORPE promotion discounts have been applied to the order, but there is a delta between the offer price and the actual selling price (due to price method discount, price overrides, and so on) an Order Discount informational message will display below the totals. The Order Discount value is a calculation of the sum of the extended offer prices for all lines, minus the total extended selling price for all lines.
Promotion Details
For orders including promotional discounts applied by ORPE (or submitted through the Order API with the already_eval_by_promo_engine attribute set to Y and containing reward data) a Promotion Details button will display within the Ship To section of Modern View Order Summary. Summary level promotion details per ship-to will be displayed in this panel.
From the Invoices tab, once an invoice has been selected the same item level and order level promotion discount data is available, however the lines displayed will be limited to those included on that specific invoice.