Amazon SP-API Orders and Products Feeds Flow

The purpose of this document is to give good understanding how the feeds will be handled within Hemi.

When we are creating a feed, we record the account Marketplace Feed > Account.

If we have successfully pass our internal validation and push the feed to Amazon we will receive the feed ID which will be stored in Hemi in Marketplace Feed > External ID.

The “type“ field Marketplace Feed > Type is for the internal type of the feed. It is free text field, where we describe the name of the feed.

The feed type, which will be returned form Amazon will be stored in Marketplace Feed > External Type. Тhe External Type should be as follow:

Order Acknowledgement Feed: POST_ORDER_ACKNOWLEDGEMENT_DATA

Order Adjustments Feed: POST_PAYMENT_ADJUSTMENT_DATA

Order Fulfillment Feed: POST_ORDER_FULFILLMENT_DATA

<v1.7> Product Creation Feed: JSON_LISTINGS_FEED </v1.7>

Step 1. Create a feed document

Creates a feed document for the feed type that you specify. Amazon returns a feedDocumentId value, encryption details, and a URL for uploading the feed contents.

Request Parameters:

Request Example:

POST https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/documents
{
  "contentType":"text/tab-separated-values; charset=UTF-8"
}

Example response:

"responses": {
          "201": {
            "description": "Successfully created a feed document that is ready to receive contents.",
            "schema": {
              "$ref": "#/definitions/CreateFeedDocumentResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference ID."
              }
            },
            "x-amzn-api-sandbox": {
              "static": [
                {
                  "request": {
                    "parameters": {
                      "body": {
                        "value": {
                          "contentType": "text/tab-separated-values; charset=UTF-8"
                        }
                      }
                    }
                  },
                "response": {
                  "payload": {
                    "feedDocumentId": "3d4e42b5-1d6e-44e8-a89c-2abfca0625bb",
                    "url": "https://d34o8swod1owfl.cloudfront.net/Feed_101__POST_PRODUCT_DATA_%2BKEY%3DFeed_101%2BMode%3DCBC%2BINITVEC%3D8f+6c+cc+56+0d+50+a2+d0+31+ec+80+be+f2+6a+1d+0a",
                    "encryptionDetails": {
                      "standard": "AES",
                      "initializationVector": "8f 6c cc 56 0d 50 a2 d0 31 ec 80 be f2 6a 1d 0a",
                      "key": "key"
                    }

Mapping:

Step 2: Encrypt and upload the feed data

You can encrypt and upload feed data using the information returned in the previous step. All samples provided from Amazon are on Java thus we will need to check how at the moment with our current MWS Amazon integration we are encrypting and uploading the feeds.

Step 3: Create a feed

The Create Feed operation to specify the feed document identifier, the feed type, the marketplaces that you want the feed to be applied to, and any optional parameters that you want.

Parameters:

Request example:

POST https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/feeds
{
  "feedType":"POST_PRODUCT_DATA",
  "marketplaceIds":[
    "ATVPDKIKX0DER",
    "A2EUQ1WTGCTBG2"
  ],
  "inputFeedDocumentId":"amzn1.tortuga.3.920614b0-fc4c-4393-b0d9-fff175300000.T29XK4YL08B2VM"
}

Mapping:

Listing Feed : JSON_LISTINGS_FEED <v1.8>Inventory Feed: JSON_LISTINGS_FEED Pricing Feed: JSON_LISTINGS_FEED</v1.8> | | marketplaceIds | A list of identifiers for marketplaces that you want the feed to be applied to. | Yes | | Mapping list is provided | | inputFeedDocumentId | The document identifier returned by the createFeedDocument operation in Step 3 | Yes | | |

Example response:

{
  "payload":
  {
    "feedId": "23492394"
  }
}

Mapping:

Step 4: Confirm feed processing

API Call: GET /feeds/2021-06-30/feeds

Confirm feed processing by periodically calling the getFeed operation ( from step 3 ) until the feed moves into one of the following terminal states: DONE, CANCELLED, or FATAL. When the feed moves into the DONE state, proceed to Step 5.

Path parameter:

Request example:

GET https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/feeds/23492394

Example response:

{
  "processingEndTime":"2020-08-10T16:56:55+00:00",
  "processingStatus":"DONE",
  "marketplaceIds":[
    "ATVPDKIKX0DER"
  ],
  "feedId":"23492394",
  "feedType":"POST_PRODUCT_DATA",
  "createdTime":"2020-08-10T16:55:32+00:00",
  "processingStartTime":"2020-08-10T16:55:40+00:00",
  "resultFeedDocumentId":"amzn1.tortuga.3.ed4cd0d8-447b-4c22-96b5-52da8ace1207.T3YUVYPGKE9BMY"
}

Mapping:

DONE- The feed has completed processing. Examine the contents of the result document to determine if there were any errors during processing. CANCELLED- The feed was cancelled before it started processing FATAL - The feed has completed processing. Examine the contents of the result document to determine if there were any errors during processing. IN_PROGRESS-The feed is being processed. IN_QUEUE - The feed has not yet started processing. It may be waiting for another IN_PROGRESS feed. | Yes | Marketplace Feed >External Status | | | marketplaceIds | A list of identifiers for the marketplaces that the feed is applied to. Type: < string > array | No | | Mapping list is provided | | feedId | The identifier for the feed document. This identifier is unique only in combination with a seller ID. Type: string | Yes | | | | feedType | The feed type. Type: string | Yes | Marketplace Feed > External Type | Values for: Listing Feed : JSON_LISTINGS_FEED Inventory Feed: POST_INVENTORY_AVAILABILITY_DATA Pricing Feed: POST_PRODUCT_PRICING_DATA | | createdTime | The date and time when the feed was created, in ISO 8601 date time format. Type: string (date-time) | | | | | processingStartTime | The date and time when feed processing started, in ISO 8601 date time format. string (date-time) | | Marketplace Feed > Submitted Date | | | resultFeedDocumentId | The identifier for the feed document. This identifier is unique only in combination with a seller ID. string | | Marketplace Feed Amazon > Feed Document Id | New field. |

Amazon returns the resultFeedDocumentId value when the feed moves into the DONE state.

We should check the value of the processingStatus attribute.

If processing status is IN_QUEUE or IN_PROGRESS, feed processing is not yet complete. Retry the getFeed operation until processingStatus reaches one of the following terminal states: DONE, CANCELLED, or FATAL.

If processing status is DONE, feed processing is complete and we should proceed to step 5.

If processing status is CANCELLED, the feed was cancelled before it started processing. If we want to submit the feed again, we should start again with step 1. Meanwhile we set all products in the feed on error with the relevant error message. If the feed is for orders we still store the error message.

If processing status is FATAL, the feed was aborted due to a fatal error. Some, none, or all of the operations within the feed might have completed successfully. In some (but not all) cases Amazon generates a feed processing report. If Amazon generates a report, it could be in a different format from a feed processing report for a successfully completed feed. In rare cases Amazon might abort a feed for reasons unrelated to the feed. If you can find no errors in the feed to correct, try submitting the feed again. In order to handle this in the most correct way we will have to check once we have “FATAL“ status go through step 5, 6 and 7 but if we do not receive any result document id we change the status on “CANCELLED“ and again set all objects on error with the relevant error message.

Note: The getFeed operation only serves information for feed requests that were created within the last 90 days.

Step 5: Get information for retrieving the feed processing report

The feed processing report indicates which records in the feed that you submitted were successful and which records generated errors. In this step you get a presigned URL for downloading the feed processing report as well as the information required to decrypt the document's contents.

API Call: GET /feeds/2021-06-30/documents/{feedDocumentId}

Docs: Feeds API v2021-06-30 reference (amazon.com)

Returns the information required for retrieving a feed document's contents. This includes a presigned URL for the feed document as well as the information required to decrypt the document's contents.

Example call:

GET https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/documents/amzn1.tortuga.3.ed4cd0d8-447b-4c22-96b5-52da8ace1207.T3YUVYPGKE9BMY

Parameters:

Example response:

{
  "feedDocumentId":"amzn1.tortuga.3.ed4cd0d8-447b-4c22-96b5-52da8ace1207.T3YUVYPGKE9BMY",
  "url":"https://tortuga-prod-na.s3.amazonaws.com/%2FNinetyDays/amzn1.tortuga.3.920614b0-fc4c-4393-b0d9-fff175300000.T29XK4YL08B2VM?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200919T035824Z&X-Amz-SignedHeaders=<headers>&X-Amz-Expires=300&X-Amz-Credential=<credential>&X-Amz-Signature=<signature>",
  "encryptionDetails":
  {
    "standard":"AES",
    "initializationVector":"kF3bZt0FSv6JQEimfEJD8g==",
    "key":"5EZo/P06OGF0UAy8QuOnMIaQbkAvYBru6EGsFvK8wJ2="
  }
}

Example error response :

{
  "header": {
    "sellerId": "AY83AIQ8M876Q",
    "version": "2.0",
    "feedId": "242286020136"
  },
  "issues": [
    {
      "messageId": 2,
      "code": "4002008",
      "severity": "ERROR",
      "message": "The provided message did not meet the schema validation requirements for a feed message."
    },
    {
      "messageId": 3,
      "code": "4002008",
      "severity": "ERROR",
      "message": "The provided message did not meet the schema validation requirements for a feed message."
    }
  ],
  "summary": {
    "errors": 2,
    "warnings": 0,
    "messagesProcessed": 2,
    "messagesAccepted": 0,
    "messagesInvalid": 2
  }
}"

Mapping:

We should store the initializationVector, key, and url values to proceed to step 6;

Step 6 - Download and decrypt the feed processing report

You can download and decrypt the feed processing report using the information returned in the previous step.

• The key, initializationVector, url, and optional compressionAlgorithm values from the previous step are arguments for the key, initializationVector, url, and compressionAlgorithm parameters of the downloadAndDecrypt method of the DownloadExample class.

Step 7 - Check the feed processing report for errors

Check the feed processing report for errors generated during processing. If there are no errors, the feed submission is complete. If there are errors, correct them and submit the corrected feed, starting at step 1 until we receive successful complete.

To be checked:

Feed Types

Additions

In cases where we are receiving no expected feed statuses we will need to handle this internally. In this edge case we will need to set the Marketplace Feed > Status = ‘completed', then we will update the Marketplace Feed > External Status with the value we receive from the response. Also we will have to update all feed objects status on error with error message - “Unexpected status received for feed id - {Marketplace feed > id}“ Once the feed is sent successfully to Amazon we need to keep all feed object as with status = 'Sent’ and when we read the actual response we update only the objects with “Sent“ status. If someone manually changed the status we wont update it with the response.

For Amazon we have the same logic as on eBay we have Error and Warnings in get feed result file. Error means that the feed has been processed but the update was not successful Warning means that the feed has been processed there is warning but sill the update is successful.

Here is a sample payload:

Sample.txt

There are 4 warning which we need to treat as success and 0 errors.

Limits