Integrating with FeedAMP Flexible Workflow via SFTP
FeedAMP (Automated MarketPlaces) provides an automated workflow for handling orders placed on marketplaces. Integration with FeedAMP can be achieved via SFTP, Rest API, as well as via popular e-commerce platform APIs (e.g. Shopify, Magento). The SFTP option can be used if no direct integration is available with your e-commerce platform. (NOTE: Non-secure FTP is not available as an integration option)
FeedAMP operates at a frequency of 15 minutes for all polling actions. Integrations can also be paused and have operations run manually and individually.
The FeedAMP SFTP integration uses a set of custom text files to process orders. There are two main categories of files: Data and Report files. A brief overview is presented here; for more details on formatting and the records these files contain, see SFTP Files. (Note: This document uses the words “row” and “record” interchangeably)
Data files are used for the various stages of automated order processing:
Report files are used for post-processing operations:
There are three main stages of FeedAMP order processing: Placement, Acknowledgement, and Fulfillment.
The actions FeedAMP performs initially:
Only some marketplaces require order acknowledgement. After getting new orders, FeedAMP will:
Once orders have been placed, the following actions occur:
An order can have multiple shipments and/or multiple cancellations. Each order line must be a separate row in a Processed Orders file, though shipments and cancellations for a particular order line can be consolidated in a single row.
FeedAMP can handle shipments and cancellations for the same order spread across different files and supplied at different times. However, FeedAMP only reports shipment and cancellation updates to the Marketplace after it has accounted for all items in an order. Any fulfillment information received after an order has all records fulfilled will be disregarded.
For refund processing, the 2 stages/actions FeedAMP performs are:
Each refund is applied to a single order line in a single order, although there can be multiple refunds for a given order line (e.g. one refund for 1 of 3 quantity of the order line, and then another refund for the remaining 2).
Refunds can be applied to orders only after they have been fulfilled. Be careful not to issue a refund for an item after already canceling the item; this may result in the refund total exceeding the amount due to the customer.
For return processing, the 3 stages/actions FeedAMP performs are:
The actions FeedAMP performs initially are:
If the marketplace does not pre-authorize returns and requires returns to be authorized
Authorized the marketplace to either complete or cancel the return request
Poll the client’s SFTP server looking for return refund files
Report refund information to the order’s origin marketplace to close out the return
Returns are stand alone records that can relate to FeedAMP orders OR orders that exist outside of our system. Returns can only be applied to orders after they have been fulfilled, the order state should be either Fulfilled or Complete.
If you have not already set up your Marketplace account(s), you will need to do so before enabling FeedAMP. Marketplaces may provide you their respective processes to follow.
Typically, the process includes:
Once you have set up your account(s), provide Feedonomics with the API authentication keys and/or login credentials to the seller accounts for all marketplaces automated using FeedAMP.
Files types are separated by directory. The default SFTP paths for each file are as follows, relative to the base directory path.
FeedAMP SFTP Integrations use two main categories of file: Data Files are used during the various stages of order processing, while Report Files present info relevant for post-processing and debugging.
File names must adhere to the following format:
{file_prefix}_{marketplace_name}_{yyyymmddhhmmss}.{file_type}
By default, file prefixes for each type of file are the same as their corresponding file type’s directory names. For example:
The “marketplace_name” is FeedAMP's identification of the marketplace integration. This refers specifically to the integration name, rather than the type of marketplace used. The formatting requirements for “marketplace_name” are:
File name timestamps can be in any time zone as long as they are consistent. Feedonomics will provide file name timestamps in GMT time zone for all applicable file types.
Examples:
orders_walmart_20171231235959.csv
orders_walmart_ca_20171231235959.csv
processed_orders_amazon_us_20171231235959.tsv
processed_orders_amazon_uk_20171231235959.tsv
order_refunds_ebay_20180125012500.tsv
Note: When opening a file with a spreadsheet processor, the data may get unintentionally mutated by column type defaults. In order to prevent this, be sure to specify each column as "text"/"raw" rather than "general"/"standard" when opening. Alternatively, open the file with a text editor (e.g. Notepad++, Sublime Text, Visual Studio Code) to preserve the raw data.
Date/time values in file contents should be in ISO-8601 format.
All files must use a delimiter-separated values format. The SFTP platform provides configuration options
to match the desired file type and delimiter settings. The default format for files is as follows:
Tab-separated (\t) values format (TSV)
Delimited with a space character ( )
Enclosed with double quotes (“) if necessary
Enclosures escaped with backslash (\)
Exception: The Results file has a set number of lines above the header that provide general results information. See the Results File Formatting section below for more details.
Descriptions and logic for each field can be found in the documentation file named FeedAMP_SFTP_Integration_Specs_V4.7.xlsx
Example files can be found in the provided sample_files directory. Note that the format for some fields is subject to change depending on how each marketplace represents them, and not all information in the sample files may be completely accurate to that of real orders.
Orders file
Processed Orders file
Order Refunds file
Return Files
IMPORTANT: When you first set up the FTP integration, the identity and order of the fields in the order file will be locked to the specifications reflected in the FeedAMP_FTP_Integration_Specs file. If new fields are made available in future releases, your FeedAMP configuration can be modified to add additional fields. In order to ensure backwards compatibility, existing columns will not be removed or renamed.
After processing a file from a merchant (i.e. Processed Orders file or an Order Refunds file), FeedAMP will archive it and generate a results file.
All files processed by FeedAMP will be moved into the archive directory of the current directory. The file name and contents are preserved.
For each file processed by FeedAMP, a corresponding results file will be generated in the results directory. The results file name will be of the format *_results.{extension} . The wildcard (*) refers to the original file name.
If FeedAMP determines a file, header, or row within a file to be invalid in any way, the reason for
rejection and steps to rectify and re-submit the record for reprocessing will be provided in the results file.
X out of TOTAL records (rows) successfully processed
Any file-level error details - Any record-level error details, including the line number in the original file (the original file can be found in the archive directory) Common reasons for rejecting a record are:
The results file always begins with a single line that specifies how many records were processed. It then has two optional sections: “File Level Errors” and “Record Errors”. Record errors are presented in TSV format with a header.
The combination of the original file under the file’s corresponding archive directory along with details of the file-level or row-level errors in the results file will allow you to know when rejections occurred and for what reasons.
Once the error is understood, you can create a new file containing the corrected rows under the folder that FeedAMP polls to process the file types (i.e. the directories for Processed Orders / Order Refunds). FeedAMP will then process the order during its next cycle as normal.
IMPORTANT: It is vital that you give the new file a unique name that still fits the file formatting and naming conventions. If the file name identical to an already processed file is used, the corresponding Archive and Results files that were already generated will be overwritten.