Difference between revisions of "Amazon Integration"

From Opentaps Wiki
Jump to navigationJump to search
m
(→‎Importing Amazon Orders)
 
(17 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
== Introduction ==
 +
 +
The opentaps Amazon component is designed to help you sell your
 +
products as an Amazon merchant.  It will upload your product catalog,
 +
including product description, images, and prices to Amazon; download
 +
customers and orders from Amazon; and confirm the shipment of orders
 +
with Amazon so that Amazon can process payments for you.  To see how this works, see [[Amazon Tests]].
 +
 
== Setting Up Amazon Integration==
 
== Setting Up Amazon Integration==
  
Line 5: Line 13:
 
* Load the seed data in hot-deploy/amazon/data/AmazonSeedData.xml
 
* Load the seed data in hot-deploy/amazon/data/AmazonSeedData.xml
 
* Load the demo data in hot-deploy/amazon/data/AmazonDemoData.xml or use it as a guide to configure your own data
 
* Load the demo data in hot-deploy/amazon/data/AmazonDemoData.xml or use it as a guide to configure your own data
−
* Configure the following properties in hot-deploy/amazon/config/amazon.properties (see below for descriptions of the properties):
+
* Configure the following properties in hot-deploy/amazon/config/amazon.properties (see below for descriptions of the properties).  E-mail addresses are optional, but they are used for notifying you in case there are problems with your integration, so it is important to set them:
 
** opentaps.amazon.merchantIdentifier
 
** opentaps.amazon.merchantIdentifier
 
** opentaps.amazon.merchantName
 
** opentaps.amazon.merchantName
 
** opentaps.amazon.userName
 
** opentaps.amazon.userName
 
** opentaps.amazon.password
 
** opentaps.amazon.password
−
** opentaps.amazon.error.email.fromAddress (optional)
+
** opentaps.amazon.error.email.fromAddress  
−
** opentaps.amazon.error.email.toAddress (optional)
+
** opentaps.amazon.error.email.toAddress  
−
* If you plan to use Opentaps to schedule shipments with carriers, comment out the ShipmentRouteSegment eECA in hot-deploy/amazon/entitydef/eecas_amazon_orders.xml and uncomment the completePack sECA in hot-deploy/amazon/servicedef/secas_amazon_orders.xml. This will ensure that the tracking numbers returned by the carrier are correctly posted to Amazon.
+
* If you plan to use Opentaps to schedule shipments with carriers, comment out the ShipmentRouteSegment eECA in <tt>hot-deploy/amazon/entitydef/eecas_amazon_orders.xml</tt> and uncomment the completePack sECA in <tt>hot-deploy/amazon/servicedef/secas_amazon_orders.xml</tt>. This will ensure that the tracking numbers returned by the carrier are correctly posted to Amazon.
  
 
== Basic Workflow ==
 
== Basic Workflow ==
  
−
* Product Importing
+
=== Publishing Products to Amazon ===
−
** The Amazon integration component disallows the changing of the ASIN and SKU GoodIdentification numbers in the catalog manager.
+
 
−
* Customer Matching
+
The <tt>AmazonProduct</tt> entity controls which products are published to Amazon and supplies additional attributes such as tax code, fulfillment terms, and search terms for Amazon.  If the Amazon component is enabled, an AmazonProduct is automatically created whenever you create or update your product, so that the product is scheduled for addition or updating on Amazon.  To publish the product successfully, though, your product must have a unique UPCA, which you can create in the catalog manager, and you need to go to the Amazon Integration application's Products tab and edit the Amazon Product record to set up its tax code.  The tax code is required for uploading products to Amazon.  (For testing try a tax code of "ABCD".)
−
** Amazon uses email address as the unique identifier of a customer.
+
 
−
** Amazon sends phone numbers which are parsed with regex into separate area code and phone numbers
+
The Amazon integration component disallows the changing of the ASIN and SKU GoodIdentification numbers in the catalog manager.
−
** Amazon sends state and country codes which are matched against the Geo and GeoAssoc entities in opentaps.
+
 
−
* Order Importing
+
If you wish to remove a product from the Amazon upload, set a flag on the AmazonProduct entity.
−
** Pending order documents are downloaded from Amazon and stored periodically (opentaps.amazon.storePendingOrderDocuments service)
+
 
−
** Acknowledgement is posted to Amazon of downloaded order documents (opentaps.amazon.acknowledgeOrderDocumentDownload service)
+
The opentaps.amazon.publishProductsToAmazon service will periodically search your products for changes and write an XML file in <tt>runtime/output/</tt> directory in the format: Amazon***Feed_yy-mm-dd_hhmmss.xml.  It will then use the soap interface to contact Amazon to upload the XML file and store the processing document ID returned by Amazon in the AmazonProduct entity.  If there were any issues with the upload, opentaps will sends you an e-mail.
−
** Amazon orders are extracted from stored order documents (opentaps.amazon.extractOrdersForImport service)
+
 
−
** Extracted orders are imported into the Opentaps data model (opentaps.amazon.importOrders service)
+
After the main product information from AmazonProduct has been uploaded, running the opentaps.amazon.checkAcknowledgementStatuses service will check if the Amazon document for the product has been acknowledged by Amazon.  Once the product has been acknowledged, then you can publish its inventory, price, and image information to Amazon.
−
** Acknowledgement is posted to Amazon of imported orders (opentaps.amazon.acknowledgeImportedOrders service)
+
 
−
** Acknowledgement is posted to Amazon of fulfilled (shipped) order items. This is accomplished by two independent services: opentaps.amazon.queueShippedItemsForFulfillmentPost, which is responsible for detecting shipment of order items related to Amazon orders (currently via an entity-ECA triggered by the update of a ShipmentRouteSegment.carrierServiceStatusId to SHRSCS_ACCEPTED) and queueing them for fulfillment acknowledgement; and opentaps.amazon.acknowledgeFulfilledOrderItems which posts the fulfillment acknowledgement to Amazon of any order items in the acknowledgement queue.
+
If later you update inventory or pricing for a product, opentaps will change the settings for the AmazonProductInventory or AmazonProductPrice entities so that the product's inventory and price information will be scheduled for upload to Amazon again.
−
** Posted acknowledgement documents are periodically checked for availability of their related processing report from Amazon. If the processing report becomes available it will be retrieved and the statuses of the related objects updated according to the information in the report.
+
 
−
** There are no execution dependencies - these steps will all run independently from one another by scheduled jobs and will operate on whatever data is available in the right condition at each runtime.
+
When uploading product prices to Amazon, opentaps will upload the list price of the product as the Amazon standard price and the default price of the product as the Amazon selling price.  If there is no thru date for the default price in opentaps, opentaps will automatically set it on Amazon to expire 20 years in the future.
 +
 
 +
=== Importing Amazon Orders ===
 +
 
 +
To be able to import orders from Amazon, you must first have Amazon Merchant Services configure your account to generate order reports in XML instead of flat file format.
 +
 
 +
Once this has been done, pending order documents can be downloaded from Amazon and stored periodically into the AmazonOrderDocument entity.  The entire XML document of all the orders retrieved from each request to Amazon is stored in this entity.  An acknowledgment is then posted back to Amazon.
 +
 
 +
Then, another service periodically extracts the XML document from AmazonOrderDocument into staging tables such as AmazonOrder, AmazonOrderItem, AmazonOrderItemPriceComp, etc.
 +
 
 +
Next, the import orders service imports the orders from Amazon to opentaps.  Orders which cannot be imported will be flagged as problem orders with their error messages.  And acknowledgment is sent back to Amazon of the orders that have been imported.
 +
 
 +
When you pack your orders, records are created in the AmazonOrderItemFulfillment table.  Another periodically schedule service will post the acknowledgement of the packed orders back to Amazon.
 +
 
 +
There are no execution dependencies - these steps will all run independently from one another by scheduled jobs and will operate on whatever data is available in the right condition at each runtime.
 +
 
 +
=== Customer Matching ===
 +
Amazon uses email address as the unique identifier of a customer.  An AmazonParty entity is used to track the matching Party in opentaps for the Amazon customer.  If none is found, a new one will be created when the order is important.
 +
 
 +
Amazon sends phone numbers which are parsed with regex into separate area code and phone numbers.
 +
 
 +
Amazon sends state and country codes which are matched against the Geo and GeoAssoc entities in opentaps.
 +
 
 +
=== Payments ===
 +
By configuring your Amazon integration store to use [[Third Party Billing]], opentaps will automatically mark your customers invoices as paid and create a running invoice to Amazon for their invoices.
 +
 
 +
== Tax Amounts Import ==
 +
 
 +
During order import, the system will attempt to resolve any tax amounts deducted by Amazon to a corresponding tax authority. The system's behaviour when it fails to resolve a tax authority is governed by the opentaps.amazon.import.requireTaxAuthority property. If that property is set to 'true', the order will fail to import. If 'false', the order will be imported without TaxAuthority-related data.
 +
 
 +
The resolution of Amazon tax amount is accomplished via the AmazonOrderTaxJurisToAuth entity. Amazon.com supplies highly normalized tax amount data, broken down by geographical tax jurisdiction. The tax jurisdiction is structured as a nested district/city/county/state relationship, and so the AmazonOrderTaxJurisToAuth entity relies on a mapping of distinct combinations of district/city/county/state to taxAuthorityGeoId/taxAuthorityPartyId.
 +
 
 +
The system will try to resolve to a TaxAuthority in a series of increasingly generic steps.The system will first attempt a precise match of all four Amazon-supplied values to a TaxAuthority. Failing that, the system will then attempt a match using the value "_NA_" in place of the Amazon-supplied district value. Failing that, it will use "_NA_" for both district and city, and so on up the chain.  
 +
 
 +
This allows for a certain amount of flexibility in TaxAuthority mappings. For example, to use one simple TaxAuthority for all tax amounts, the AmazonOrderTaxJurisToAuth record would be in this form:
 +
 
 +
<pre>
 +
<AmazonOrderTaxJurisToAuth taxJurisDistrict="_NA_" taxJurisCity="_NA_" taxJurisCounty="_NA_" taxJurisState="_NA_"
 +
taxAuthPartyId="YOURTAXAUTHPARTYID" taxAuthGeoId="YOURTAXAUTHGEOID" />
 +
</pre>
 +
 
 +
To track tax amounts separately for the state of Washington and the state of New York, the records would be in this form:
 +
 
 +
<pre>
 +
<AmazonOrderTaxJurisToAuth taxJurisDistrict="_NA_" taxJurisCity="_NA_" taxJurisCounty="_NA_" taxJurisState="WA"
 +
taxAuthPartyId="WA_TAXMAN" taxAuthGeoId="WA" />
 +
<AmazonOrderTaxJurisToAuth taxJurisDistrict="_NA_" taxJurisCity="_NA_" taxJurisCounty="_NA_" taxJurisState="NY"
 +
taxAuthPartyId="NY_DTF" taxAuthGeoId="NY" />
 +
</pre>
 +
 
 +
To track tax amounts deducted for a particular city separately from tax amounts deducted for the remainder of the state, the records would be in this form:
 +
 
 +
<pre>
 +
<AmazonOrderTaxJurisToAuth taxJurisDistrict="_NA_" taxJurisCity="AMAZONCITYVALUE" taxJurisCounty="AMAZONCOUNTYVALUE" taxJurisState="AMAZONSTATEVALUE"
 +
taxAuthPartyId="CITYTAXAUTHPARTYID" taxAuthGeoId="CITYTAXAUTHGEOID" />
 +
<AmazonOrderTaxJurisToAuth taxJurisDistrict="_NA_" taxJurisCity="_NA_" taxJurisCounty="_NA_"
 +
taxJurisState="AMAZONSTATEVALUE"
 +
taxAuthPartyId="STATETAXAUTHPARTYID" taxAuthGeoId="STATETAXAUTHGEOID" />
 +
</pre>
  
−
== Services ==
+
== Order Integration Services ==
  
 
{|border=1
 
{|border=1
Line 108: Line 174:
 
{|border=1
 
{|border=1
 
|-bgcolor=grey
 
|-bgcolor=grey
−
!Entity!!Holds
+
!Entity!!Description
 +
|-
 +
|AmazonBatchUpdateHistory||
 +
|-
 +
|AmazonNodeMappingType||
 +
|-
 +
|AmazonNodeValidAttribute||
 
|-
 
|-
 
|AmazonOrder||
 
|AmazonOrder||
Line 133: Line 205:
 
|-
 
|-
 
|AmazonOrderItemTaxRate||
 
|AmazonOrderItemTaxRate||
 +
|-
 +
|AmazonOrderTaxJurisToAuth||
 +
|-
 +
|AmazonOtherItemAttrValue||
 
|-
 
|-
 
|AmazonParty||
 
|AmazonParty||
 +
|-
 +
|AmazonProduct||
 +
|-
 +
|AmazonProductBrowseNode||
 +
|-
 +
|AmazonProductBulletPoint||
 +
|-
 +
|AmazonProductFeedProcessing||
 +
|-
 +
|AmazonProductImage||
 +
|-
 +
|AmazonProductImageAck||
 +
|-
 +
|AmazonProductImageAndAck||
 +
|-
 +
|AmazonProductInventory||
 +
|-
 +
|AmazonProductItemType||
 +
|-
 +
|AmazonProductOtherItemAttr||
 +
|-
 +
|AmazonProductPrice||
 +
|-
 +
|AmazonProductSearchTerms||
 +
|-
 +
|AmazonProductTargetAudience||
 +
|-
 +
|AmazonProductUsedFor||
 +
|-
 +
|AmazonTargetAudienceValue||
 +
|-
 +
|AmazonUsedForValue||
 +
|-
 +
|ViewAmazonProducts||
 +
|}
 +
 +
== Scheduled Jobs ==
 +
 +
Various services are required to run at intervals in order to retrieve Amazon orders and post product data to Amazon. Below is a table of the required services and suggested recurrence intervals:
 +
 +
{|border=1px solid
 +
|-bgcolor=#666
 +
!Service!!Frequency/Run Time
 +
|-
 +
|opentaps.amazon.storePendingOrderDocuments||Every 15 minutes
 +
|-
 +
|opentaps.amazon.acknowledgeOrderDocumentDownload||Every 15 minutes
 +
|-
 +
|opentaps.amazon.extractOrdersForImport||Every 15 minutes
 +
|-
 +
|opentaps.amazon.importOrders||Every 15 minutes
 +
|-
 +
|opentaps.amazon.acknowledgeImportedOrders||Every 15 minutes
 +
|-
 +
|opentaps.amazon.acknowledgeFulfilledOrderItems||Hourly
 +
|-
 +
|opentaps.amazon.checkAcknowledgementStatuses||Hourly
 +
|-
 +
|opentaps.amazon.publishProductsToAmazon||Daily at 00:30
 +
|-
 +
|opentaps.amazon.batchUpdateAmazonProducts||Daily at 00:00
 +
|-
 +
|opentaps.amazon.publishProductPriceToAmazon||Daily at 02:30
 +
|-
 +
|opentaps.amazon.publishProductImagesToAmazon||Daily at 03:00
 +
|-
 +
|opentaps.amazon.publishProductInventoryToAmazon||Daily at 04:00
 +
|-
 +
|opentaps.amazon.deleteProductsFromAmazon||Daily at 04:30
 +
|-
 +
|opentaps.amazon.checkLastFeedProcessingDocumentDownloadSuccess||Daily at 06:00
 
|}
 
|}
  
Line 166: Line 313:
 
|-
 
|-
 
|export.product.useProductIdAsSKU||If false, a GoodIdentification of goodIdentificationTypeId SKU will be required in order to post a product to Amazon||true
 
|export.product.useProductIdAsSKU||If false, a GoodIdentification of goodIdentificationTypeId SKU will be required in order to post a product to Amazon||true
 +
|-
 +
|export.product.useUPCAsSKU||Set to 'true' to use the product's UPC as its Amazon SKU. Set to false to use either productId or a GoodIdentification of type 'SKU', depending on the value of the opentaps.amazon.export.product.useProductIdAsSKU property||false
 
|-bgcolor=#CCC
 
|-bgcolor=#CCC
 
|colspan=3|
 
|colspan=3|
Line 173: Line 322:
 
|-
 
|-
 
|error.email.errorEmailScreenUri.orders||Screen location for order error email template||component://amazon/widget/orders/AmazonOrderScreens.xml#errorEmail
 
|error.email.errorEmailScreenUri.orders||Screen location for order error email template||component://amazon/widget/orders/AmazonOrderScreens.xml#errorEmail
 +
|-
 +
|error.email.errorEmailScreenUri.orders.orderAckValidate||Screen location for template for order acknowledgement errors returned by Amazon||component://amazon/widget/orders/AmazonOrderScreens.xml#orderAckValidateErrorEmail
 +
|-
 +
|error.email.errorEmailScreenUri.orders.orderItemFulfillValidate||Screen location for template for order item fulfillment acknowledgement errors returned by Amazon||component://amazon/widget/orders/AmazonOrderScreens.xml#orderItemFulfillValidateErrorEmail
 +
|-
 +
|error.email.errorEmailScreenUri.products||Screen location for the template for template for the generic product-related error email||component://amazon/widget/products/AmazonProductScreens.xml#errorEmail
 
|-
 
|-
 
|error.email.errorEmailScreenUri.productFeedProcessingAgeWarning||Screen location for the template for the email warning of the age of the last successful product feed processing document download||component://amazon/widget/products/AmazonProductScreens.xml#productFeedProcessingAgeWarning
 
|error.email.errorEmailScreenUri.productFeedProcessingAgeWarning||Screen location for the template for the email warning of the age of the last successful product feed processing document download||component://amazon/widget/products/AmazonProductScreens.xml#productFeedProcessingAgeWarning
Line 183: Line 338:
 
|-
 
|-
 
|error.email.toAddress||'To' email address for all error emails||
 
|error.email.toAddress||'To' email address for all error emails||
 +
|-
 +
|error.email.linesForBulkErrorEmails||Number of errors to include in each email when bulk error messages are sent||1000
 
|-bgcolor=#CCC
 
|-bgcolor=#CCC
 
|colspan=3|
 
|colspan=3|
 
''Miscellaneous properties''
 
''Miscellaneous properties''
 +
|-
 +
|createdByAmazonApplication||Generic string for description fields of automatically-created records||Created by application
 +
|-bgcolor=#CCC
 +
|colspan=3|
 +
''Product export properties''
 +
|-
 +
|default.product.descriptionField||Name of a field in the Product entity from which to extract product descriptions. Must be one of description or longDescription||longDescription
 
|-
 
|-
 
|default.uom.length||Amazon length unit of measure to use in cases where a unit of measure is missing for a product dimension||IN
 
|default.uom.length||Amazon length unit of measure to use in cases where a unit of measure is missing for a product dimension||IN
 
|-
 
|-
 
|default.uom.weight||Amazon weight unit of measure to use in cases where a unit of measure is missing for a product weight||LB
 
|default.uom.weight||Amazon weight unit of measure to use in cases where a unit of measure is missing for a product weight||LB
−
|-
 
−
|createdByAmazonApplication||Generic string for description fields of automatically-created records||Created by application
 
 
|-
 
|-
 
|export.product.conditionType||Condition for exported products - must be one of:
 
|export.product.conditionType||Condition for exported products - must be one of:
Line 209: Line 371:
 
|colspan=3|
 
|colspan=3|
 
''Product image export''
 
''Product image export''
 +
|-
 +
|image.urlRoot||URL root with which to prefix values in the SMALL_IMAGE_URL, LARGE_IMAGE_URL, etc. fields||
 
|-
 
|-
 
|default.image.main||Mapping of Opentaps Product field/productContentTypeId to Amazon Main product image||LARGE_IMAGE_URL
 
|default.image.main||Mapping of Opentaps Product field/productContentTypeId to Amazon Main product image||LARGE_IMAGE_URL
Line 231: Line 395:
 
|-
 
|-
 
|default.image.swatch||Mapping of Opentaps Product field/productContentTypeId to Amazon Swatch product image||
 
|default.image.swatch||Mapping of Opentaps Product field/productContentTypeId to Amazon Swatch product image||
 +
|-bgcolor=#CCC
 +
|colspan=3|
 +
''Product price export''
 +
|-
 +
|export.product.price.delistProductIfNoSalePrice||Post a product's price as zero, thereby disabling the 'buy' button, if no current DEFAULT_PRICE exists for the product||false
 
|-bgcolor=#CCC
 
|-bgcolor=#CCC
 
|colspan=3|
 
|colspan=3|
Line 253: Line 422:
 
|-
 
|-
 
|import.maxDaysToShip.Standard||Number of days to add to the current date in order to calculate a Ship-By Date for orders with Standard service level||7
 
|import.maxDaysToShip.Standard||Number of days to add to the current date in order to calculate a Ship-By Date for orders with Standard service level||7
−
|-
 
−
|import.requireInventory||Setting for the Require Inventory flag of order item inventory reservations during order import||true
 
 
|-
 
|-
 
|import.requireTaxAuthority||Require an Amazon taxLocationCode to Opentaps taxAuthorityGeoId/taxAuthorityPartyId mapping in the AmazonTaxLocToTaxAuth entity to successfully import orders with tax amounts||true
 
|import.requireTaxAuthority||Require an Amazon taxLocationCode to Opentaps taxAuthorityGeoId/taxAuthorityPartyId mapping in the AmazonTaxLocToTaxAuth entity to successfully import orders with tax amounts||true
Line 326: Line 493:
  
 
=UPC Codes=
 
=UPC Codes=
 +
 +
Amazon.com is divided into 'stores', each of which are responsible for certain types of products. Some stores (Health, Beauty) require a valid, unique UPC-A (12-digit) code to be supplied for each product. Depending on your requirements, the Amazon.com integration component can be configured to check UPC validity and supply a UPC to Amazon, and also can be configured to use the product's UPC as the SKU for Amazon. The relevant properties are these:
 +
 +
* opentaps.amazon.export.product.requireUpcCodes - set to 'true' to require a valid SKU before posting a product to Amazon. Must be set to 'true' if the opentaps.amazon.export.product.useUPCAsSKU property (below) is true
 +
* opentaps.amazon.export.product.useUPCAsSKU - set to 'true' to use the product's UPC as its Amazon SKU. Set to false to use either productId or a GoodIdentification of type 'SKU', depending on the value of the opentaps.amazon.export.product.useProductIdAsSKU property
 +
 +
Since Amazon only recognizes the 12-digit form of UPC (UPC-A), any 8-digit (compressed) UPC-E codes will be expanded to UPC-A codes before being posted to Amazon. If both a UPC-A code and a UPC-E code exist for a product, the UPC-A code will be used and the UPC-E code will be ignored. In the case of multiple UPC-A or multiple UPC-E codes existing for a given product, the most recently modified code will be used.
  
 
=Import of existing Amazon Products=
 
=Import of existing Amazon Products=

Latest revision as of 00:22, 17 February 2010

Introduction

The opentaps Amazon component is designed to help you sell your products as an Amazon merchant. It will upload your product catalog, including product description, images, and prices to Amazon; download customers and orders from Amazon; and confirm the shipment of orders with Amazon so that Amazon can process payments for you. To see how this works, see Amazon Tests.

Setting Up Amazon Integration

To enable integration with Amazon.com:

  • Uncomment the line for the Amazon.com component in hot-deploy/component-load.xml
  • Load the seed data in hot-deploy/amazon/data/AmazonSeedData.xml
  • Load the demo data in hot-deploy/amazon/data/AmazonDemoData.xml or use it as a guide to configure your own data
  • Configure the following properties in hot-deploy/amazon/config/amazon.properties (see below for descriptions of the properties). E-mail addresses are optional, but they are used for notifying you in case there are problems with your integration, so it is important to set them:
    • opentaps.amazon.merchantIdentifier
    • opentaps.amazon.merchantName
    • opentaps.amazon.userName
    • opentaps.amazon.password
    • opentaps.amazon.error.email.fromAddress
    • opentaps.amazon.error.email.toAddress
  • If you plan to use Opentaps to schedule shipments with carriers, comment out the ShipmentRouteSegment eECA in hot-deploy/amazon/entitydef/eecas_amazon_orders.xml and uncomment the completePack sECA in hot-deploy/amazon/servicedef/secas_amazon_orders.xml. This will ensure that the tracking numbers returned by the carrier are correctly posted to Amazon.

Basic Workflow

Publishing Products to Amazon

The AmazonProduct entity controls which products are published to Amazon and supplies additional attributes such as tax code, fulfillment terms, and search terms for Amazon. If the Amazon component is enabled, an AmazonProduct is automatically created whenever you create or update your product, so that the product is scheduled for addition or updating on Amazon. To publish the product successfully, though, your product must have a unique UPCA, which you can create in the catalog manager, and you need to go to the Amazon Integration application's Products tab and edit the Amazon Product record to set up its tax code. The tax code is required for uploading products to Amazon. (For testing try a tax code of "ABCD".)

The Amazon integration component disallows the changing of the ASIN and SKU GoodIdentification numbers in the catalog manager.

If you wish to remove a product from the Amazon upload, set a flag on the AmazonProduct entity.

The opentaps.amazon.publishProductsToAmazon service will periodically search your products for changes and write an XML file in runtime/output/ directory in the format: Amazon***Feed_yy-mm-dd_hhmmss.xml. It will then use the soap interface to contact Amazon to upload the XML file and store the processing document ID returned by Amazon in the AmazonProduct entity. If there were any issues with the upload, opentaps will sends you an e-mail.

After the main product information from AmazonProduct has been uploaded, running the opentaps.amazon.checkAcknowledgementStatuses service will check if the Amazon document for the product has been acknowledged by Amazon. Once the product has been acknowledged, then you can publish its inventory, price, and image information to Amazon.

If later you update inventory or pricing for a product, opentaps will change the settings for the AmazonProductInventory or AmazonProductPrice entities so that the product's inventory and price information will be scheduled for upload to Amazon again.

When uploading product prices to Amazon, opentaps will upload the list price of the product as the Amazon standard price and the default price of the product as the Amazon selling price. If there is no thru date for the default price in opentaps, opentaps will automatically set it on Amazon to expire 20 years in the future.

Importing Amazon Orders

To be able to import orders from Amazon, you must first have Amazon Merchant Services configure your account to generate order reports in XML instead of flat file format.

Once this has been done, pending order documents can be downloaded from Amazon and stored periodically into the AmazonOrderDocument entity. The entire XML document of all the orders retrieved from each request to Amazon is stored in this entity. An acknowledgment is then posted back to Amazon.

Then, another service periodically extracts the XML document from AmazonOrderDocument into staging tables such as AmazonOrder, AmazonOrderItem, AmazonOrderItemPriceComp, etc.

Next, the import orders service imports the orders from Amazon to opentaps. Orders which cannot be imported will be flagged as problem orders with their error messages. And acknowledgment is sent back to Amazon of the orders that have been imported.

When you pack your orders, records are created in the AmazonOrderItemFulfillment table. Another periodically schedule service will post the acknowledgement of the packed orders back to Amazon.

There are no execution dependencies - these steps will all run independently from one another by scheduled jobs and will operate on whatever data is available in the right condition at each runtime.

Customer Matching

Amazon uses email address as the unique identifier of a customer. An AmazonParty entity is used to track the matching Party in opentaps for the Amazon customer. If none is found, a new one will be created when the order is important.

Amazon sends phone numbers which are parsed with regex into separate area code and phone numbers.

Amazon sends state and country codes which are matched against the Geo and GeoAssoc entities in opentaps.

Payments

By configuring your Amazon integration store to use Third Party Billing, opentaps will automatically mark your customers invoices as paid and create a running invoice to Amazon for their invoices.

Tax Amounts Import

During order import, the system will attempt to resolve any tax amounts deducted by Amazon to a corresponding tax authority. The system's behaviour when it fails to resolve a tax authority is governed by the opentaps.amazon.import.requireTaxAuthority property. If that property is set to 'true', the order will fail to import. If 'false', the order will be imported without TaxAuthority-related data.

The resolution of Amazon tax amount is accomplished via the AmazonOrderTaxJurisToAuth entity. Amazon.com supplies highly normalized tax amount data, broken down by geographical tax jurisdiction. The tax jurisdiction is structured as a nested district/city/county/state relationship, and so the AmazonOrderTaxJurisToAuth entity relies on a mapping of distinct combinations of district/city/county/state to taxAuthorityGeoId/taxAuthorityPartyId.

The system will try to resolve to a TaxAuthority in a series of increasingly generic steps.The system will first attempt a precise match of all four Amazon-supplied values to a TaxAuthority. Failing that, the system will then attempt a match using the value "_NA_" in place of the Amazon-supplied district value. Failing that, it will use "_NA_" for both district and city, and so on up the chain.

This allows for a certain amount of flexibility in TaxAuthority mappings. For example, to use one simple TaxAuthority for all tax amounts, the AmazonOrderTaxJurisToAuth record would be in this form: 

<AmazonOrderTaxJurisToAuth taxJurisDistrict="_NA_" taxJurisCity="_NA_" taxJurisCounty="_NA_" taxJurisState="_NA_" 
taxAuthPartyId="YOURTAXAUTHPARTYID" taxAuthGeoId="YOURTAXAUTHGEOID" />

To track tax amounts separately for the state of Washington and the state of New York, the records would be in this form: 

<AmazonOrderTaxJurisToAuth taxJurisDistrict="_NA_" taxJurisCity="_NA_" taxJurisCounty="_NA_" taxJurisState="WA" 
taxAuthPartyId="WA_TAXMAN" taxAuthGeoId="WA" />
<AmazonOrderTaxJurisToAuth taxJurisDistrict="_NA_" taxJurisCity="_NA_" taxJurisCounty="_NA_" taxJurisState="NY" 
taxAuthPartyId="NY_DTF" taxAuthGeoId="NY" />

To track tax amounts deducted for a particular city separately from tax amounts deducted for the remainder of the state, the records would be in this form: 

<AmazonOrderTaxJurisToAuth taxJurisDistrict="_NA_" taxJurisCity="AMAZONCITYVALUE" taxJurisCounty="AMAZONCOUNTYVALUE" taxJurisState="AMAZONSTATEVALUE" 
taxAuthPartyId="CITYTAXAUTHPARTYID" taxAuthGeoId="CITYTAXAUTHGEOID" />
<AmazonOrderTaxJurisToAuth taxJurisDistrict="_NA_" taxJurisCity="_NA_" taxJurisCounty="_NA_" 
taxJurisState="AMAZONSTATEVALUE" 
taxAuthPartyId="STATETAXAUTHPARTYID" taxAuthGeoId="STATETAXAUTHGEOID" />

Order Integration Services

Service Area Action Notes
opentaps.amazon.

storePendingOrderDocuments

Orders Requests all pending order documents from Amazon and stores each document in the AmazonOrderDocument entity. The service will fail only if there is a database error or a communication error with Amazon. Each document is treated separately - if the download of one document fails, the AmazonOrderDocument record will reflect the error and reason, but other documents in the same batch won't be affected. If a document download fails, the service will keep trying to download it from Amazon at each run. Documents will also fail if they consist of invalid or unparseable XML.
  • An attempt to parse the XML of the downloaded document is made before storing a success result
opentaps.amazon.

acknowledgeOrderDocumentDownload

Orders Finds any AmazonOrderDocuments in the database which have been successfully downloaded, but for which download acknowledgement has not yet been posted back to Amazon, and posts that acknowledgement. The service will fail only in the case of a database error. If there is an error posting acknowledgement, each of the affected AmazonOrderDocuments will reflect the failure and the reason. The AmazonOrderDocument.ackStatusId field will be set to AMZN_DOC_ACKED or AMZN_DOC_ACK_ERR.
opentaps.amazon.

extractOrdersForImport

Orders Finds any AmazonOrderDocuments in the database which have been successfully downloaded *and* successfully acknowledged, and for which extraction has failed no more than the number of times defined in the opentaps.amazon.import.order.retry.threshold.extract property, and attempts to parse each document in order to extract information about Amazon orders. The service will fail only in the case of a database error. Order documents are dealt with in an atomic fashion - if a document is unparseable or there is a problem extracting or storing order information into the import tables for any order in an order document, the entire order document will be marked as a failure and no orders will be extracted from it. Records in these entities will be created for each Amazon order extracted successfully (see the Entities section below for a description of the contents of each entity):
  • AmazonOrder
  • AmazonOrderItem
  • AmazonOrderItemPriceComponent
  • AmazonOrderItemFee
  • AmazonOrderItemTaxJurisdtn
  • AmazonOrderItemTaxAmount
  • AmazonOrderItemTaxRate
  • AmazonOrderItemPromo
  • When dates for order date and order posted date are extracted from the XML as strings, they are corrected to the server's timezone before being stored in AmaonOrder as timestamps.
opentaps.amazon.

importOrders service

Orders Creates the constellation of order-related data from any unimported Amazon orders, or any Amazon orders for which import has failed no more than the number of times defined in the opentaps.amazon.import.order.retry.threshold.import property. Each order will succeed or fail independently of the others - the service will only return error in the case of a database error. Individual Amazon orders are updated to AMZN_ORDR_IMPTD status if successful, AMZN_ORDR_IMPTD_ERR if unsuccessful. If unsuccessful, the importFailure count for the Amazon order will be incremented and the reason for the failure will be recorded in the corresponding AmazonOrder.importErrorMessage field. If successful, an AmazonOrderImport record and one or more AmazonOrderItemImport records will be created to define the relation to the Opentaps order and items. An AmazonParty record will also be created if the customer didn't previously exist in the system (determined by looking for the buyerEmailAddress in the AmazonParty entity).
opentaps.amazon.

acknowledgeImportedOrders

Orders Finds any Amazon orders which have been successfully imported and haven't yet been acknowledged, or for which acknowledgement failed previously. Constructs one XML document and posts it to Amazon, and updates each order's status to AMZN_ORDR_ACK_SENT if the post is successful, and AMZN_ORDR_SC_ACK_ERR if unsuccessful. All orders succeed or fail together, and the AmazonOrder.acknowledgeErrorMessage field stores the reason for failure. If successful, the AmazonOrder.processingDocumentId and AmazonOrder.acknowledgeMessageId fields are updated with values used later by the opentaps.amazon.checkAcknowledgementStatuses to retrieve processing data.
opentaps.amazon.

queueShippedItemsForFulfillmentPost

Orders Triggered by confirming a shipment with a carrier. If the shipment contains items related to an Amazon order, constructs an AmazonOrderItemFulfillment record for each item, for the quantity shipped, with ackStatusId AMZN_SHIP_NOT_ACKED.
opentaps.amazon.

acknowledgeFulfilledOrderItems

Orders Finds any AmazonOrderItemFulfillment records which haven't yet been acknowledged, or for which acknowledgement failed previously. Constructs one XML document and posts it to Amazon, and updates each order item's ackStatusId to AMZN_SHIP_ACK_SENT if the post is successful, and AMZN_SHIP_ACK_ERR if unsuccessful. All order item fulfillments succeed or fail together, and the AmazonOrderItemFulfillment.acknowledgeErrorMessage field stores the reason for failure. If successful, the AmazonOrderItemFulfillment.processingDocumentId and AmazonOrderItemFulfillment.acknowledgeMessageId fields are updated with values used later by the opentaps.amazon.checkAcknowledgementStatuses to retrieve processing data.
opentaps.amazon.

checkAcknowledgementStatuses

Orders Finds any Amazon-related objects (currently AmazonOrder and AmazonOrderItemFulfillment) which are recorded as having had an acknowledgment posted to Amazon. Retrieves the set of processingDocumentIds from these objects, and retrieves each document. Each document is examined for reports of processing errors relating to the objects. The object's ackStatusId field is updated to a success status (AMZN_ORDER_SCSS_ACKED/AMZN_ORDR_FAIL_ACKED or AMZN_SHIP_ACKED) or error status (AMZN_ORDER_SCSS_ACK_ERR/AMZN_ORDR_FL_ACK_ERR or AMZN_SHIP_ACK_ERR) and the object's acknowledgeErrorMessage holds any errors reported.
opentaps.amazon.

cancelUnimportedOrder

Orders Posts failure acknowledgement to Amazon of an order which can't or won't be imported. AmazonOrder.statusId is set to AMZN_ORDR_CANCELLED and ackStatusId to AMZN_ORDR_ACK_FL_ST if success or AMZN_ORDR_FL_ACK_ERR if error.

Entities

Entity Description
AmazonBatchUpdateHistory
AmazonNodeMappingType
AmazonNodeValidAttribute
AmazonOrder
AmazonOrderDocument
AmazonOrderImport
AmazonOrderItem
AmazonOrderItemFee
AmazonOrderItemFulfillment
AmazonOrderItemImport
AmazonOrderItemPriceComp
AmazonOrderItemPromo
AmazonOrderItemTaxAmount
AmazonOrderItemTaxJurisdtn
AmazonOrderItemTaxRate
AmazonOrderTaxJurisToAuth
AmazonOtherItemAttrValue
AmazonParty
AmazonProduct
AmazonProductBrowseNode
AmazonProductBulletPoint
AmazonProductFeedProcessing
AmazonProductImage
AmazonProductImageAck
AmazonProductImageAndAck
AmazonProductInventory
AmazonProductItemType
AmazonProductOtherItemAttr
AmazonProductPrice
AmazonProductSearchTerms
AmazonProductTargetAudience
AmazonProductUsedFor
AmazonTargetAudienceValue
AmazonUsedForValue
ViewAmazonProducts

Scheduled Jobs

Various services are required to run at intervals in order to retrieve Amazon orders and post product data to Amazon. Below is a table of the required services and suggested recurrence intervals:

Service Frequency/Run Time
opentaps.amazon.storePendingOrderDocuments Every 15 minutes
opentaps.amazon.acknowledgeOrderDocumentDownload Every 15 minutes
opentaps.amazon.extractOrdersForImport Every 15 minutes
opentaps.amazon.importOrders Every 15 minutes
opentaps.amazon.acknowledgeImportedOrders Every 15 minutes
opentaps.amazon.acknowledgeFulfilledOrderItems Hourly
opentaps.amazon.checkAcknowledgementStatuses Hourly
opentaps.amazon.publishProductsToAmazon Daily at 00:30
opentaps.amazon.batchUpdateAmazonProducts Daily at 00:00
opentaps.amazon.publishProductPriceToAmazon Daily at 02:30
opentaps.amazon.publishProductImagesToAmazon Daily at 03:00
opentaps.amazon.publishProductInventoryToAmazon Daily at 04:00
opentaps.amazon.deleteProductsFromAmazon Daily at 04:30
opentaps.amazon.checkLastFeedProcessingDocumentDownloadSuccess Daily at 06:00

Configuration Properties

Property Description Default Value

Credentials

merchantIdentifier Merchant Identifier credential specified by Amazon for the merchant
merchantName Merchant Name credential specified by Amazon for the merchant
password Password specified by Amazon for the merchant
url Production environment URL for Amazon SOAP services https://merchant-api.amazon.com/gateway/merchant-interface-mime
userName Username credential specified by Amazon for the merchant

Basic configuration properties

import.productStoreId ID of the ProductStore to use when importing orders AMAZON
export.product.price.productStoreGroupId productStoreGroupId for ProductPrice records in the Amazon channel -NA_
export.product.requireUpcCodes Require UPC codes for products posted to Amazon (UPC codes are required in at least the Health and Beauty stores) true
export.product.useProductIdAsSKU If false, a GoodIdentification of goodIdentificationTypeId SKU will be required in order to post a product to Amazon true
export.product.useUPCAsSKU Set to 'true' to use the product's UPC as its Amazon SKU. Set to false to use either productId or a GoodIdentification of type 'SKU', depending on the value of the opentaps.amazon.export.product.useProductIdAsSKU property false

Error email configuration

error.email.errorEmailLocale Locale setting for error emails en_US
error.email.errorEmailScreenUri.orders Screen location for order error email template component://amazon/widget/orders/AmazonOrderScreens.xml#errorEmail
error.email.errorEmailScreenUri.orders.orderAckValidate Screen location for template for order acknowledgement errors returned by Amazon component://amazon/widget/orders/AmazonOrderScreens.xml#orderAckValidateErrorEmail
error.email.errorEmailScreenUri.orders.orderItemFulfillValidate Screen location for template for order item fulfillment acknowledgement errors returned by Amazon component://amazon/widget/orders/AmazonOrderScreens.xml#orderItemFulfillValidateErrorEmail
error.email.errorEmailScreenUri.products Screen location for the template for template for the generic product-related error email component://amazon/widget/products/AmazonProductScreens.xml#errorEmail
error.email.errorEmailScreenUri.productFeedProcessingAgeWarning Screen location for the template for the email warning of the age of the last successful product feed processing document download component://amazon/widget/products/AmazonProductScreens.xml#productFeedProcessingAgeWarning
error.email.fromAddress 'From' email address for all error emails
error.email.productFeedProcessingAgeWarning.thresholdHours Age threshold for warning of the last successful product feed processing document download (in hours) 24
error.email.sendErrorEmails Send emails when errors occur in order import or product export true
error.email.toAddress 'To' email address for all error emails
error.email.linesForBulkErrorEmails Number of errors to include in each email when bulk error messages are sent 1000

Miscellaneous properties

createdByAmazonApplication Generic string for description fields of automatically-created records Created by application

Product export properties

default.product.descriptionField Name of a field in the Product entity from which to extract product descriptions. Must be one of description or longDescription longDescription
default.uom.length Amazon length unit of measure to use in cases where a unit of measure is missing for a product dimension IN
default.uom.weight Amazon weight unit of measure to use in cases where a unit of measure is missing for a product weight LB
export.product.conditionType Condition for exported products - must be one of:
  • New
  • UsedLikeNew
  • UsedVeryGood
  • UsedGood
  • UsedAcceptable
  • CollectibleLikeNew
  • CollectibleVeryGood
  • CollectibleGood
  • CollectibleAcceptable
  • Refurbished
  • Club
 New

Product image export

image.urlRoot URL root with which to prefix values in the SMALL_IMAGE_URL, LARGE_IMAGE_URL, etc. fields
default.image.main Mapping of Opentaps Product field/productContentTypeId to Amazon Main product image LARGE_IMAGE_URL
default.image.pt1 Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 1
default.image.pt2 Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 2
default.image.pt3 Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 3
default.image.pt4 Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 4
default.image.pt5 Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 5
default.image.pt6 Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 6
default.image.pt7 Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 7
default.image.pt8 Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 8
default.image.search Mapping of Opentaps Product field/productContentTypeId to Amazon Search product image SMALL_IMAGE_URL
default.image.swatch Mapping of Opentaps Product field/productContentTypeId to Amazon Swatch product image

Product price export

export.product.price.delistProductIfNoSalePrice Post a product's price as zero, thereby disabling the 'buy' button, if no current DEFAULT_PRICE exists for the product false

Product inventory export

export.inventory.inventoryIsAvailableIfMinimumStock Post product inventory as Available if a product's ProductFacility.minimumStock > 0 true
export.inventory.postActualInventory Post ATP for a product to Amazon. If false, a simple Available boolean will be posted true
export.inventory.postInventoryDaysToShip Post ProductFacility.daysToShip for a product to Amazon true

Order import

import.approveOrders Automatically approve orders imported from Amazon true
import.decimalPrecision Number of places of decimal precision to use for intermediate price calculations during order import 2
import.decimalRounding Rounding mode to use for intermediate price calculations during order import ROUND_HALF_UP
import.maxDaysToShip.Expedited Number of days to add to the current date in order to calculate a Ship-By Date for orders with Expedited service level 3
import.maxDaysToShip.Standard Number of days to add to the current date in order to calculate a Ship-By Date for orders with Standard service level 7
import.requireTaxAuthority Require an Amazon taxLocationCode to Opentaps taxAuthorityGeoId/taxAuthorityPartyId mapping in the AmazonTaxLocToTaxAuth entity to successfully import orders with tax amounts true

Retry thresholds

export.product.retry.threshold.post Number of times to retry posting new/updated products 3
import.order.retry.threshold.acknowledge Number of times to retry acknowledging an order before giving up (not implemented yet) 3
import.order.retry.threshold.import Number of times to retry importing an order before giving up 3
import.document.retry.threshold.acknowledge Number of times to acknowledging a pending order download before giving up (not implemented yet) 3
import.document.retry.threshold.download Number of times to retry a failed pending order document download before giving up (not implemented yet) 3
import.document.retry.threshold.extract Number of times to retry extracting orders from a pending order download before giving up 3

Phone number parsing

import.phone.regexp Regular expression used for identifying and parsing phone numbers during order import. Note that backslashes must be doubled. [0]|[2-9]){1})\\D*(\\d{3}\\D*\\d{4})\\D*(\\d*)\\s*$
import.phone.regexp.group.areaCode Index of the regular expression capturing group defined in the import.phone.regexp property which represents the area code. Note that capturing groups begin at 1. 2
import.phone.regexp.group.countryCode Index of the regular expression capturing group defined in the import.phone.regexp property which represents the country code. Note that capturing groups begin at 1. 1
import.phone.regexp.group.extension Index of the regular expression capturing group defined in the import.phone.regexp property which represents the extension. Note that capturing groups begin at 1. 4
import.phone.regexp.group.phoneNumber Index of the regular expression capturing group defined in the import.phone.regexp property which represents the phone number itself. Note that capturing groups begin at 1. 3

Shipping configuration

shipping.carrierPartyId.fedEx Opentaps partyId of the carrier party for Federal Express FEDEX
shipping.carrierPartyId.ups Opentaps partyId of the carrier party for UPS UPS
shipping.carrierPartyId.usps Opentaps partyId of the carrier party for the US Postal Service USPS
import.shipmentMethodTypeId.Expedited Shipment method to use for orders with Expedited service level AIR
import.shipmentMethodTypeId.Standard Shipment method to use for orders with Standard service level GROUND
import.carrierPartyId.Expedited PartyId of the carrier party which handles Expedited shipments UPS
import.carrierPartyId.Standard PartyId of the carrier party which handles Standard shipments UPS

Test Cases

Order Item Fulfillment (Charge-When-Ship)

Test Case Action Result
1 Order an item on Amazon.com and wait until the order has been imported into Opentaps. Pack the full order in the Warehouse application. Wait until the scheduled job for the opentaps.amazon.acknowledgeFulfilledOrderItems services has run (or run it manually). Result: There should be AmazonOrderItemFulfillment records representing the fulfilled order items, for which the ackStatusId field should be AMZN_SHIP_ACK_ERR. The orders should be marked 'Confirmed' in the Amazon Seller Central site's 'Manage Orders' screen.
2 Place a multiple-item order on Amazon.com and wait until the order has been imported. Pack part of the order. Wait until the service has run as above. The shipped order items should be noted in Seller Central, but the entire order should not be marked confirmed since it hasn't all been shipped.
3 Pack the rest of the order from case 2. Wait until the service has run as above. The order should be marked confirmed in Seller Central, since it has been fully shipped.

UPC Codes

Amazon.com is divided into 'stores', each of which are responsible for certain types of products. Some stores (Health, Beauty) require a valid, unique UPC-A (12-digit) code to be supplied for each product. Depending on your requirements, the Amazon.com integration component can be configured to check UPC validity and supply a UPC to Amazon, and also can be configured to use the product's UPC as the SKU for Amazon. The relevant properties are these:

  • opentaps.amazon.export.product.requireUpcCodes - set to 'true' to require a valid SKU before posting a product to Amazon. Must be set to 'true' if the opentaps.amazon.export.product.useUPCAsSKU property (below) is true
  • opentaps.amazon.export.product.useUPCAsSKU - set to 'true' to use the product's UPC as its Amazon SKU. Set to false to use either productId or a GoodIdentification of type 'SKU', depending on the value of the opentaps.amazon.export.product.useProductIdAsSKU property

Since Amazon only recognizes the 12-digit form of UPC (UPC-A), any 8-digit (compressed) UPC-E codes will be expanded to UPC-A codes before being posted to Amazon. If both a UPC-A code and a UPC-E code exist for a product, the UPC-A code will be used and the UPC-E code will be ignored. In the case of multiple UPC-A or multiple UPC-E codes existing for a given product, the most recently modified code will be used.

Import of existing Amazon Products

Data Model

  • AmazonProduct holds Amazon-specific data and data relating to product posting times, successes and failures
  • AmazonProductPrice, AmazonProductImage and AmazonProductInventory hold only data relating to product posting times, successes and failures and are each related to AmazonProduct
  • ProductPrice holds Amazon-specific prices, designated by ProductPrice.productStoreGroupId
  • AmazonProductSearchTerms and AmazonProductBulletPoint hold search terms and bullet points and are related to AmazonProduct by the productId field
  • The AmazonProductUsedFor entity holds possible UsedFor values, and AmazonUsedForValue relates the AmazonProduct and AmazonProductUsedFor entities by the productId field
  • The AmazonProductTargetAudience entity holds possible TargetAudience values, and AmazonTargetAudienceValue relates the AmazonProduct and AmazonProductTargetAudience entities by the productId field
  • The AmazonProductOtherItemAttr entity holds possible OtherItemAttribute values, and AmazonOtherItemAttrValue relates the AmazonProduct and AmazonProductOtherItemAttr entities by the productId field
  • AmazonProductItemType holds possible ItemType values and is related directly to AmazonProduct by the AmazonProduct.itemTypeId field

Notes

  • Amazon product import must happen after Opentaps products have been imported
  • Products must have matching SKU GoodIdentification records
  • Products must have matching UPCA GoodIdentification records if the opentaps.amazon.export.product.requireUpcCodes property is set to true (this is required for the Health store)
  • Required records:
    • AmazonProduct (1)
    • ProductPrice (1 or 2)
    • AmazonProductPrice (1)
    • AmazonProductInventory (1)
    • AmazonProductImage (1)
  • Optional records:
    • AmazonProductSearchTerms (1 for each Amazon search term, minimum 0, maximum 5)
    • AmazonProductBulletPoint (1 for each Amazon bullet point, minimum 0, maximum 5)
    • AmazonUsedForValue (1 for each Amazon UsedFor value, minimum 0, maximum 5)
    • AmazonTargetAudienceValue (1 for each Amazon TargetAudience value, minimum 0, maximum 3)
    • AmazonOtherItemAttrValue (1 for each Amazon OtherItemAttributes value, minimum 0, maximum 5)


Records to Create

AmazonProduct

Field Type Allow Empty Initial Value Notes
productId String No Opentaps productId
statusId String No AMZN_PROD_CHANGED
productTaxCode String No From imported data
releaseDate Date Yes From imported data
itemTypeId String Yes From imported data Must exist in AmazonProductItemType entity
nodeId String Yes null or from imported data Must exist in AmazonProductBrowseNode entity
priority Integer Yes From imported data Not currently implemented
browseExclusion String (Y/N) Yes From imported data Not currently implemented
recommendationExclusion String (Y/N) Yes From imported data Not currently implemented
cost Currency Yes From imported data Not currently implemented
currencyUom String Yes From imported data Not currently implemented
tier Integer Yes From imported data Not currently implemented
purchasingCategory String Yes From imported data Not currently implemented
purchasingSubCategory String Yes From imported data Not currently implemented
packagingType String Yes From imported data Not currently implemented
underlyingAvailability String Yes From imported data Not currently implemented
replenishmentCategory String Yes From imported data Not currently implemented
dropShipStatus String Yes From imported data Not currently implemented
outOfStockWebsiteMessage String Yes From imported data Not currently implemented
registeredParameter String Yes From imported data Not currently implemented
processingDocumentId Integer Yes null
postTimestamp Date Yes null
postErrorMessage String Yes null
postFailures Integer No 0
ackStatusId String No AMZN_PROD_NOT_ACKED
acknowledgeTimestamp Date Yes null
acknowledgeErrorMessage String Yes null
acknowledgeMessageId String Yes null

ProductPrice

Field Type Allow Empty Initial Value Notes
productId String No Opentaps productId
productPriceTypeId String No DEFAULT_PRICE or LIST_PRICE Value depends on whether the price is a standard price or a sale price. Use LIST_PRICE for standard prices and DEFAULT_PRICE for sale prices
productPricePurposeId String No PURCHASE
currencyUomId String No Value of ProductStore.defaultCurrencyUomId for the productStoreId defined in the opentaps.amazon.import.productStoreId property
productStoreGroupId String No Value of the opentaps.amazon.export.product.price.productStoreGroupId property
fromDate Date No Current date
thruDate Date Yes If the price is a standard price, use the current date if the product is not active on Amazon.com, use null if the product is currently active. If the price is a sale price, use null unless the sale price has expired, in which case use the current date or the date of the expiry.
price Currency No Price of the product in the Amazon channel, corrected for the currency in the currencyUomId field

AmazonProductPrice

Field Type Allow Empty Initial Value Notes
productId String No Opentaps productId Must exist in AmazonProduct
statusId String No AMZN_PROD_CHANGED
processingDocumentId Integer Yes null
postTimestamp Date Yes null
postErrorMessage String Yes null
postFailures Integer No 0
ackStatusId String No AMZN_PROD_NOT_ACKED
acknowledgeTimestamp Date Yes null
acknowledgeErrorMessage String Yes null
acknowledgeMessageId Integer Yes null

AmazonProductInventory

Field Type Allow Empty Initial Value Notes
productId String No Opentaps productId Must exist in AmazonProduct
statusId String No AMZN_PROD_CHANGED
processingDocumentId Integer Yes null
postTimestamp Date Yes null
postErrorMessage String Yes null
postFailures Integer No 0
ackStatusId String No AMZN_PROD_NOT_ACKED
acknowledgeTimestamp Date Yes null
acknowledgeErrorMessage String Yes null
acknowledgeMessageId Integer Yes null

AmazonProductImage

Field Type Allow Empty Initial Value Notes
productId String No Opentaps productId Must exist in AmazonProduct
statusId String No AMZN_PROD_CHANGED
processingDocumentId Integer Yes null
postTimestamp Date Yes null
postErrorMessage String Yes null
postFailures Integer No 0

AmazonProductSearchTerms

Field Type Allow Empty Initial Value Notes
searchTermId String No Auto-sequenced
productId String No Opentaps productId Must exist in AmazonProduct
description Integer No From imported data

AmazonProductBulletPoint

Field Type Allow Empty Initial Value Notes
bulletPointId String No Auto-sequenced
productId String No Opentaps productId Must exist in AmazonProduct
description Integer No From imported data

AmazonUsedForValue

Field Type Allow Empty Initial Value Notes
productId String No Opentaps productId Must exist in AmazonProduct
usedForId String No From imported data Must exist in AmazonProductUsedFor

AmazonTargetAudienceValue

Field Type Allow Empty Initial Value Notes
productId String No Opentaps productId Must exist in AmazonProduct
targetAudienceId String No From imported data Must exist in AmazonProductTargetAudience

AmazonOtherItemAttrValue

Field Type Allow Empty Initial Value Notes
productId String No Opentaps productId Must exist in AmazonProduct
otherItemAttrId String No From imported data Must exist in AmazonProductOtherItemAttr
Retrieved from "https://docs.opentaps.org/docs/index.php?title=Amazon_Integration&oldid=5544"