Amazon Integration

From Opentaps Wiki

Jump to: navigation, search

Contents

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

ServiceAreaActionNotes
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

EntityDescription
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:

ServiceFrequency/Run Time
opentaps.amazon.storePendingOrderDocumentsEvery 15 minutes
opentaps.amazon.acknowledgeOrderDocumentDownloadEvery 15 minutes
opentaps.amazon.extractOrdersForImportEvery 15 minutes
opentaps.amazon.importOrdersEvery 15 minutes
opentaps.amazon.acknowledgeImportedOrdersEvery 15 minutes
opentaps.amazon.acknowledgeFulfilledOrderItemsHourly
opentaps.amazon.checkAcknowledgementStatusesHourly
opentaps.amazon.publishProductsToAmazonDaily at 00:30
opentaps.amazon.batchUpdateAmazonProductsDaily at 00:00
opentaps.amazon.publishProductPriceToAmazonDaily at 02:30
opentaps.amazon.publishProductImagesToAmazonDaily at 03:00
opentaps.amazon.publishProductInventoryToAmazonDaily at 04:00
opentaps.amazon.deleteProductsFromAmazonDaily at 04:30
opentaps.amazon.checkLastFeedProcessingDocumentDownloadSuccessDaily at 06:00

Configuration Properties

PropertyDescriptionDefault Value

Credentials

merchantIdentifierMerchant Identifier credential specified by Amazon for the merchant
merchantNameMerchant Name credential specified by Amazon for the merchant
passwordPassword specified by Amazon for the merchant
urlProduction environment URL for Amazon SOAP serviceshttps://merchant-api.amazon.com/gateway/merchant-interface-mime
userNameUsername credential specified by Amazon for the merchant

Basic configuration properties

import.productStoreIdID of the ProductStore to use when importing ordersAMAZON
export.product.price.productStoreGroupIdproductStoreGroupId for ProductPrice records in the Amazon channel-NA_
export.product.requireUpcCodesRequire UPC codes for products posted to Amazon (UPC codes are required in at least the Health and Beauty stores)true
export.product.useProductIdAsSKUIf false, a GoodIdentification of goodIdentificationTypeId SKU will be required in order to post a product to Amazontrue
export.product.useUPCAsSKUSet 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 propertyfalse

Error email configuration

error.email.errorEmailLocaleLocale setting for error emailsen_US
error.email.errorEmailScreenUri.ordersScreen location for order error email templatecomponent://amazon/widget/orders/AmazonOrderScreens.xml#errorEmail
error.email.errorEmailScreenUri.orders.orderAckValidateScreen location for template for order acknowledgement errors returned by Amazoncomponent://amazon/widget/orders/AmazonOrderScreens.xml#orderAckValidateErrorEmail
error.email.errorEmailScreenUri.orders.orderItemFulfillValidateScreen location for template for order item fulfillment acknowledgement errors returned by Amazoncomponent://amazon/widget/orders/AmazonOrderScreens.xml#orderItemFulfillValidateErrorEmail
error.email.errorEmailScreenUri.productsScreen location for the template for template for the generic product-related error emailcomponent://amazon/widget/products/AmazonProductScreens.xml#errorEmail
error.email.errorEmailScreenUri.productFeedProcessingAgeWarningScreen location for the template for the email warning of the age of the last successful product feed processing document downloadcomponent://amazon/widget/products/AmazonProductScreens.xml#productFeedProcessingAgeWarning
error.email.fromAddress'From' email address for all error emails
error.email.productFeedProcessingAgeWarning.thresholdHoursAge threshold for warning of the last successful product feed processing document download (in hours)24
error.email.sendErrorEmailsSend emails when errors occur in order import or product exporttrue
error.email.toAddress'To' email address for all error emails
error.email.linesForBulkErrorEmailsNumber of errors to include in each email when bulk error messages are sent1000

Miscellaneous properties

createdByAmazonApplicationGeneric string for description fields of automatically-created recordsCreated by application

Product export properties

default.product.descriptionFieldName of a field in the Product entity from which to extract product descriptions. Must be one of description or longDescriptionlongDescription
default.uom.lengthAmazon length unit of measure to use in cases where a unit of measure is missing for a product dimensionIN
default.uom.weightAmazon weight unit of measure to use in cases where a unit of measure is missing for a product weightLB
export.product.conditionTypeCondition for exported products - must be one of:
  • New
  • UsedLikeNew
  • UsedVeryGood
  • UsedGood
  • UsedAcceptable
  • CollectibleLikeNew
  • CollectibleVeryGood
  • CollectibleGood
  • CollectibleAcceptable
  • Refurbished
  • Club
New

Product image export

image.urlRootURL root with which to prefix values in the SMALL_IMAGE_URL, LARGE_IMAGE_URL, etc. fields
default.image.mainMapping of Opentaps Product field/productContentTypeId to Amazon Main product imageLARGE_IMAGE_URL
default.image.pt1Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 1
default.image.pt2Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 2
default.image.pt3Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 3
default.image.pt4Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 4
default.image.pt5Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 5
default.image.pt6Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 6
default.image.pt7Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 7
default.image.pt8Mapping of Opentaps Product field/productContentTypeId to Amazon alternate product image 8
default.image.searchMapping of Opentaps Product field/productContentTypeId to Amazon Search product imageSMALL_IMAGE_URL
default.image.swatchMapping of Opentaps Product field/productContentTypeId to Amazon Swatch product image

Product price export

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

Product inventory export

export.inventory.inventoryIsAvailableIfMinimumStockPost product inventory as Available if a product's ProductFacility.minimumStock > 0true
export.inventory.postActualInventoryPost ATP for a product to Amazon. If false, a simple Available boolean will be postedtrue
export.inventory.postInventoryDaysToShipPost ProductFacility.daysToShip for a product to Amazontrue

Order import

import.approveOrdersAutomatically approve orders imported from Amazontrue
import.decimalPrecisionNumber of places of decimal precision to use for intermediate price calculations during order import2
import.decimalRoundingRounding mode to use for intermediate price calculations during order importROUND_HALF_UP
import.maxDaysToShip.ExpeditedNumber of days to add to the current date in order to calculate a Ship-By Date for orders with Expedited service level3
import.maxDaysToShip.StandardNumber of days to add to the current date in order to calculate a Ship-By Date for orders with Standard service level7
import.requireTaxAuthorityRequire an Amazon taxLocationCode to Opentaps taxAuthorityGeoId/taxAuthorityPartyId mapping in the AmazonTaxLocToTaxAuth entity to successfully import orders with tax amountstrue

Retry thresholds

export.product.retry.threshold.postNumber of times to retry posting new/updated products3
import.order.retry.threshold.acknowledgeNumber of times to retry acknowledging an order before giving up (not implemented yet)3
import.order.retry.threshold.importNumber of times to retry importing an order before giving up3
import.document.retry.threshold.acknowledgeNumber of times to acknowledging a pending order download before giving up (not implemented yet)3
import.document.retry.threshold.downloadNumber of times to retry a failed pending order document download before giving up (not implemented yet)3
import.document.retry.threshold.extractNumber of times to retry extracting orders from a pending order download before giving up3

Phone number parsing

import.phone.regexpRegular 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.areaCodeIndex 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.countryCodeIndex 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.extensionIndex 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.phoneNumberIndex 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.fedExOpentaps partyId of the carrier party for Federal ExpressFEDEX
shipping.carrierPartyId.upsOpentaps partyId of the carrier party for UPSUPS
shipping.carrierPartyId.uspsOpentaps partyId of the carrier party for the US Postal ServiceUSPS
import.shipmentMethodTypeId.ExpeditedShipment method to use for orders with Expedited service levelAIR
import.shipmentMethodTypeId.StandardShipment method to use for orders with Standard service levelGROUND
import.carrierPartyId.ExpeditedPartyId of the carrier party which handles Expedited shipmentsUPS
import.carrierPartyId.StandardPartyId of the carrier party which handles Standard shipmentsUPS

Test Cases

Order Item Fulfillment (Charge-When-Ship)

Test CaseActionResult
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

FieldTypeAllow EmptyInitial ValueNotes
productIdStringNoOpentaps productId
statusIdStringNoAMZN_PROD_CHANGED
productTaxCodeStringNoFrom imported data
releaseDateDateYesFrom imported data
itemTypeIdStringYesFrom imported dataMust exist in AmazonProductItemType entity
nodeIdStringYesnull or from imported dataMust exist in AmazonProductBrowseNode entity
priorityIntegerYesFrom imported dataNot currently implemented
browseExclusionString (Y/N)YesFrom imported dataNot currently implemented
recommendationExclusionString (Y/N)YesFrom imported dataNot currently implemented
costCurrencyYesFrom imported dataNot currently implemented
currencyUomStringYesFrom imported dataNot currently implemented
tierIntegerYesFrom imported dataNot currently implemented
purchasingCategoryStringYesFrom imported dataNot currently implemented
purchasingSubCategoryStringYesFrom imported dataNot currently implemented
packagingTypeStringYesFrom imported dataNot currently implemented
underlyingAvailabilityStringYesFrom imported dataNot currently implemented
replenishmentCategoryStringYesFrom imported dataNot currently implemented
dropShipStatusStringYesFrom imported dataNot currently implemented
outOfStockWebsiteMessageStringYesFrom imported dataNot currently implemented
registeredParameterStringYesFrom imported dataNot currently implemented
processingDocumentIdIntegerYesnull
postTimestampDateYesnull
postErrorMessageStringYesnull
postFailuresIntegerNo0
ackStatusIdStringNoAMZN_PROD_NOT_ACKED
acknowledgeTimestampDateYesnull
acknowledgeErrorMessageStringYesnull
acknowledgeMessageIdStringYesnull

ProductPrice

FieldTypeAllow EmptyInitial ValueNotes
productIdStringNoOpentaps productId
productPriceTypeIdStringNoDEFAULT_PRICE or LIST_PRICEValue 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
productPricePurposeIdStringNoPURCHASE
currencyUomIdStringNoValue of ProductStore.defaultCurrencyUomId for the productStoreId defined in the opentaps.amazon.import.productStoreId property
productStoreGroupIdStringNoValue of the opentaps.amazon.export.product.price.productStoreGroupId property
fromDateDateNoCurrent date
thruDateDateYesIf 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.
priceCurrencyNoPrice of the product in the Amazon channel, corrected for the currency in the currencyUomId field

AmazonProductPrice

FieldTypeAllow EmptyInitial ValueNotes
productIdStringNoOpentaps productIdMust exist in AmazonProduct
statusIdStringNoAMZN_PROD_CHANGED
processingDocumentIdIntegerYesnull
postTimestampDateYesnull
postErrorMessageStringYesnull
postFailuresIntegerNo0
ackStatusIdStringNoAMZN_PROD_NOT_ACKED
acknowledgeTimestampDateYesnull
acknowledgeErrorMessageStringYesnull
acknowledgeMessageIdIntegerYesnull

AmazonProductInventory

FieldTypeAllow EmptyInitial ValueNotes
productIdStringNoOpentaps productIdMust exist in AmazonProduct
statusIdStringNoAMZN_PROD_CHANGED
processingDocumentIdIntegerYesnull
postTimestampDateYesnull
postErrorMessageStringYesnull
postFailuresIntegerNo0
ackStatusIdStringNoAMZN_PROD_NOT_ACKED
acknowledgeTimestampDateYesnull
acknowledgeErrorMessageStringYesnull
acknowledgeMessageIdIntegerYesnull

AmazonProductImage

FieldTypeAllow EmptyInitial ValueNotes
productIdStringNoOpentaps productIdMust exist in AmazonProduct
statusIdStringNoAMZN_PROD_CHANGED
processingDocumentIdIntegerYesnull
postTimestampDateYesnull
postErrorMessageStringYesnull
postFailuresIntegerNo0

AmazonProductSearchTerms

FieldTypeAllow EmptyInitial ValueNotes
searchTermIdStringNoAuto-sequenced
productIdStringNoOpentaps productIdMust exist in AmazonProduct
descriptionIntegerNoFrom imported data

AmazonProductBulletPoint

FieldTypeAllow EmptyInitial ValueNotes
bulletPointIdStringNoAuto-sequenced
productIdStringNoOpentaps productIdMust exist in AmazonProduct
descriptionIntegerNoFrom imported data

AmazonUsedForValue

FieldTypeAllow EmptyInitial ValueNotes
productIdStringNoOpentaps productIdMust exist in AmazonProduct
usedForIdStringNoFrom imported dataMust exist in AmazonProductUsedFor

AmazonTargetAudienceValue

FieldTypeAllow EmptyInitial ValueNotes
productIdStringNoOpentaps productIdMust exist in AmazonProduct
targetAudienceIdStringNoFrom imported dataMust exist in AmazonProductTargetAudience

AmazonOtherItemAttrValue

FieldTypeAllow EmptyInitial ValueNotes
productIdStringNoOpentaps productIdMust exist in AmazonProduct
otherItemAttrIdStringNoFrom imported dataMust exist in AmazonProductOtherItemAttr


© Open Source Strategies, Inc. Development of this documentation site is sponsored by Open Source Strategies, Inc.
Help support opentaps with a subscription to this documentation site.