- Introduction to the Amazon Marketplace Connector
- Amazon Marketplace Connector Tool Features
- White Paper - Amazon Marketplace Connector Tool v1.5
- System Requirements
- Architecture
- About the Amazon Marketplace Connector Tool
- Global Configuration
- Connection Settings
- Step Configuration
- Working with Other Tools
- Supported Objects
- Tool Output
- Amazon Marketplace Accounts Security
Introduction to the Amazon Marketplace Connector
What is the Amazon Marketplace Connector Tool?
The Amazon Marketplace Connector tool provides a straightforward way of enabling connectivity between your sales outlet in the Amazon Marketplace and BPA Platform.
This enables data integration between Amazon Marketplace and other systems that you use to process orders that BPA Platform can connect to.
The Amazon Marketplace Connector tool takes away the need for script and provides an easy to use user interface for writing data to the Amazon Marketplace.
Another advantage of the Amazon Marketplace Connector enables you to write data through the Amazon MWS API. This means that the data is validated using the business rules defined by Amazon so the data cannot be accidentally corrupted through lack of knowledge of these rules.
The Amazon Marketplace Connector tool uses XML as its input and output data format. Interoperation with standard BPA Platform tools is achieved using the BPA Platform XML tools which allow conversion of standard BPA Platform recordsets to and from XML.
Amazon Marketplace Connector Tool Features
- Connects to the Amazon Marketplace Web Service to communicate with your Amazon store using XML
- Allows for synchronisation solutions between your Amazon store and a third-party system:
- Download and retrieve information on sales orders
- Download and retrieve information on products
- Upload inventory changes, i.e. stock levels and prices
- Upload order status changes
- Obtain reports on marketplace activity
- Drag & drop facility for mapping BPA Platform data to your Amazon store; only map what you require to be sent and retrieved by the operations
- Visual links to easily identify the mappings between the incoming data of the XML source and the outgoing data to be sent to the Amazon Marketplace
White Paper - Amazon Marketplace Connector Tool v1.5
The Amazon Marketplace Connector white paper describes how to use the tool.
System Requirements
The Amazon Marketplace Connector requires BPA Platform (formerly known as TaskCentre) 4.5 SR4I or above.
Architecture
The image below provides a high-level system architecture diagram of the Amazon Marketplace Connector tool within the context of BPA Platform, the Amazon Marketplace Web Services and other systems used for processing orders:
About the Amazon Marketplace Connector Tool
The Amazon Marketplace Connector Tool is used to operate with data from/to an Amazon Marketplace Store.
The tool transforms incoming XML data into an XML format for the specific Amazon Marketplace object and operation selected. This XML is then passed to the Amazon Web Service which does the actual communication with Amazon Marketplace via its API. The response is exposed as XML from the tool, which could include details of the object requested, errors from the provider, or the values of any automatically generated ID fields.
The tool does not accept a BPA Platform recordset directly as input but BPA Platform variables containing XML data from any source at Task runtime may be utilised. In addition, a BPA Platform recordset can be processed by the Convert Recordset to XML Tool first to transform it into XML if you have this tool available.
Global Configuration
The global configuration for this tool is used to create a connection to the Amazon Marketplace Web Service. This will enable communication with the Amazon Marketplace and allow you to read data from or write data to your marketplace store.
When the connection is selected at task level, within the Amazon Marketplace Connector tool, the available objects and fields are exposed allowing BPA Platform data to be mapped and operations to be executed.
The global configuration for the tool can be accessed via the toolbar: Manage > Tools > Data Connectors > Amazon Marketplace Connector. Or, via the BPA Platform system tree within the Data Connectors node:
The dialog box displays the Connections list of the global configuration where connections to the Amazon Marketplace Web Service are managed. If you have multiple marketplace stores, then one connection can be created for each store
Connection Settings
The connection settings are accessed when you create or modify an existing connection.
The Amazon Marketplace Connector tool requires certain web access credentials to enable communication with the web service. These details are provided to you by Amazon and will include credentials such as your Merchant Token and Account Identifiers.
The settings required by a connection include the following:
- Connection Name — A name for the connection, for example, Amazon Marketplace. If you have more than one merchant account, then this will need to differentiate between the different accounts.
- Merchant ID — Enter the Seller ID as assigned by Amazon for your account.
- Merchant Token — Enter the Merchant Token. A security token provided by Amazon for your account.
- AWS Access Key ID — Enter the security key provided by Amazon for your account.
- Secret Key — Enter the security key provided by Amazon for your account.
- Country — United States or United Kingdom (for Europe select United Kingdom).
For a detailed description of how to obtain the details needed to continue with this configuration, go to our knowledge base article, How to obtain the web access credentials for the Amazon Marketplace Connector tool.
Step Configuration
About the General Tab
At configuration time, when the tool is added to a task the step will allow the user to select the data source which it will use at runtime through the General tab of the Amazon Marketplace Connector dialog.
The Data source can be either a task step, or a custom data source, including the use of BPA Platform variables.
If a Task step is used, then the data source can be set to an available BPA Platform XML data source. Only those steps that are capable of natively exposing an XML document at runtime are listed (this may be another Amazon Marketplace Connector step or a tool such as Convert Recordset to XML).
It is also possible to define a Custom data source. This data source has two parts – a definition of the schema used by the incoming data, and the selection of a BPA Platform variable that will contain the XML data at runtime.
Custom Schema Configuration
The Custom Schema Configuration dialog is used to define the schema of the XML to be used as the input data source for the Amazon Marketplace Connector Step. An XML schema defines the structure of the XML, in terms of what tags are present, and the nesting of the tags. The format used by the Amazon Marketplace Connector Tool is the industry standard XSD format.
If an XSD schema file is available for the XML that is to be used as the input data, then this can be loaded in from a file on disk (via the Import XSD/XML File button, which displays a file selection dialog) or pasted directly into the text box shown. Any XML passed into the step at runtime must conform to this schema. Otherwise an error will be reported.
Using an XSD schema file is the recommended way of defining the XML schema. However, if an XSD schema is not available, then an example of the XML that will be used at runtime can be loaded in or pasted into the text box. If an XML document is used, then the schema can be determined by pressing the Parse button.
About the Connection Tab
Through the Connection tab of the Amazon Marketplace Connector dialog box, a connection is selected from the list of connections previously created.
As an alternative to selecting a connection that has been previously created, a BPA Platform variable may be utilised by dragging and dropping it from the Task Browser dialog box into the Connection field to create a dynamic connection. If the dynamic option is used, then at runtime the text in the variable should match the name of one of the connections set up in the Global Configuration and this connection is then used.
About the Mapping Tab
Once the input data and the Amazon Marketplace connection have been defined, the mapping of data from the source to an Amazon Marketplace object, along with the operation required, is performed through the Mapping tab of the Amazon Marketplace Connector dialog box.
The aim of this tab is to define the links between the incoming data and the outgoing data that is to be sent to the Amazon Web Service.
The Object drop-down holds a list of objects available for the selected Amazon Marketplace connection. Selecting an object and operation will change the tree display in the right-hand pane to reflect the fields and child objects available for that selected operation.
The Operation drop-down displays the operations that the selected object supports.
Links are created by dragging and dropping fields from the data source left-hand XML tree control to the tool input right-hand XML tree control.
BPA Platform variables and formulas can be included in the source data, by simply dragging them from the task browser into a branch node in the input XML tree control on the left. Once in place, these can then be linked to the output XML tree control in the same way as normal fields.
Additionally, a field is present in each objects’ operation named SupplementaryReference. It allows for traceability throughout the process of transferring data from one place to another. When mapped, the data will reside locally at run time. It is added to the output and creates a record for your reference purposes only, this means you can choose to map any kind of information to this field to assist with, for example, advising where the data originated from or at what time data transfer occurred.
Advanced Translations (XSLT)
Creating the links in the user interface defines how, at runtime, the incoming XML is to be translated into the XML required for the given object and operation.
The method used to translate the XML is XSLT (eXtensible Stylesheet Language Transformations), which is an industry standard mechanism for performing XML translations. There is an Advanced Translation (XSLT) tab on the control, which will show the XSLT currently being generated for the given set of links created.
In the case of the user interface not being able to handle a particularly quirky requirement for transforming data, it is possible for the user to go into Enable Free Type Mode by checking this option, where XSLT can be input directly to achieve a transformation from the source XML format into the XML format required for the desired object and operation. XSLT knowledge will be needed to do this.
About the Options Tab
The Options tab allows you to set how errors in the step are handled at task runtime:
For example, if an error occurs you can decide if you want the task to continue with processing the next step along or abort and terminate the task completely.
Download Whitepaper
Working with Other Tools
Consuming from Other Tools
Below is a list of other steps that an Amazon Marketplace Connector step can directly interact with to consume information from. This list is by no means exhaustive but instead includes the most common steps the tool can interact with:
| Icon | Tool Name | Tool Category |
|---|---|---|
 | Import Flat File | Input |
 | Import XML Document | Input |
 | Convert Recordset to XML | Format |
 | Transform Data | Format |
 | Call Task | Execute |
 | Web Service Connector | Data Connectors |
 | Amazon Marketplace Connector | Data Connectors |
Exposing to Other Steps
An Amazon Marketplace Connector step can also directly expose its output for use by the following steps listed below:
| Icon | Tool Name | Tool Category |
|---|---|---|
 | Convert XML to Recordset | Format |
 | Run Microsoft Reporting Services | Format |
| Transform Data | Format |
 | Save File | Output |
| Call Task | Execute |
| Web Service Connector | Data Connectors |
| Amazon Marketplace Connector | Data Connectors |
Supported Objects
The objects and operations currently supported are displayed in the tables below. Bold fields are the primary keys.
Object: Order
| Operation | Description | Fields |
|---|---|---|
GetList | Retrieves a list of the seller’s orders defined by a combination of criteria. | SupplementaryReference CreatedAfter CreatedBefore LastUpdatedAfter LastUpdatedBefore MarketplaceId OrderStatus FullfillmentChannel BuyerEmail SellerOrderId |
GetOrder | Retrieves shipping/payment details for a specific order. | SupplementaryReference AmazonOrderId |
GetOrderItems | Retrieves details on specific items in an order. | SupplementaryReference AmazonOrderId |
Update | Updates shipping information for an order or items in an order. | SupplementaryReference MarketplaceId +Message
|
Acknowledgement | Allows the seller to acknowledge the successful or failed download of an order from Amazon. | SupplementaryReference +Message
+Items
|
| Adjustment | Allows the seller to issue a refund (adjustment) for an order. | SupplementaryReference +Message
+AdjustedItem
+ItemPriceAdjustments
|
Object: Product
| Operation | Description | Fields |
|---|---|---|
Add | Add an existing ASIN or ISBN product to the sellers’ inventory. You can then use the existing price and stock update operations to set those values for it which will make the product ‘live’ for them. | SupplementaryReference MarketplaceId +Message
|
Read | Retrieves information about products or an individual product. held by the seller on Amazon Marketplace. | SupplementaryReference MarketplaceId IdType Id |
UpdatePrice | Updates price fields for a specific product. | SupplementaryReference MarketplaceId +Message
|
Object: ProductStock
| Operation | Description | Fields |
|---|---|---|
Update | Updates stock fields for a specific product. | SupplementaryReference MarketplaceId +Message
|
Object: Report
| Operation | Description | Fields |
|---|---|---|
RequestReport | Starts the process of requesting a report from Amazon. | SupplementaryReference ReportType StartDate EndDate ReportOptions MarketplaceId |
RequestReport | Starts the process of requesting a report from Amazon. | |
GetReportRequestList | Checks with Amazon for when a report request has been completed. Supplies you with a GenerateReportID value when available. | SupplementaryReference ReportRequestIdList ReportTypeList ReportProcessingStatusList MaxCount RequestedFromDate RequestedToDate |
GetReport | Uses the GenerateReportID value to obtain the report from Amazon. | SupplementaryReference ReportId |
Object: SubmissionResponse
| Operation | Description | Fields |
|---|---|---|
GetFeedSubmissionResult | Returns status data from Amazon relating to the progress of submitted update requests. | SupplementaryReference FeedSubmissionId |
Fulfilled by Amazon
Certain operations allow a filter to be enabled which can separate the returned results based on whether they were fulfilled by Amazon or the seller.
Where the parameter FulfillmentChannel is present a filter can be set as follows:
- Setting the parameter to AFN will return results fulfilled by Amazon.
- Setting the parameter to MFN will return results fulfilled by the seller.
- Leaving the parameter blank will enable the default setting and will return results for both types.
The table below displays which operations include the parameter FulfillmentChannel to enable this filter:
| Operation | Description | Fields |
|---|---|---|
GetList | Retrieves a list of the seller’s orders defined by a combination of criteria. | SupplementaryReference CreatedAfter CreatedBefore LastUpdatedAfter LastUpdatedBefore MarketplaceId OrderStatus FullfillmentChannel BuyerEmail SellerOrderId |
Tool Output
The Amazon Marketplace Connector tool can output either a “success” or “error” XML document depending on whether the execution of the step at run time is successful or not.
Each XML document output by the Tool can then be used within other BPA Platform Tools, either as is or through conversion to a BPA Platform recordset using the Convert XML to Recordset tool.
Success XML Document
This document will contain the following:
- The input data mapped for the object
- Data returned from Amazon Marketplace, in the case of a Query operation:
- The SupplementaryReference value will appear here within the response content of the call
The key fields for the entity instances affected by the method. For example, in the case of a “Create”, the key fields for the top-level object instances created would be returned.
Error XML Document
An error XML output is always produced if an error is returned by the API. Any errors that occur are created as an
<ERROR> node. If no errors are present, the node will simply be empty.
The sub-nodes would be as follows:
<Object> — The name of the requested object (for example, PurchaseOrder.OrderHeader_main)
<CODE> — The error code returned by Amazon MWS
<MESSAGE> — The error message
<EXTENDEDINFO> — A string that contains additional information about the error that occurred.
<INPUTDATA> — The input data mapped for the object. The SupplementaryReference value will also appear under this node
Data Processing
When a task containing an Amazon Marketplace Connector Step runs, the Connector Step itself performs all the processing of data from other steps in the task and assembles an XML document containing all the information that the Web Service needs to perform the operation on the object that the step is configured for.
This information includes the data itself to be passed from other steps, connection details for the Amazon Marketplace API, and the operation to be performed on the Amazon web service. The XML is then transmitted to the Web Service via a secure HTTPS connection.
The Web Service then parses the XML and performs the required operation by generating a function call to the Amazon Marketplace API.
An XML document is then created which contains the response from the Amazon Marketplace API. This may be information about the requested object data if for instance the operation was a Get or Read operation, or it could be a confirmation if an Update operation was attempted.
This XML is then returned to the Amazon Marketplace Connector tool for use in subsequent steps. In the case of updates, they are not performed immediately by Amazon, so it is necessary to query the SubmissionResponse object to check that the update is successful. Reports use a similar mechanism by utilising the GetReportRequestList operation to check when a report has been made available by Amazon.
Download Whitepaper
Runtime
The incoming XML is translated into the XML format for the object and operation selected in the configuration. The data for the linked fields is brought across into the output XML — only those fields that were linked are brought across. The XML is passed to the connector tool, which then:
- Processes the data
- Performs the operation requested
- Sends back an XML document containing the response The XML can then be used by other BPA Platform steps.
Error Handling
Errors are written to the BPA Platform Event Log (Manage > Event Log). You define how errors are handled in the Options tab of the Amazon Marketplace Connector tool. Reasons for the errors could include:
- Web service connection errors
- User privilege errors
- Errors from the Amazon Marketplace API
- Warnings and messages from the Amazon Marketplace API
Errors that Occur Outside of the Amazon Marketplace Web Service
These types of errors could include:
- XML transformation errors
- Web Service connection errors
- Login errors
These types of errors may result in the step failing. Whether or not the step and task fails depends on the standard Step Options Tab set. The error is recorded in the BPA Platform log for the task and displayed in the BPA Platform client at the time of failure.
Errors Returned by the Amazon Marketplace Web Service
These types of errors could include:
- Invalid data (according to Amazon) passed into the tool for the given fields
- Amazon business logic errors
RunCountproperty — At runtime, this contains the total number of top level object, for example orders, in the input XML that were processed by the tool.- FailCount property — At runtime, this contains the number of error objects returned in the output XML.
- SuccessCount property — At runtime, this contains the number of non-error objects returned in the output XML.
These types of errors may not result in the step failing. A business logic failure may result in a warning rather than an error. Mapping, for example, the CreatedAfter and LastUpdatedAfter fields in an Order GetList operation gives a warning in the BPA Platform Event Log. The step, however doesn’t fail.
Dealing with errors
There are three properties set on the step after processing:
Amazon Marketplace Accounts Security
The Amazon Marketplace API is the only method used to connect to a Amazon Marketplace database, and perform read / write tasks — all security present in the API is used.
