Upload
others
View
4
Download
0
Embed Size (px)
Citation preview
Version: 2.3.5Published date: April 2020
Copyright © 2020 by eShopWorld. All rights reserved. Information contained herein is subject tochange without notice.
eShopWorld eCommerce Solutions
Magento Extension User Manual
Table of Contents1 About this document 11.1 Intended audience 1
1.2 Document revision history 1
2 Overview 32.1 Features 3
2.1.1 Out of scope 4
2.2 Magento Extension and eShopWorld Checkout flow 4
3 How does it work? 63.1 Retailer Platform and eShopWorld Checkout Flow 6
3.2 Pricing Models 7
3.3 Pricing API (hosted by eShopWorld) 7
3.4 Checkout API (hosted by eShopWorld) 8
3.4.1 Process Flow 9
3.5 Order Confirmation Request (hosted by retailer) 9
3.5.1 Process Flow 9
3.6 Package Integration 10
3.6.1 Hub model 10
3.6.1.1 Hub model flow 13
3.6.1.2 Cron synchronisation 15
3.6.1.3 Administration interface 16
3.6.2 Ship from Store (Hubless model) 17
3.6.2.1 Ship from Store flow 18
3.7 Returns Integration 21
3.7.1 Magento Entity Types 22
3.8 Catalog Integration 23
4 Installation and setup 264.1 Installing the extension 26
4.2 Verifying the installation 27
- i -
4.3 Accessing the extension 27
4.4 Viewing configuration 27
5 Configuration 295.1 Setting up Magento for Fixed price model 29
5.1.1 Country and Currency setup 29
5.2 Setting up Magento for the Calculated Pricing model 29
5.2.1 Prerequisites 29
5.2.2 Country and currency setup 30
6 Security Token Service 316.1 Security Token Configuration 31
7 Checkout 327.1 General Configuration 32
7.2 Pricing Feed Configuration 33
7.3 Country – Currency Mapping 34
7.4 Retailer Display Configuration 35
7.5 Pricing Configuration 37
7.6 Preorder Expansion Pairs Configuration 38
7.7 Preorder URL Configuration 40
7.8 Order Confirmation Configuration 42
8 Order Fulfillment 448.1 General Configuration 44
8.2 Package/ASN Configuration 44
8.3 Returns Configuration 46
9 Catalog 489.1 General Configuration 48
10 Logs 5010.1 General Configuration 50
10.2 Logs Cleaning 50
11 Shipping Rates 5212 Extension Logs 53
- ii -
13 Order Confirmation 5413.1 Order Confirmation v2.0 54
13.1.1 eShopWorld Order 54
13.1.2 eShopWorld Order Items 59
13.1.3 eShopWorld Order Cart Discounts 65
14 Developer 6814.1 Setting up the Varnish cache 68
14.2 Setting the package reference 69
14.2.1 Package reference in the Magento Shipment API 70
14.3 Cookies 70
14.4 Extension API 71
14.5 Frontend Widgets Customization 72
14.6 Asynchronous Operations for Magento Commerce Cloud 73
14.6.1 Get eShopWorld calculated price 73
15 Troubleshooting 7515.1 Extension not appearing on the dashboard 75
- iii -
1 About this documentThis document provides an overview of the eShopWorld Magento extension and provides instructions on how to install and use the extension. For the latest version of this document, go to the eShopWorld Developer Portal.
1.1 Intended audienceThis document is intended for developers who want to integrate the eShopWorld Magento extension with their existing e-commerce platform.
1.2 Document revision historyVersion Date Description
2.0.1 December 2018 Created the initial version for v2 of the extension. Also added Loyalty Card Number to the Order Confirmation 1.1 request.
2.1.0 March 2019
New features added:
l Basic authentication on order confirmation point.
l Ability to set custom order confirmation URL.
l Paid order status option for new order creation.
l Country configuration to match the eShopWorld checkout display, including saving tax on item-level for countries where tax is added at the eShopWorld checkout.
l Multi-website support.
Enhancements to existing features:
l FX shipping overrides with conditions.
l FX model working with native Magento func-tionality cart discounts with pricing rules and fixed tier pricing.
- 1 -
Version Date Description
l Added FX pricing model support for bundle and group product type.
2.2.0 May 2019
New features added:
l Checkout 2.0 fixed price support.
l Package 2.0 integration for eShopWorld orders.
l Logs configuration.
2.3.0 August 2019New features added:
l Checkout 2.0 pricing advisor support
2.3.5 March 2020
New features added:
l Order fulfillment and details on package integ-ration for the Hub and Hubless (Ship from Store) shipping models.
l Returns integration.
l Setting the package reference for the Hub ship-ping model.
l New Developer section added
l Setting the package reference for the Hub ship-ping model.
l Renamed the FX pricing model to Calculated.
l Updated the Catalog Integration in "How does it work."
2.4.0 April 2020New features added:
l Asynchronous operations for Commerce Cloud.
- 2 -
2 OvervieweShopWorld's Magento extension integration allows retailers to get access to a network of 25+ global carriers, 40+ global hubs, multiple PSPs and acquirers, 40+ payment methods, 100+ currencies, multilingual checkout, and much more. The eShopWorld Magento extension creates a seamless international shopping experience with an optimized journey per shipping country. Magento’s cart is integrated with eShopWorld’s hosted checkout, providing a seamless shopping journey to international shoppers.
The eShopWorld Magento extension supports Magento® Community and Enterprise editions 2.2.x and 2.3.x.
2.1 FeaturesThe following are some of the features of the eShopWorld Magento extension:
l Cross-border shoppers are automatically provided with local prices in their currency across the Magento shopping experience through eShopWorld’s GeoIP implementation.
l Registered shoppers benefit from faster checkout by utilizing saved data within the eShopWorld hosted checkout.
l Retailers can enable the eShopWorld landing mat and country/language selectors so that shoppers can change their country and language preferences. Multi-language sup-port is integrated via Magento’s language configuration and eShopWorld’s hosted checkout.
l Tax and duty display options can be set to maximized conversion rate with eShopWorld’s Pricing Advisor. Tax and duty are updated in Magento once an order is placed to reflect the breakdown of order details based on the actual order.
l Pricing is natively integrated with Magento allowing the full support of catalog and cart price rules.
l Shipping rules per country can be configured within the extension. Additionally, retailers can configure the countries that they want their native checkout to support and the coun-tries that will utilize eShopWorld’s optimized international checkout.
- 3 -
l Payment options are provided on the eShopWorld hosted checkout. These options are optimized for each market. Once the payment is made, the order is created in Magento and the Order Confirmation page is displayed to the shoppers.
2.1.1 Out of scope
The following features are out of the scope of the extension:
l Cart price rules for shipping: The extension does not support shopping cart price rules for shipping.
l Checkout UI customization: Checkout is a module that the eShopWorld extension integ-rates with, but UI cannot be customized from within the extension configuration. A guide is provided to the retailers regarding UI customization and is defined during the scoping stage of eShopWorld integration.
l Checkout configuration: The eShopWorld extension has a dependency on the con-figuration by eShopWorld. The extension can only enable configurations that have already been enabled on eShopWorld’s Checkout module, for example:
l Additional countries and currencies.
l Shipping methods - configured to support overrides within eShopWorld’s services to allow overrides to apply.
l Payment methods (the payment methods cannot be controlled from within the exten-sion).
l Gift Cards: The extension does not support gift cards.
l Native Magento tax rules: The extension currently does not support native Magento tax rules.
2.2 Magento Extension and eShopWorld Checkout flowThe following figure explains the flow between the Magento extension and eShopWorld Checkout.
- 4 -
- 5 -
3 How does it work?This chapter describes the following topics:
l Retailer Platform and eShopWorld Checkout Flow
l Pricing Models
l Pricing API
l Checkout API
l Order Confirmation Request
l Package Integration
l Returns Integration
3.1 Retailer Platform and eShopWorld Checkout FloweShopWorld's hosted cross-border checkout collects shopper data, such as delivery, product, and pricing information. It processes the payment and creates an order on the eShopWorld platform and the retailer's e-commerce engine. For more information on the eShopWorld Checkout and the features, click here.
To use eShopWorld’s optimized international hosted checkout, retailers must have a tenant set up by eShopWorld. A tenant contains retailer-specific configuration and provides services, such as hosted checkout, logistics service configuration, and inter-national country setup, which are unique to each retailer. eShopWorld provides the tenant information to the retailers during their onboarding.
The following figure describes the flow between the retailer's platform and eShopWorld checkout:
- 6 -
3.2 Pricing ModelsA pricing model defines how the in-country product price is displayed on the retailer's site. The retailer defines the pricing model per country. The eShopWorld Magento extension supports the following pricing models:
l Calculated pricing model: In this model, in most cases the product base price is exclusive of any taxes. This model uses the Pricing Advisor API. The base price is taken from Magento's native base price field and formulas are applied to this value to display the loc-alized price to shoppers.
l Fixed price model: In this model, in most cases the product price is inclusive of all taxes. Prices are taken from the native Magento price fields.
3.3 Pricing API (hosted by eShopWorld)Pricing advisor is a collection of services that provide retailers with a maintenance-free pricing solution for the international markets.
- 7 -
Key features include:
l Pricing Advisor API: A service that sets the uplift, estimated tax, estimated duty, foreign exchange, and rounding rules per shipping country. These values are set up during the scoping phase and are unique to each retailer.
l Pricing Advisor Magento Synchronization: A synchronization service that is included with the Magento extension. This service updates daily foreign exchange, uplift, estimated tax, estimated duty, and rounding rules.
l Pricing Advisor Magento Configuration: An interface that sets the prices for each shipping country in Magento.
l Pricing Advisor Magento Price Display: A feature that displays updated prices across Magento based on the pricing advisor for the international market.
l Pricing Advisor Checkout Integration: A feature that sends the prices set up by the pricing advisor to the eShopWorld’s hosted checkout to facilitate end-to-end customer flow.
3.4 Checkout API (hosted by eShopWorld)The information that is passed from the retailer's site to the eShopWorld checkout is called the Checkout API (or Preorder) request. This payload provides the order data that relates to a
- 8 -
shopper's cart. There are two types of checkout flows:
l eShopWorld supported countries, where the shopper cuts across to the eShopWorld checkout.
l Traditional or domestic e-commerce platform flow for non-eShopWorld supported countries.
3.4.1 Process Flow
The following steps explain the process flow:
1. When a shopper clicks Proceed to Checkout after adding products to their cart, a call is made to the Checkout API.
2. On success, an eShopWorld redirect URL is passed in the response and the shopper is redirected to the eShopWorld checkout. On failure, the shopper remains on the retailer’s cart page.
3.5 Order Confirmation Request (hosted by retailer)The extension provides an API endpoint for the eShopWorld system to send a request with order confirmation to the retailer's system, which is called the Order Confirmation API. The URL is: {domain}/eShopWorld/order/confirm.
3.5.1 Process Flow
The following steps explain the process flow:
1. When a shopper clicks Pay Now, the payment is processed, and an Order Confirmation API payload is sent by the eShopWorld system to the Order Confirmation API endpoint containing the product, shipping, service level, and payment data for the order.
2. When the Order Confirmation request is received by this endpoint:
1. The request data is validated.
2. A search for the checkout order number is made in the database to make sure it exists.
3. When found, the request data is persisted into the retailer's e-commerce platform.
3. On success, the Order Confirmation endpoint sends a response to the eShopWorld system indicating that the order confirmation action is successful, and the order is created on the eShopWorld platform. The shopper is then presented with the Order Confirmation page.
- 9 -
4. On failure, the shopper is redirected to a failure notification URL supplied by the retailer. No order is created on the retailer's platform or the eShopWorld platform.
3.6 Package Integration eShopWorld provides a range of models, including Hub and Ship from Store for retailers to fulfill orders. Each model has a different order process flow, which is described in the following sections.
3.6.1 Hub model
The Hub model is used when a retailer ships goods to the eShopWorld distribution hub. From there, the goods are shipped to the shopper. To use the Hub model, the package data must be sent to eShopWorld in advance of the packages physically arriving at the hub. The data can be synchronized via eShopWorld's Magento extension based on the shipments created in Magento. During the synchronization stage, the order tracking is also updated, which allows shoppers to track the order using the eShopWorld Order Tracking portal.When using the Hub model, retailers have the option to set the package reference in their standard process. If the package reference is not set, the default the order increment ID from Magento is set as the package reference. The limitation with using order increment ID is that only full order shipments are supported. If you require split or partial shipment, the package reference must be set according to the tracking specification using the native Magento shipment API. For more information on the package reference, "Configuration" on page 29.
Key features:
l Extension of the Magento native shipment API to include package_reference.
l Integration with eShopWorld’s Package API to include the POST endpoint.
l Cron job, which can be set for x frequency to run the POST endpoint.
- 10 -
l Native Magento shipment tracking updates.
l Ability to view the order view synchronization status:
l Ability to view the order tracking information.
- 11 -
l Ability to view the order tracking link.
- 12 -
3.6.1.1 Hub model flow
The following diagram explains the Hub model:
- 13 -
1. Shopper adds the item to their cart on Magento -Magento Quote table. This is the native Magento shopper journey.
2. When the shopper clicks Checkout, a call is made to the eShopWorld Checkout API. The Checkout API request is integrated with the eShopWorld extension, which sends eShopWorld Magento cart information, such as product information, shipping country, currency, locale, shipping rates (if setup) and customer details (if the shopper is logged in). eShopWorld generates hosted checkout based on the data received and responds with the Checkout URL to redirect the shopper.
3. The eShopWorld hosted Checkout is generated based on the data.
4. The shopper enters their delivery details, payment details and clicks Pay Now.
5. The payment is authorized and an order created in the eShopWorld system.
6. The order confirmation request is sent from eShopWorld to Magento to confirm payment successfully. The order confirmation request contains additional order information, such as the breakdown of the order including tax and duty in the shopper currency and retailer currency.
7. The order is created based on the quote in Magento. The invoice is created and the order status is updated to Processing. Additional custom data from step 6 is saved in the eShopWorld custom tables within Magento. The data can be viewed via the Admin panel.
8. The order confirmation response is received from Magento to ESW. When the success response is received by eShopWorld, the payment is captured between 30 minutes to 2 hours and 30 minutes later. The order confirmation request is attempted thrice with a waiting time of one minute for a success response. If a response is not received within the time limit, the order is automatically cancelled in eShopWorld’s database, which can potentially cause misalignment of order status. If an error response is sent by Magento, for example, due to issues with stock, the order is cancelled.
9. The Order Confirmation page hosted by eShopWorld is displayed to the shopper.
10. The order with the Processing status is fetched by WMS/ERP. The orders are imported into WMS ready for processing and dispatch.
11. The order is picked and packed. The Shipment ID is printed as a barcode on the pack-age generated by the retailer’s WMS. Retailers print a barcode on the shipment to identify package contents, this could be order number (which is only used if only full order fulfillment exclusively) or unique shipment reference.
12. The order is collected by the courier and delivered to the eShopWorld distribution hub.
- 14 -
13. The package arrives at the eShopWorld hub.
Steps 16-20 take place prior to step 13 because these are background processes that occur automatically based on existing processes and systems.
14. The barcode is scanned at the eShopWorld hub, the shipment label is printed, and the package is collected by the courier. The barcode is the package reference from step 16 and synchronized with eShopWorld at step 20.
15. The package is delivered to the shopper.
16. A unique shipment ID is passed to Magento. Unique shipment ID is optional data sent from WMS to Magento to identify the package. Retailers must populate package_reference using Magento shipment API to synchronize unique shipment ID.
17. WMS pushes the update to Magento to create a shipment.
18. Magento creates shipments in Magento.
19. Magento updates the order status to Complete when the shipment is created for the full order.
20. The Magento extension sends the package information to eShopWorld every x minutes. Additionally, the package reference is set as a unique shipment ID if it exists. If not, the order order number is set as the package reference. The Magento tracking is also updated with the eShopWorld carrier and tracking ID set as package reference.
21. Tracking order or returns are managed via the eShopWorld Order Tracking portal and Returns portal respectively.
3.6.1.2 Cron synchronisation
The Cron job is used to send eShopWorld shipment updates from Magento. A request is sent for each shipment that has the shipment status as Pending. The following table shows the shipment status update based on a response from the eShopWorld Package API:
Code Description Sync action
204 Success Update record status to Synchronized.
400 Bad Request1001 The invalid model status: Update record status to Error.101 Required brand code status: Leave current record status.301 Invalid brand code status: Leave current record status.
- 15 -
Code Description Sync action
316 Invalid number of package references status: Update record status to Error. 317 Required order references status: Update record status to Error. 318 Eshop setup error status: Leave current record status.400 Invalid AsnApiRequest error status: Leave current record status. 999 General error: Update record status to Error.
401 Unauthorized Leave current record status
404 Not Found Leave current record status
500 Server Error Leave current record status
3.6.1.3 Administration interface
Shipments grid
l eShopWorld synchronization status column with current shipment status.
l Action to push the shipment to eShopWorld.
Shipment details view
- 16 -
l Action to push the shipment to eShopWorld.
l eShopWorld sync information and status action in the block section. You can manually change the shipment sync status to any listed status.
3.6.2 Ship from Store (Hubless model)
The Ship from Store, also known as Hubless model, is a shipping model that allows retailers to ship the goods directly to the shoppers using eShopWorld’s Ship from Store application. To use the Ship from Store model, a shipment must be created in Magento to complete the full order process flow and order processing within Magento.
Key features:
l Integration with the eShopWorld Package API using the GET endpoint.
l Creation of shipments on Magento based on the GET endpoint.
l Cron job, which can be set for x frequency to run the GET endpoint.
l Additional custom data stored in the custom eShopWorld tables on Magento.
- 17 -
l Serial Number/Unique engraving number (UEN), WarrantyID, packageReference, car-rierReference, and eswpackageReference, which are stored in the eshopworld_shipment table.
l Native Magento shipment tracking.
3.6.2.1 Ship from Store flow
The following diagram explains the Ship from Store model:
- 18 -
1. Shopper adds an item to their cart on Magento (Magento Quote table). This is the native Magento shopper journey.
2. When the shopper clicks Checkout, a call is made to the eShopWorld Checkout API. The Checkout API request is integrated with the eShopWorld extension, which sends eShopWorld Magento cart information, such as product information, shipping country,
- 19 -
currency, locale, shipping rates (if setup) and customer details (if the shopper is logged in). eShopWorld generates hosted checkout based on the data received and responds with the Checkout URL to redirect the shopper.
3. The eShopWorld hosted Checkout is generated based on the data.
4. The shopper enters their delivery details, payment details and clicks Pay Now.
5. The payment is authorized and an order created in the eShopWorld system.
6. The order confirmation request is sent from eShopWorld to Magento to confirm payment successfully. The order confirmation request contains additional order information, such as a breakdown of the order including tax and duty in the shopper currency and retailer currency.
7. The order is created based on the quote in Magento. The invoice is created and the order status is updated to Processing. Additional custom data from step 6 is saved in the eShopWorld custom tables within Magento. The data can be viewed via the Admin panel.
8. The order confirmation response is received from Magento to ESW. When the success response is received by eShopWorld, the payment is captured between 30 minutes to 2 hours and 30 minutes later. The order confirmation request is attempted thrice with a waiting time of one minute for a success response. If a response is not received within the time limit, the order is automatically cancelled in eShopWorld’s database, which can potentially cause misalignment of the order status. If an error response is sent by Magento, for example, due to issues with stock, the order is cancelled.
9. The Order Confirmation page hosted by eShopWorld is displayed to the shopper.
10. The order exists in the Ship from Store application. Orders with successful payment are synchronized across eShopWorld’s systems and therefore exist in the Ship from Store application. An email notification will be sent to the store clerk to advise when an order will exist in the Ship from Store application ready for processing.
11. The store clerk processes the order and enters additional information, for example, a unique number and warranty ID.
12. Material information, for example, Carat content is added to the commercial invoice (for cross-border only).
13. The shipment label is printed and collected by the courier.
14. The Ship from Store application updates eShopWorld database with Shipped status.
- 20 -
15. Magento reads shipments from the eShopWorld database since the last update and cre-ates shipments in Magento including UEN and tracking ID. Shipment synchronisation cron job runs every x minutes. The job queries the eShopWorld Package API, which returns all shipments created between timestamps. The From timestamp will be from the last time the job has run and the To timestamp is the current time. The query will return order number, SKU ID, quantity, UEN, and package ID. This information will be used to create a ship-ment in Magento. The Package Reference is recorded as the tracking number and eShopWorld is set as the carrier. This automatically sets the tracking URL in the backend admin and customer account section.
16. Magento updates the order status to Complete once a shipment is created for the full order. This is as per the native Magento order process.
17. Tracking order or returns are managed via the eShopWorld Tracking Portal and Returns Portal respectively.
3.7 Returns IntegrationThe eShopWorld Magento extension allows you to create returns and issue refunds in Magento based on processed returns in eShopWorld’s hub. eShopWorld's return model allows shoppers to send their return orders either to the eShopWorld hub or directly to your warehouse. In order to keep systems synchronized, you can enable returns synchronization within the eShopWorld extension. Only the Hub model synchronization is currently supported. To learn more about the Returns Configuration, "Returns Configuration" on page 46.
In the case of returns, a hub model is when a shopper returns goods to the eShopWorld distribution hub. When eShopWorld receives a return package, a clerk inspects the package before authorizing the refund. Each item from return must be accepted or rejected. After the package passes the inspection, eShopWorld changes the return status to Proceed. This happens in real time. During the cron job run, the Magento extension requests the returns with the Approved status. Returned records are then replicated in Magento by creating the selected Magento entity type.
- 21 -
3.7.1 Magento Entity Types
You can select the type of entity that will be created in Magento when approved eShopWorld returns are synchronized. The options are Credit Memo and Return Merchandise Authorization (RMA).
l Credit Memo: When this option is selected, the Magento extension creates an offline credit memo during the synchronization process. Only accepted line items are included in the credit memo. The credit memo grand total value matches the refunded amount (subtotal, shipping and tax that is combined value of tax and duty), and the extension saves the return reasons per item in a custom database table. To display the return reason in the admin credit memo view, customize the the credit memo template.
- 22 -
l
l Return Merchandise Authorization (RMA): This option is only available for the Magento Enterprise Edition, which supports RMA. When RMA is selected, the eShopWorld Magento extension creates an RMA entry during the synchronization process. Both approved and rejected items are be part of the RMA. Rejected item is saved with status Return received and approved with status Authorized. The Magento RMA item return reason codes are extended to match the options supported by eShopWorld.
3.8 Catalog IntegrationeShopWorld requires a product catalog from retailers to allow eShopWorld to assign the correct duties and taxes. This information is used for checkout calculations, customs and duty declarations when operating a cross border business and other downstream processes.Catalog integration exports catalog data plus additional custom attributes via Magento using product information that exists in Magento. The data is sent to eShopWorld and synchronized.
- 23 -
Catalog configuration has preselected default mapping of Magento product attribute that are required by eShopWorld.Some required fields for eShopWorld catalog integration do not exist in default Magento attributes. The extension creates three additional product attributes during installation or update of the eShopWorld Magento extension. Custom attributes created by the extension are:
l HS Code
l HS Region
l Material Description
These attributes are available under Products View in the eShopWorld section.
Catalog exports to eShopWorld can be triggered using the Export to eShopWorld Catalog option under Actions. Once the products are added to the queue, they are synchronized by message queues in Magento. The PHP setting "max_input_vars" limits the number of inputs that can be set when posting forms. To increase the limit, change to max_input_vars in php.ini.
- 24 -
Note: Catalog integration works only with simple products, as displayed in the "Type field".For most attributes, the source value data can be a "Parent" product. For more information, seeConfiguration > Product Attributes Mapping.
- 25 -
4 Installation and setupThis section describes how to install the eShopWorld Magento extension. To adhere to the best practices and manage extension dependencies correctly, use Composer for the installation and update process.
Always install the downloaded extension on a staging server first to detect any issues that might arise. Before migrating, take a backup of your Production environment.
4.1 Installing the extensionTo install the extension:
1. Create a packages folder in the Magento root directory.
2. Create an eshopworld folder within the packages folder that you just created.
3. Place the module-eshopworld.{version}.zip file inside the packages/eshopworld folder.
4. From the Magento root directory, run the composer config repositories.eshopworld-checkout "artifact"
"packages/eshopworld command. The following entry is created in the composer.json file:
5. From the Magento root directory, run the composer update eShopWorld/module-checkout:{version} command.
6. From the Magento root directory, run the php bin/magento setup:upgrade command.
7. From the Magento root directory, run the php bin/magento cache:clean command.
- 26 -
8. Update permissions on the localhost folder for var/cache, generated, pub. For more information on permissions, click here.
4.2 Verifying the installationTo verify the installation:
1. Sign in to the Magneto 2 administration panel using your credentials.
2. Navigate to Stores > Configuration > Advanced > Advanced.
4.3 Accessing the extensionTo access the extension:
1. Sign in to the Magneto 2 administration panel using your credentials.
2. Navigate to eShopWorld > Configuration.
4.4 Viewing configurationTo view the configuration:
1. Sign in to the Magento 2 administration panel using your credentials.
2. Navigate to eShopWorld > Configuration. The extension settings are organized in nes-ted logical tabs.
- 27 -
- 28 -
5 ConfigurationThis chapter provides instructions on the Magento configuration required to set up eShopWorld's Magento Plugin.
5.1 Setting up Magento for Fixed price modeleShopWorld's Magento extension uses the native Magento configuration to setup countries to be displayed on the eShopWorld landing page and footer. eShopWorld's module pulls the countries from all allowed countries in Magento websites to create a list on the landing mat and footer.
l The Fixed Pricing model is used by default for a country if the Magento base currency is equal to the current shopper display currency. You can override this using the Force FX Pricing Model Countries option under Pricing Configuration.
l The Calculated Pricing model is used by default for a country if the Magento base cur-rency is not equal to the current shopper display currency.
5.1.1 Country and Currency setup l To set up a Fixed Price country, add the country to Allowed Countries in Stores > Con-
figuration > General > Allowed Countries.
l To set up the currency to be used, add Base Currency in Stores > Configuration > Currency Setup. The same currency must be set up in Default Display Currency as well as Allowed Currencies.
5.2 Setting up Magento for the Calculated Pricing modelThe Calculated Pricing model works by utilizing eShopWorld’s Pricing Advisor to convert a retailer's Magento global or website-level price and applying eShopWorld’s custom formula to display the in-country prices.
5.2.1 Prerequisites l Pricing Advisor must be set up to use the Calculated Pricing model. Each retailer has a
different configuration because the estimated duty and tax varies based on the product set and average order value in each target market.
- 29 -
l Pricing Advisor must be run at least once to populate the currency rates and the custom eShopWorld data required to generate the eShopWorld calculated price. You can run Pri-cing Advisor manually by setting the Import Service (Stores > Currency Rates) to EShopWorld FxRates.
5.2.2 Country and currency setup
You can set up the country and currency relationships by navigating to eShopWorld > Checkout > Country - Currency Mapping. Each country supports a single currency and the defaults are automatically setup within the installation.
l To set up the Calculated Pricing model countries, add the country to the allowed countries (Stores > Configuration > General > Allowed Countries). The allowed countries are included in the Country selector on the landing mat and footer.
l To set up the currency to be used, add the currency as the base currency (Stores > Con-figuration > Currency Setup).
l If different Default Display Currency and Allowed Currencies are set up, then the Calculated Pricing model is enabled for the selected country at the website level.
l If a different Default Display Currency cannot be set up, then the Fixed Pricing model is enabled for the selected country. However, if you want to use the Calculated Pricing model, then an override must be set in eShopWorld > Checkout > Pricing Configuration > Force Calculated Pricing Model Countries.
Notes:
l A single website can support multiple countries using the Calculated Pricing model, Fixed Pricing model, and native domestic countries.
l All currencies that will be supported by the Pricing Advisor must be enabled in the default configuration (Stores > Configuration > Currency Setup > Allowed Cur-rencies).
l All currencies that are enabled at the website-level for the Calculated Price model must be enabled at the 'Default Config' level to allow the Calculated Pricing cron to update the foreign exchange rates.
l The countries for which the tax is added and displayed separately in the Totals sec-tion at the eShopWorld Checkout can be set up using the eShopWorld Tax on Check-out Side Only Countries option under Pricing Configuration.
- 30 -
6 Security Token ServiceeShopWorld APIs and User Interface are secured using a single security system called Security Token Service (STS). eShopWorld uses the STS platform to issue, validate as well as renew security tokens that are required to authenticate with eShopWorld APIs and access API endpoints.
6.1 Security Token Configuration
Option Description Scope
EnvironmentDefines the eShopWorld API environment. The options are Sandbox and Production.
Website
Client Id Unique identifier assigned to a client. Website
Client Secret
Unique secret assigned to a client. Website
After entering the details, click Test credentials to validate the credentials.
- 31 -
7 Checkout This chapter describes the following configuration options:
l General
l Pricing Feed
l Country-Currency Mapping
l Retailer Display
l Pricing
l Preorder Expansion Pairs
l Preorder URL
l Order Confirmation
7.1 General ConfigurationThis tab contains options to enable the checkout extension features. For the extension to work, you must provide information in each of the fields:
The following table describes the General Configuration options:
- 32 -
Option Description Dependency Scope
Extension Version
Read-only version number of the installed plugin. None Global
Checkout Functionality Enabled
Indicates if the eShopWorld Checkout is enabled. None Global
Preorder Schema
Defines the schema to be used by the Preorder API call. The option is only available for 1.0.
None Global
eShopWorld Checkout Countries
Defines the countries for which the extension is enabled. When the shopper's country is one of the countries defined here, they are redirected to the eShopWorld Checkout.
None Global
7.2 Pricing Feed ConfigurationThis tab contains configuration options for the FX Rates synchronization.
- 33 -
The following table describes the Pricing Feed Configuration options:
Option Description Dependency Scope
Pricing Feed Enabled
Enables or disables the functionality. None Website
Rates Syn-chronisation Start Time
Determines the time when Magento 2 checks the FX rates for any changes. This check takes places daily.
None Global
Rates Syn-chronisation Stop Time
Determines the time when Magento 2 stops checking for new FX rates and coun-try adjustments.
None Global
Frequency of Requests
Determines the frequency at which the FX rate changes should be checked.
None Global
Last Update Date
Read-only date when FX rates were updated.
None Website
Automatically Clean FPC and Block HTML Cache After Rate Import
Defines if the FPC and the Block HTML cache should be refreshed automatically after the FX rate import.
None Global
7.3 Country – Currency MappingWhen this feature is enabled, the country and currency are mapped as a combined selection from a single dropdown menu on the Welcome Mat and/or Footer bar. You can enable this feature by setting Country – Currency Display Together on Landing Page and/or Country - Currency Display Together on Footer Bar to Yes in the Retailer Display Configuration panel.
- 34 -
7.4 Retailer Display ConfigurationRetailer Display refers to the landing page and footer bar that can be toggled on or off. This tab allows you to configure the retailer display to suit your requirements.
- 35 -
The following table describes the Retailer Display Configuration options:
Option Description Scope
GeoIP Location
Defines whether MaxMind GeoIP service will be used to determine shopper location and pre-select matched store.
The domain to work with MaxMind GeoIP service must be whitelisted by eShopWorld first. If the GeoIP is disabled, the default store will be used.
Global
Country - Currency Display Together
Defines whether the country and currency are displayed together.
Global
Enable Countries Selector
Defines whether the countries selector will be available for shoppers to select their shipping country.
Global
Enable Currencies Selector
Defines whether the currency selector will be available for shoppers to select their preferred shopping currency.
Global
Enable Landing Page
Defines whether the landing page is enabled. If you select Yes, the landing page will be displayed where shoppers can select the preferred language, currency, and country.
Global
Enable Language Selector on Land-ing Page
Defines whether the language selector will be available on the landing page.
Global
Enable Footer Bar
Defines whether the same selectors as per the landing page will be available in the footer area. If you select Yes, the same set of selectors will be displayed in the footer area.
Global
Enable Language Defines whether the languages selector will be available Global
- 36 -
Option Description Scope
Selector in Footer Bar
in the footer bar.
7.5 Pricing ConfigurationThis tab contains the Pricing configuration.
The following table describes the Pricing Configuration options:
- 37 -
Option Description Scope
eShopWorld Tax on Checkout Side Only Countries
Indicates the countries where tax is added and dis-played separately on the eShopWorld checkout under Total and is not part of the subtotal.
Global
Force Calculated Price Model Coun-tries
Indicates countries that will use the Calculated pricing model even if the Magento base currency is the same as customer display currency. This model uses the retailer's base currency with the pricing feed cal-culations (FX, retailer uplift, duty and taxes) applied.
Global
7.6 Preorder Expansion Pairs ConfigurationThis tab contains the attribute mappings configuration. eShopWorld checkout allows retailers to send additional product attributes with the preorder request. On this tab, you can define the relationship between the store attributes and the eShopWorld extension attributes. If any mapping attribute is not defined, the attribute is not sent in the request. The following table describes the Preorder Expansion Pairs Configuration options:
- 38 -
The following table describes the PreOrder Expansion Pairs Configuration options:
Option Description Scope
Catalog codeDefines the catalog code attribute, which will be passed in the preorder request.
Global
Color codeDefines the color code attribute, which will be passed in the pre-order request.
Global
Color descrip-tion
Defines the color description attribute, which will be passed in the preorder request.
Global
Size code Defines the size code attribute, which will be passed in the pre- Global
- 39 -
Option Description Scope
order request.
Style codeDefines the style code attribute, which will be passed in the pre-order request.
Global
Is per-sonalised
Defines the Is personalised attribute, which will be passed in the preorder request.
Global
Monogram text
Defines the monogram text attribute, which will be passed in the preorder request.
Global
Monogram colour
Defines the monogram colour attribute, which will be passed in the preorder request.
Global
Gift wrappedDefines the Gift wrapped attribute, which will be passed in the preorder request.
Global
Is return pro-hibited
Defines the Is return prohibited attribute, which will be passed in the preorder request.
Global
7.7 Preorder URL ConfigurationThis tab contains configuration related to preorder callback URLs.
- 40 -
The following table describes the PreOrder Url Configuration options:
Option Description Dependency Scope
Order Noti-fication Url
Defines the URL that is used for order confirmation. N/A indicates eshopworld/order/confirm as a default url, if empty - not set.
l For preorder schema 2.0, this functionality only works for eShopWorld checkout Sandbox environment.
l For production, this field should be empty.
l For an empty record, a predefined value is used from the eShopWorld database.
None Global
Continue Shopping Url
Defines the URL that is used when a shopper clicks Continue Shopping at the checkout. N/A indicates base url as a default URL, if empty - not set. For an empty record, a predefined value is used from the eShopWorld database.
None Global
Back to Cart Url
Defines the URL that is used when a shopper clicks Back to Cart on the checkout. N/A indicates check-out/cart as a default URL, if empty - not set. For an empty record, a predefined value is used from the
None Global
- 41 -
Option Description Dependency Scope
eShopWorld database.
7.8 Order Confirmation ConfigurationThis tab contains configuration related to the order confirmation request. The Order confirmation schema must match the configuration agreed with eShopWorld:
The following table describes the Order Confirmation Configuration options:
Option Description Dependency Scope
Enable Basic Auth for Order Confirmation
Defines if the basic auth credentials, that is, the username and password should be val-idated during order confirmation. eShopWorld recommends that you enable this option to secure order confirmation callback URL from unauthorized third-party requests.
None Global
Username A unique username provided by a user.
Enable basic authentication for order con-firmation
Global
Password A unique password provided by the user.Enable basic auth for order confirmation
Global
Order StatusDefines the order status of a newly created order. Default indicates the default Magento
None Global
- 42 -
Option Description Dependency Scope
order status. Paid indicates the invoices cre-ated automatically.
- 43 -
8 Order Fulfillment The Order Fulfillment screen allows you to specify the General, Package/ASN, and Returns configuration options to enable the package extension features.
8.1 General ConfigurationThe following table describes the General Configuration options:
Option Description Dependency Scope
Extension Ver-sion
Read-only version number of the installed extension.
None Global
Brand Code Retailer-specific identifier. None Website
8.2 Package/ASN ConfigurationThe following table describes the Package/ASN Configuration option. To learn about the Package integration, including Hub model and Ship from Store model, see "Package Integration " on page 10.
Option Description Dependency Scope
Enable Pack- Indicates if the eShopWorld package syn- None Global
- 44 -
Option Description Dependency Scope
age/ASN chronization is enabled.
When you select Yes in the Enable Package/ASN field, the following additional fields are displayed:
Option Description Dependency Scope
Model
Indicates the package model to use. The options are Hub Model and Hubless - Ship from Store, and Mixed - Specified Per Country.
l When you select Hubless - Ship from Store, the Last Update Date field is displayed. This is a read-only date and time when the shipments were synchronized.
l When you select Mixed - Specified Per Country, the Country-Model field is displayed, which allows you
None Global
- 45 -
Option Description Dependency Scope
to configure package/ASN with a dif-ferent model per country.
Enable Cron Synchronization
Indicates if the eShopWorld package syn-chronization is enabled.
None Global
Cron FrequencyRun the POST API call every x minutes to send the package data to eShopWorld.
Enable Cron Synchronization: Yes
Global
Batch SizeNumber of packages to send each POST API call.
Enable Cron Syncronization: Yes
Global
8.3 Returns ConfigurationThe following table describes the Returns Configuration option. To learn about the Returns Hub model, see "Returns Integration" on page 21.
Option Description Dependency Scope
Enable Returns Integration
Indicates if the eShopWorld returns syn-chronization is enabled.
None Global
When you select Yes in the Enable Returns Integration field, the following additional fields are displayed:
- 46 -
Option Description Dependency Scope
Return Type
Defines what type of Magento entity will be created during sync. The options are Credit Memo and RMA. RMA is only available for Enterprise edition.
None Global
Model Defines the model to use. None Global
Country - ModelDefines the model that can be in use for the specified country.
Model: Mixed - Specified Per Country
Global
Last Update Date
Read-only date and time when the returns were synchronized.
None Website
Enable Cron Synchronization
Defines if the cron should synchronize records between eShopWorld and Magento.
None Global
Cron Frequency Defines how often the cron job will run.Enable cron synchronization
Global
- 47 -
9 Catalog9.1 General ConfigurationThe following table describes the General Configuration options:
Option Description Dependency Scope
Enable Cata-log
Indicates if the eShopWorld catalog export is enabled.
None Website
Prodict Attrib-utes Mapping
Configuration to setup mapping between eShopWorld attributes and Magento product attributes. Source pri-ority indicates priority order for product attribute value.
None Website
- 48 -
- 49 -
10 Logs 10.1 General ConfigurationThis tab allows you to enable or disable the Log feature.
The following table describes the Log Cleaning Configuration option:
Option Description Scope
Enable Logs Indicates if the Log feature is enabled. Global
10.2 Logs CleaningThis tab allows you to enable or disable the Log Cleaning feature.
The following table describes the Log Cleaning Configuration options:
Option Description Scope
Enable Log Cleaning Cron
Indicates if the Log Cleaning feature is enabled. Global
Cron Frequency Time when the cron job will run. Global
Days to Store Log Number for days for which the logs should be retrained Global
- 50 -
Option Description Scope
Data Before Deleting before they are removed from the database.
- 51 -
11 Shipping RatesOn the Shipping Rates screen, you can define the shipping rate overrides. This is the configuration section for the eShopWorld supported functionality. You can define the shipping rates to be passed along with the preorder request. The way shipping rates are applied can be defined through the Magento 2 built-in mechanism, which acts the same as the Magento 2 default cart price rules. When these shipping rates are defined, the extension validates them during the preorder request. If the shipping rates apply to the active customer cart, the rates information is passed over to eShopWorld API along with the preorder request.
- 52 -
12 Extension LogsThe Extension Logs screen displays logs that are created by the extension. The extension creates logs on sending and receiving the preorder request, sending pricing update requests, handling order confirmation requests, and package post requests.
- 53 -
13 Order ConfirmationOrder confirmation supports the separation of the order data into separate tabs. The Order View tab can be accessed by clicking Sales in the left panel and then selecting View from the Actions list for an order. For more information, see the Magento documentation.
13.1 Order Confirmation v2.0The order-level, item-level, and discount-level details are displayed on the eShopWorld Order, eShopWorld Order Items, eShopWorld Cart Discounts tabs respectively that you can access under Order View.
13.1.1 eShopWorld Order
This tab displays the order-level details. These attributes are passed in from eShopWorld's Order Confirmation request.
The following table describes the eShopWorld order attributes:
Field Type Allow null Description
Entity ID int (10) no Unique ID.
Retailer Cart Idvarchar (255)
no Order number or cart identifier for the retailer.
- 54 -
Field Type Allow null Description
Order numbervarchar (255)
no Order number or cart identifier of the brand.
Retailer Cur-rency Payment Amount
varchar (100)
yesThree-letter identifier of the retailer currency in the ISO 4217 format and the amount paid in the retailer currency.
Shopper Cur-rency Payment Amount
varchar (100)
yesThree-letter identifier of the shopper currency in the ISO 4217 format and the amount paid in the shopper currency.
Retailer Fx Group Id
varchar (255)
yes
Value of the retailerFxGroupId being used. If no value is provided, either the latest retailerFxGroupId that exists in the eShopWorld database is used.
Payment Timevarchar (255)
yesDate and time when the order was preau-thorised or payment was made.
Payment methodvarchar (255)
yes Details of the payment method.
Payment Method Card Brand
varchar (255)
yes Card brand information.
Fraud holdvarchar (255)
yesIndicates if there is any fraud hold or fraudulent activity.
Retailer Promo Codes
text yes Promo code applied.
Delivery Country varchar yes ISO 3166 format two-letter country identifier for
- 55 -
Field Type Allow null Description
Iso (20) the delivery country.
Shopper culture language ISO
varchar (20)
yesLanguage ISO code for the shopper in the ISO 639-1 format.
Email marketing opt in
integer(11)
yesIndicates if the shopper wants to subscribe to the email marketing.
Delivery Optionvarchar (255)
yes Preferred delivery option for the shopper.
Retailer currency delivery price before discount
varchar (255)
yes Price before the discount is applied.
Retailer currency delivery price dis-count amount
varchar (255)
yes Amount of the discount.
Retailer currency delivery price dis-count percentage
varchar (255)
yes Percentage value of the discount.
Retailer currency delivery price
varchar (255)
yes Order delivery charge in the retailer currency.
Retailer currency delivery price title
varchar (255)
yes Price title.
Retailer currency delivery price description
varchar (255)
yes Price description.
- 56 -
Field Type Allow null Description
Shopper cur-rency delivery price before dis-count
varchar (255)
yes Price before the discount is applied.
Shopper cur-rency delivery price discount amount
varchar (255)
yesDiscount amount in shopper currency on deliv-ery price.
Shopper cur-rency delivery price discount percentage
varchar (255)
yesDiscount percentage in shopper currency on delivery price.
Shopper cur-rency delivery price
varchar (255)
yes Order delivery charge in the shopper currency.
Shopper cur-rency delivery price title
varchar (255)
yes Price title.
Shopper cur-rency delivery price description
varchar (255)
yes Price description.
Delivery Option Metadata Items
text yesKey-value pairs used for passing additional details.
Shopper Cur-rency Total
varchar (100)
yes Merchandise cost in the shopper currency.
- 57 -
Field Type Allow null Description
Shopper Cur-rency Delivery
varchar (100)
yes Delivery cost in the shopper currency.
Shopper Cur-rency Delivery Duty
varchar (100)
yesDuty on the delivery cost in the shopper cur-rency.
Shopper Cur-rency Delivery Taxes
varchar (100)
yes Taxes on delivery cost in the shopper currency.
Shopper Cur-rency Taxes
varchar (100)
yes Taxes in the shopper currency.
Shopper Cur-rency Other Taxes
varchar (100)
yes Other taxes in the shopper currency.
Shopper Cur-rency Admin-istration
varchar (100)
yesOrder administration charge in the shopper cur-rency.
Shopper Cur-rency Duty
varchar (100)
yes Duty in the shopper currency.
Shopper Cur-rency Uplift
varchar (100)
yes Uplift in the shopper currency.
Retailer Cur-rency Total
varchar (100)
yes Merchandise total in the retailer currency.
Retailer Cur-rency Delivery
varchar (100)
yes Delivery cost in the retailer currency.
- 58 -
Field Type Allow null Description
Retailer Cur-rency Delivery Duty
varchar (100)
yesDuty on the delivery charge in the retailer cur-rency.
Retailer Cur-rency Delivery Taxes
varchar (100)
yesTaxes on the delivery charge in the retailer cur-rency.
Retailer Cur-rency Taxes
varchar (100)
yesTaxes element in the overall Order Payment amount in the retailer currency.
Retailer Cur-rency Other Taxes
varchar (100)
yesOther taxes element in the overall Order pay-ment amount.
Retailer Cur-rency Admin-istration
varchar (100)
yes Administration charge in the retailer currency.
Retailer Cur-rency Duty
varchar (100)
yes Duty charge in the retailer currency.
Retailer Cur-rency Uplift
varchar (100)
yes Uplift in the retailer currency.
Created at timestamp no
13.1.2 eShopWorld Order Items
This tab displays the item-level details. These attributes are passed in from eShopWorld's Order Confirmation request.
- 59 -
Field Type Allow null Description
Entity ID int (10) no Unique ID.
Order numbervarchar (255)
no Order number or cart identifier of the brand.
Quantity int (10) yes Quantity of the product unit.
Product Codevarchar (255)
yesRetailer’s unique identification code or SKU for the order article.
UPCvarchar (255)
yes12-digit Universal Product Code assigned to each item.
Product HS Code
varchar (255)
yes HS code of the product.
Product titlevarchar (255)
yes Title of the product.
Product descrip-tion
varchar (255)
yes Description of the product.
- 60 -
Field Type Allow null Description
Retailer Cur-rency Price Info Before Discount
varchar (100)
yes
Price before the discount is applied in the retailer currency. The value is a combination of a three-let-ter currency identifier (in the ISO 4217 format) fol-lowed by a number.
Retailer Cur-rency Price Info Discount Amount
varchar (100)
yesAmount of the discount in the retailer currency. The value is a combination of a three-letter identifier (in the ISO 4217 format) followed by a number.
Retailer Cur-rency Price Info Discount per-centage
varchar (100)
yes Discount percentage in the shopper currency.
Retailer Cur-rency Price Info Price
varchar (100)
yes
Retailer Cur-rency Price Info Title
varchar (255)
yes Price title.
Retailer Cur-rency Price Info Description
varchar (255)
yes Price description.
Shopper Cur-rency Price Info Before Discount
varchar (100)
yes
Price before the discount is applied in the shopper currency. The value is a combination of a three-let-ter currency identifier (in the ISO 4217 format) fol-lowed by a number.
- 61 -
Field Type Allow null Description
Shopper Cur-rency Price Info Discount Amount
varchar (100)
yesAmount of the discount in the shopper currency. The value is a combination of a three-letter identifier (in the ISO 4217 format) followed by a number.
Shopper Cur-rency Price Info Discount per-centage
varchar (100)
yes Discount percentage in the shopper currency.
Shopper Cur-rency Price Info Price
varchar (100)
yes
Shopper Cur-rency Price Info Title
varchar (255)
yes Price title.
Shopper Cur-rency Price Description
varchar (255)
yes Price description.
Product Image Url
varchar (255)
yes Thumbnail image URL of the product.
Product Colorvarchar (255)
yes Color of the item.
Product Sizevarchar (255)
yes Size of the item.
Product Is Non integer yes Indicates whether the product is a non-standard
- 62 -
Field Type Allow null Description
Standard Cata-log Item
catalog item.
Product Metadata Items
text yes Key-value pairs used for passing additional details.
Estimated Deliv-ery Date
varchar (255)
yes Estimated delivery date of the cart items.
Line Item Idvarchar (20)
yes Item sequence or the ID of the line item.
Shopper Cur-rency Item Sub Total
varchar (20)
yesItem subtotal, that is, the value of the merchandise in the shopper currency.
Shopper Cur-rency Item Uplift
varchar (20)
yes Item uplift in the shopper currency.
Shopper Cur-rency Item Deliv-ery
varchar (20)
yes Item delivery charge in the shopper currency.
Shopper Cur-rency Item Deliv-ery Duty
varchar (20)
yes Item delivery duty in the shopper currency.
Shopper Cur-rency Item Deliv-ery Taxes
varchar (20)
yes Item delivery taxes in the shopper currency.
Shopper Cur- varchar yes Item taxes charge in the shopper currency.
- 63 -
Field Type Allow null Description
rency Item Taxes
(20)
Shopper Cur-rency Item Other Taxes
varchar (20)
yes Other taxes charge in the shopper currency.
Shopper Cur-rency Item Administration
varchar (20)
yes Item administration charge in the shopper currency.
Shopper Cur-rency Item Duty
varchar (20)
yes Item duty charge in the shopper currency.
Retailer Cur-rency Item Sub Total
varchar (20)
yesItem subtotal, that is, the value of the merchandise in the retailer currency.
Retailer Cur-rency Item Uplift
varchar (20)
yes Taxes on delivery cost in the shopper currency.
Retailer Cur-rency Item Deliv-ery
varchar (20)
yes Item delivery charge in the retailer currency.
Retailer Cur-rency Item Deliv-ery Duty
varchar (20)
yes Item delivery duty in the retailer currency.
Retailer Cur-rency Item Deliv-ery Taxes
varchar (20)
yes Item delivery taxes in the retailer currency.
- 64 -
Field Type Allow null Description
Retailer Cur-rency Item Taxes
varchar (20)
yes Item taxes charge in the retailer currency.
Retailer Cur-rency Item Other Taxes
varchar (20)
yes Other taxes charge in the retailer currency.
Retailer Cur-rency Item Administration
varchar (20)
yes Item administration charge in the retailer currency.
Retailer Cur-rency Item Duty
varchar (20)
yes Item duty charge in the retailer currency.
Metadata Items text yes Key-value pairs used for passing additional details.
13.1.3 eShopWorld Order Cart Discounts
The following table describes the ESW cart discounts attributes:
Field Type Allow null Description
Entity ID int (10) no Unique ID.
Order numbervarchar (255)
noOrder number or cart identifier of the brand.
Titlevarchar (255)
yesTitle of the promotion or voucher code.
Descriptionvarchar (255)
yesDescription of the promotion or voucher code.
- 65 -
Field Type Allow null Description
Retailer Currency Cart Discount Before Discount
varchar (100)
yesPrice before the discount is applied.
Retailer Currency Cart Discount Amount
varchar (100)
yes Amount of the discount.
Retailer Currency Cart Discount Percentage
varchar (100)
yesPercentage value of the dis-count.
Retailer Currency Cart Discount Price
varchar (100)
yes Price.
Retailer Currency Cart Discount Title
varchar (255)
yes Price title.
Retailer Currency Cart Discount Description
varchar (255)
yes Price description.
Shopper Currency Cart Discount Before Discount
varchar (100)
yesPrice before the discount is applied.
Shopper Currency Cart Discount Amount
varchar (100)
yes Amount of the discount.
Shopper Currency Cart Discount Percentage
varchar (100)
yesPercentage value of the dis-count.
Shopper Currency Cart Discount Price
varchar (100)
yes Price.
Shopper Currency Cart Discount Title
varchar (255)
yes Price title.
- 66 -
Field Type Allow null Description
Shopper Currency Cart Discount Description
varchar (255)
yes Price description.
- 67 -
14 Developer14.1 Setting up the Varnish cacheThis allows the calculated pricing model to work with Varnish cache. The value of the cache key must include the eShopWorld currency (esw-currency) or the location (esw-location) cookie. For example:
sub vcl_hash {
if (req.http.cookie ~ "X-Magento-Vary=" || req.http.cookie ~ "esw.-currency=")
{ hash_data(regsub(req.http.cookie, "^.*?X-Magento-Vary=([^;]+);*.*$", "\1") + regsub(req.http.cookie, "^.*?esw.currency=([^;]+);*.*$", "\1")); }
#For multi site configurations to not cache each other's content
if (req.http.host) { hash_data(req.http.host); }
else
{ hash_data(server.ip); }
#To make sure http users don't see ssl warnin
if (req.http.X-Forwarded-Proto) { hash_data(req.http.X-Forwarded-Proto); }
}
Varnish rules can also be updated via Vary header. For example:
#Recv
if (req.http.Cookie ~ "esw.currency=") {
set req.http.Esw-currency = regsub(req.http.cookie, "^.*?esw.currency=([^;]+);*.*$", "\1");
} else {
set req.http.Esw-currency = "";
}
#Fetch
- 68 -
if (beresp.http.Content-Type ~ "text/(html|xml)") {
if (beresp.http.Vary) {
set beresp.http.Vary = beresp.http.Vary ",Esw-currency";
}
}
14.2 Setting the package reference
This section applies to the Hub shipping model only. To learn about this model, including the model features and flow, see "Hub model" on page 10.
The package reference can be set when you are creating shipments. If no package reference is set, the order increment ID from Magento is set as the package reference. The limitation with using order increment ID is that only full order shipments are supported. If you require split shipment, then package reference must be set according to the tracking specification using native Magento Shipment API. eShopWorld’s Magento extension sends package data to eShopWorld based on the shipments created for eShopWorld orders in Magento. You can create shipments in Magento and have the option to set a package_reference in eshopworld_shipment.
l To populate package_reference in eshopworld_shipment, you can use the native Magento shipment API and populate new extension attribute package_reference, as shown in the following image:
- 69 -
14.2.1 Package reference in the Magento Shipment API
When the Package API is triggered via cron, shipments with the Pending synchronization status are sent to eShopWorld. If no value is set in package_reference in eshopworld_shipment table, the order increment ID will be set as package_reference in eshopworld_shipment and sent to eShopWorld. If a value exists in package_reference in eshopworld_shipment, then this value is sent to eShopWorld.
l The tracking information is updated in Magento shipment on the successful run of the Package API. eShopWorld is set as carrier and tracking ID will be set as package_reference. This will update all native Magento views, such as customer account and backend admin to add tracking links to eShopWorld’s tracking portal.
l The weight from the Magento shipment is sent to eShopWorld as part of package integ-ration. If no weight is set in the shipment, product weight from the order item is used.
14.3 Cookies l esw-location:Determines the shipping address of the shopper. If value is not present,
the default store country from configuration is used.
l For example: esw-location:{"country":{"iso_code":"US"}}
l esw-currency: Used by extension for front-end widgets selectors to track current cur-rency
- 70 -
l For example: esw-currency:USD
l esw-geoip: Determines if geoip should be used to get shopper current country location.
l esw-landing-played: Determines if welcome-mat widget was already displayed for shop-per.
14.4 Extension APIThe eShopWorld extension provides an API for requesting eShopWorld’s redirect checkout URL. This functionality can be used to build a headless commerce experience with the eShopWorld checkout.Guest checkout requestPOST /V1/eshopworld/checkout/guest-carts
BODY PARAMS
cart_id* (string)
Cart identifier.
RESPONSE 200
String url
Url to eShopWorld checkout
Logged in user checkout requestPOST /V1/eshopworld/checkout/carts/mine
HEADER PARAMS
Authorization: Bearer <customer authentication token>
RESPONSE 200
String url
Url to eShopWorld checkout
By default, the source of the shipping country for eShopWorld extension is taken from the Magento configuration: Country options → default country.
- 71 -
If more countries are allowed within Magneto configuration for one store, the extension allows you to set a different shipping country via the header in the API request.Set shipping country used by extension in API call1. Via Header in requestESW-COUNTRY: {{country abbreviation ISO-3166-1 ALPHA-2}}example: ESW-COUNTRY:US2. Via Cookie in request
14.5 Frontend Widgets CustomizationThe Welcome mat and drop-down selections are part of the extension templates. The default stylesheet provides the Magento Luma theme. If you want to change the default output provided by the extension, override the theme in Custom Theme. This is the basis of template customization in Magento.
l Shipping country, currency and language options displayed in frontend widget are based on Magento configuration. Shipping countries are based on all countries selected in the General → Allowed Countries.
l Mapping between country and currency is supported by extension and can be changed in eShopWorld: Checkout → Country - Currency Mapping configuration.
- 72 -
l Any further option overrides can be achieved by using interceptor or observer for eshop-world_js_configuration_build event .
14.6 Asynchronous Operations for Magento Commerce CloudThe following changes might required to allow asynchronous operations to work with Commerce Cloud:
1. Create a .magento.env.yaml file in root directory of the project and add the following snippet to the file:
stage:
deploy:
CRON_CONSUMERS_RUNNER:
cron_run: true
max_messages: 10000
consumers: []
2. Commit and deploy the changes.
For more information on asynchronous operations, see the Magento documentation.
14.6.1 Get eShopWorld calculated price
The following example shows how to get the calculated price for a product. In this example, the base price is 59 USD and the price is converted from USD to CAD:
<?php
namespace Vendor\Module\Example;
use EShopWorld\Checkout\Pricing\TaxManager;
class ExampleClass
{
/**
* @var TaxManager
*/
- 73 -
private $taxManager;
public function __construct(TaxManager $taxManager)
{
$this->taxManager = $taxManager;
}
public function getCalculatedPrice()
{
$basePrice = 59.00;
$currencyCodeFrom = 'USD';
$currencyCodeTo = 'CAD';
$countryCodeTo = 'CA';
return round($this->taxManager->applyRoundingModel($this->taxMan-ager->applyRetailerTaxes($this->taxManager->convertCurrency($basePrice, $currencyCodeFrom, $currencyCodeTo), null, $coun-tryCodeTo)), $this->taxManager->getCurrencyExponent());
}
}
- 74 -
15 TroubleshootingThis chapter provides procedures for troubleshooting the common problems encountered when installing the eShopWorld Magento extension.
15.1 Extension not appearing on the dashboardIf the eShopWorld Magento extension does not appear on the dashboard, edit the composer.json file and check the following path entries for the eShopWorld extension folder:
"repositories": {
"0": {
"type": "composer",
"url": "https://repo.magento.com/"
},
"eshopworld-checkout": {
"type": "artifact",
"url": "./packages/eshopworld"
}
In addition, check the following entry in require to ensure that the Magento edition and the eShopWorld extension version are up-to-date.
"require": {
"magento/product-community-edition": "{version}",
"composer/composer": "@alpha",
"eshopworld/module-checkout": "{version}"
}
- 75 -