Amazon SP API - Order management

The purpose of this document is give detailed description how order management flow will for Amazon using the SP API.

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

Get Orders

“Get Orders“ call will be split in “Get New Orders“ and “Get Modified Orders“. Get New Orders will look for “Created After“ & “Created Before“, and Modified Orders will look for “Last Updated After“ and “Last Updated Before“.

Note: The Get New Orders call **and Get Order Items calls to be incorporated into one single cron, i.e. to work together because in Hemi we do not want to download the orders without the items. On Amazon the buyer is able to cancel the product within 30min after the order creation thus we keep the order on “pending“ and after the payment is cleared and the grease period expired get modified will double check the order items and if any of them are with cancelled status will be removed from the order. This will be handled with get modified orders cron.

Get New Orders

The first run of the cron will need to check for orders in the last 9 months and after successful run to store a new record in last_date_run table. If we already have a record for the specific cron we will need to overlap 90 minutes from the last_date_run > date_created field.

API Call: GET /orders/v0/orders

Docs: selling-partner-api-docs/ordersV0.md at main · amzn/selling-partner-api-docs · GitHub

All available parameters:

PendingAvailability (This status is available for pre-orders only. The order has been placed, payment has not been authorized, and the release date of the item is in the future.); Pending (The order has been placed but payment has not been authorized); Unshipped (Payment has been authorized and the order is ready for shipment, but no items in the order have been shipped); PartiallyShipped (One or more, but not all, items in the order have been shipped); Shipped (All items in the order have been shipped); InvoiceUnconfirmed (All items in the order have been shipped. The seller has not yet given confirmation to Amazon that the invoice has been shipped to the buyer.); Canceled (The order has been canceled); Unfulfillable (The order cannot be fulfilled. This state applies only to Multi-Channel Fulfillment orders.). | < string > array | | MarketplaceIds**required | A list of MarketplaceId values. Used to select orders that were placed in the specified marketplaces. Max count : 50 | < string > array | | FulfillmentChannelsoptional | A list that indicates how an order was fulfilled. Filters the results by fulfillment channel. Possible values: FBA (Fulfillment by Amazon); SellerFulfilled (Fulfilled by the seller). | < string > array | | PaymentMethodsoptional | A list of payment method values. Used to select orders paid using the specified payment methods. Possible values: COD (Cash on delivery); CVS (Convenience store payment); Other (Any payment method other than COD or CVS). | < string > array | | BuyerEmailoptional | The email address of a buyer. Used to select orders that contain the specified email address. | string | | SellerOrderIdoptional | An order identifier that is specified by the seller. Used to select only the orders that match the order identifier. If SellerOrderId is specified, then FulfillmentChannels, OrderStatuses, PaymentMethod, LastUpdatedAfter, LastUpdatedBefore, and BuyerEmail cannot be specified. | string | | MaxResultsPerPageoptional | A number that indicates the maximum number of orders that can be returned per page. Value must be 1 - 100. Default 100. | integer | | EasyShipShipmentStatusesoptional | A list of EasyShipShipmentStatus values. Used to select Easy Ship orders with statuses that match the specified values. If EasyShipShipmentStatus is specified, only Amazon Easy Ship orders are returned. Possible values: PendingPickUp (Amazon has not yet picked up the package from the seller). LabelCanceled (The seller canceled the pickup). PickedUp (Amazon has picked up the package from the seller). AtOriginFC (The packaged is at the origin fulfillment center). AtDestinationFC (The package is at the destination fulfillment center). OutForDelivery (The package is out for delivery). Damaged (The package was damaged by the carrier). Delivered (The package has been delivered to the buyer). RejectedByBuyer (The package has been rejected by the buyer). Undeliverable (The package cannot be delivered). ReturnedToSeller (The package was not delivered to the buyer and was returned to the seller). ReturningToSeller (The package was not delivered to the buyer and is being returned to the seller). | < string > array | | NextTokenoptional | A string token returned in the response of your previous request. | string | | AmazonOrderIdsoptional | A list of AmazonOrderId values. An AmazonOrderId is an Amazon-defined order identifier, in 3-7-7 format. Max count : 50 | < string > array | | ActualFulfillmentSupplySourceIdoptional | Denotes the recommended sourceId where the order should be fulfilled from. | string | | IsISPUoptional | When true, this order is marked to be picked up from a store rather than delivered. | boolean | | StoreChainStoreId**optional | The store chain store identifier. Linked to a specific store in a store chain. | string |

Example json schema:

"/orders/v0/orders": {
      "get": {
        "tags": [
          "ordersV0"
        ],
        "description": "Returns orders created or updated during the time frame indicated by the specified parameters. You can also apply a range of filtering criteria to narrow the list of orders returned. If NextToken is present, that will be used to retrieve the orders instead of other criteria.\n\n**Usage Plans:**\n\n| Plan type | Rate (requests per second) | Burst |\n| ---- | ---- | ---- |\n|Default| 0.0055 | 20 |\n|Selling partner specific| Variable | Variable |\n\nThe x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation. Rate limits for some selling partners will vary from the default rate and burst shown in the table above. For more information, see \"Usage Plans and Rate Limits\" in the Selling Partner API documentation.",
        "operationId": "getOrders",
        "parameters": [
          {
            "name": "CreatedAfter",
            "in": "query",
            "description": "A date used for selecting orders created after (or at) a specified time. Only orders placed after the specified time are returned. Either the CreatedAfter parameter or the LastUpdatedAfter parameter is required. Both cannot be empty. The date must be in ISO 8601 format.",
            "required": false,
            "type": "string"
          },
          {
            "name": "CreatedBefore",
            "in": "query",
            "description": "A date used for selecting orders created before (or at) a specified time. Only orders placed before the specified time are returned. The date must be in ISO 8601 format.",
            "required": false,
            "type": "string"
          },
          {
            "name": "LastUpdatedAfter",
            "in": "query",
            "description": "A date used for selecting orders that were last updated after (or at) a specified time. An update is defined as any change in order status, including the creation of a new order. Includes updates made by Amazon and by the seller. The date must be in ISO 8601 format.",
            "required": false,
            "type": "string"
          },
          {
            "name": "LastUpdatedBefore",
            "in": "query",
            "description": "A date used for selecting orders that were last updated before (or at) a specified time. An update is defined as any change in order status, including the creation of a new order. Includes updates made by Amazon and by the seller. The date must be in ISO 8601 format.",
            "required": false,
            "type": "string"
          },
          {
            "name": "OrderStatuses",
            "in": "query",
            "description": "A list of OrderStatus values used to filter the results. Possible values: PendingAvailability (This status is available for pre-orders only. The order has been placed, payment has not been authorized, and the release date of the item is in the future.); Pending (The order has been placed but payment has not been authorized); Unshipped (Payment has been authorized and the order is ready for shipment, but no items in the order have been shipped); PartiallyShipped (One or more, but not all, items in the order have been shipped); Shipped (All items in the order have been shipped); InvoiceUnconfirmed (All items in the order have been shipped. The seller has not yet given confirmation to Amazon that the invoice has been shipped to the buyer.); Canceled (The order has been canceled); and Unfulfillable (The order cannot be fulfilled. This state applies only to Multi-Channel Fulfillment orders.).",
            "required": false,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          {
            "name": "MarketplaceIds",
            "in": "query",
            "description": "A list of MarketplaceId values. Used to select orders that were placed in the specified marketplaces.\n\nSee the [Selling Partner API Developer Guide](doc:marketplace-ids) for a complete list of marketplaceId values.",
            "required": true,
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 50
          },
          {
            "name": "FulfillmentChannels",
            "in": "query",
            "description": "A list that indicates how an order was fulfilled. Filters the results by fulfillment channel. Possible values: FBA (Fulfillment by Amazon); SellerFulfilled (Fulfilled by the seller).",
            "required": false,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          {
            "name": "PaymentMethods",
            "in": "query",
            "description": "A list of payment method values. Used to select orders paid using the specified payment methods. Possible values: COD (Cash on delivery); CVS (Convenience store payment); Other (Any payment method other than COD or CVS).",
            "required": false,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          {
            "name": "BuyerEmail",
            "in": "query",
            "description": "The email address of a buyer. Used to select orders that contain the specified email address.",
            "required": false,
            "type": "string"
          },
          {
            "name": "SellerOrderId",
            "in": "query",
            "description": "An order identifier that is specified by the seller. Used to select only the orders that match the order identifier. If SellerOrderId is specified, then FulfillmentChannels, OrderStatuses, PaymentMethod, LastUpdatedAfter, LastUpdatedBefore, and BuyerEmail cannot be specified.",
            "required": false,
            "type": "string"
          },
          {
            "name": "MaxResultsPerPage",
            "in": "query",
            "description": "A number that indicates the maximum number of orders that can be returned per page. Value must be 1 - 100. Default 100.",
            "required": false,
            "type": "integer"
          },
          {
            "name": "EasyShipShipmentStatuses",
            "in": "query",
            "description": "A list of EasyShipShipmentStatus values. Used to select Easy Ship orders with statuses that match the specified  values. If EasyShipShipmentStatus is specified, only Amazon Easy Ship orders are returned.Possible values: PendingPickUp (Amazon has not yet picked up the package from the seller). LabelCanceled (The seller canceled the pickup). PickedUp (Amazon has picked up the package from the seller). AtOriginFC (The packaged is at the origin fulfillment center). AtDestinationFC (The package is at the destination fulfillment center). OutForDelivery (The package is out for delivery). Damaged (The package was damaged by the carrier). Delivered (The package has been delivered to the buyer). RejectedByBuyer (The package has been rejected by the buyer). Undeliverable (The package cannot be delivered). ReturnedToSeller (The package was not delivered to the buyer and was returned to the seller). ReturningToSeller (The package was not delivered to the buyer and is being returned to the seller).",
            "required": false,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          {
            "name": "NextToken",
            "in": "query",
            "description": "A string token returned in the response of your previous request.",
            "required": false,
            "type": "string"
          },
          {
            "name": "AmazonOrderIds",
            "in": "query",
            "description": "A list of AmazonOrderId values. An AmazonOrderId is an Amazon-defined order identifier, in 3-7-7 format.",
            "required": false,
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 50
          },
          {
            "name": "ActualFulfillmentSupplySourceId",
            "in": "query",
            "description": "Denotes the recommended sourceId where the order should be fulfilled from.",
            "required": false,
            "type": "string"
          },
          {
            "name": "IsISPU",
            "in": "query",
            "description": "When true, this order is marked to be picked up from a store rather than delivered.",
            "required": false,
            "type": "boolean"
          },
          {
            "name": "StoreChainStoreId",
            "in": "query",
            "description": "The store chain store identifier. Linked to a specific store in a store chain.",
            "required": false,
            "type": "string""
          }

Example Response:

                  "Orders": [
                    {
                      "AmazonOrderId": "902-3159896-1390916",
                      "PurchaseDate": "2017-01-20T19:49:35Z",
                      "LastUpdateDate": "2017-01-20T19:49:35Z",
                      "OrderStatus": "Pending",
                      "FulfillmentChannel": "SellerFulfilled",
                      "NumberOfItemsShipped": 0,
                      "NumberOfItemsUnshipped": 0,
                      "PaymentMethod": "Other",
                      "PaymentMethodDetails": [
                        "CreditCard",
                        "GiftCerificate"
                      ],
                      "MarketplaceId": "ATVPDKIKX0DER",
                      "ShipmentServiceLevelCategory": "Standard",
                      "OrderType": "StandardOrder",
                      "EarliestShipDate": "2017-01-20T19:51:16Z",
                      "LatestShipDate": "2017-01-25T19:49:35Z",
                      "IsBusinessOrder": false,
                       "OrderTotal": {
                       "CurrencyCode": "USD",
                        "Amount": "40.65"
                        },
                      "IsPrime": false,
                      "IsGlobalExpressEnabled": false,
                      "IsPremiumOrder": false,
                      "IsSoldByAB": false,
                      "IsIBA": false,
                      "IsISPU":false,
                      "ShippingAddress": {
                        "Name": "Michigan address",
                        "AddressLine1": "1 Cross St.",
                        "City": "Canton",
                        "StateOrRegion": "MI",
                        "PostalCode": "48817",
                        "CountryCode": "US"
                      },
                      "BuyerInfo": {
                        "BuyerEmail": "user@example.com",
                        "BuyerName": "John Doe",
                        "BuyerTaxInfo": {
                          "CompanyLegalName": "A Company Name"
                        },
                        "PurchaseOrderNumber": "1234567890123"
                      }
                    }
                  ]

Response Mapping:

"StandardOrder"- An order that contains items for which the selling partner currently has inventory in stock; "LongLeadTimeOrder" - An order that contains items that have a long lead time to ship; "Preorder"- An order that contains items with a release date that is in the future; "BackOrder" - An order that contains items that already have been released in the market but are currently out of stock and will be available in the future "SourcingOnDemandOrder" - A Sourcing On Demand order | | Orders > Order Type Hardcode as “Home Delivery” | | | EarliestShipDate | | | The start of the time period within which you have committed to ship the order. In ISO 8601 date time format. Returned only for seller-fulfilled orders. Note: EarliestShipDate might not be returned for orders placed before February 1, 2013. | Orders Amazon > Earliest Ship Date | New Field | | | LatestShipDate | | | The end of the time period within which you have committed to ship the order. In ISO 8601 date time format. Returned only for seller-fulfilled orders. Note: LatestShipDate might not be returned for orders placed before February 1, 2013. | Orders Amazon > Latest Ship Date | | | | IsBusinessOrder | | | When true, the order is an Amazon Business order. An Amazon Business order is an order where the buyer is a Verified Business Buyer. | Orders Amazon > Business Order | | | | OrderTotal | | | | | | | | | Amount | | | Orders > Order Total Amount | Please note if the order total node is missing from the payload we set the Orders > Order Total Amount as 0

Please note if for some reason we have negative amounts by default we store them as “0“ | | | | Currency | | | N/A | | | | IsPrime | | | When true, the order is a seller-fulfilled Amazon Prime order. | Orders Amazon > Prime | | | | IsGlobalExpressEnabled | | | When true, the order is a GlobalExpress order. | Orders Amazon > Is Global Express Enabled | New Field | | | IsPremiumOrder | | | When true, the order has a Premium Shipping Service Level Agreement. For more information about Premium Shipping orders, see "Premium Shipping Options" in the Seller Central Help for your marketplace. | Orders Amazon > Premium | | | | IsSoldByAB | | | When true, the item within this order was bought and re-sold by Amazon Business EU SARL (ABEU). By buying and instantly re-selling your items, ABEU becomes the seller of record, making your inventory available for sale to customers who would not otherwise purchase from a third-party seller. | Orders Amazon > Is Sold By AB | New field | | | IsIBA | | | | Orders Amazon > Is IBA | New field

• isIBA: This a flag denoting whether you want the SKU to be a part of the Invoice by Amazon programme. This field should be set accordingly. ◦ false: If you want the SKU to be opted out of the Invoice by Amazon programme ◦ true: If you want the SKU to be opted in to the Invoice by Amazon programme By default this field is false and if received from Amazon it will be either true or false | | | IsISPU | | | | Order > Order Type | If true we set the Order Type as In-Store Pickup | | | ShippingAddress | | | | | There is a specific handling of Shipping addresses. Please see below fields | | | | Name | | | N/A | | | | | AddressLine1 | | | N/A | | | | | City | | | N/A | | | | | StateOrRegion | | | N/A | | | | | PostalCode | | | N/A | | | | | CountryCode | | | N/A | | | | BuyerInfo | | | | | | | | | BuyerEmail | | The anonymized email address of the buyer | Orders > Buyer mail | | | | | BuyerName | | The name of the buyer | N/A | | | | | BuyerTaxInfo | | Contains the business invoice tax information. | | | | | | | CompanyLegalName | The legal name of the company | Orders > Billing Company Name Orders > Shipping Company Name | | | | | PurchaseOrderNumber | | The purchase order (PO) number entered by the buyer at checkout. Returned only for orders where the buyer entered a PO number at checkout. | N/A | |

For the Orders > Order Subtotal Amount we will need to make the calculations internally as follows Based on the MarketplaceId we will need to identify if the order is US or not. US orders Order > Оrder Subtotal Аmount = OrderTotal - All order item sum of (ShippingPrice +ShippingTax)

Rest orders Order > Оrder Subtotal Аmount = OrderTotal - All order item sum of (ShippingPrice)

Possible error codes & messages:

Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference ID. | | 403 | Indicates access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature. Headers : x-amzn-RequestId (string) : Unique request reference ID. | | 404 | The resource specified does not exist. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference ID. | | 429 | The frequency of requests was greater than allowed. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference ID. | | 500 | An unexpected condition occurred that prevented the server from fulfilling the request. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference ID. | | 503 | Temporary overloading or maintenance of the server. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference ID. |

Get Order Items

API Call: GET /orders/v0/orders/{orderId}/orderItems

Returns detailed order item information for the order indicated by the specified order ID.

Note: When an order is in the Pending state (the order has been placed but payment has not been authorized), the getOrderItems operation does not return information about pricing, taxes, shipping charges, gift status or promotions for the order items in the order. After an order leaves the Pending state (this occurs when payment has been authorized) and enters the Unshipped, Partially Shipped, or Shipped state, the getOrderItems operation returns information about pricing, taxes, shipping charges, gift status and promotions for the order items in the order.

Parameters:

Example json schema:

"/orders/v0/orders/{orderId}/orderItems": {
      "get": {
        "tags": [
          "ordersV0"
        ],
        "description": "Returns detailed order item information for the order indicated by the specified order ID. If NextToken is provided, it's used to retrieve the next page of order items.\n\nNote: When an order is in the Pending state (the order has been placed but payment has not been authorized), the getOrderItems operation does not return information about pricing, taxes, shipping charges, gift status or promotions for the order items in the order. After an order leaves the Pending state (this occurs when payment has been authorized) and enters the Unshipped, Partially Shipped, or Shipped state, the getOrderItems operation returns information about pricing, taxes, shipping charges, gift status and promotions for the order items in the order.\n\n**Usage Plans:**\n\n| Plan type | Rate (requests per second) | Burst |\n| ---- | ---- | ---- |\n|Default| 0.0055 | 20 |\n|Selling partner specific| Variable | Variable |\n\nThe x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation. Rate limits for some selling partners will vary from the default rate and burst shown in the table above. For more information, see \"Usage Plans and Rate Limits\" in the Selling Partner API documentation.",
        "operationId": "getOrderItems",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "description": "An Amazon-defined order identifier, in 3-7-7 format.",
            "required": true,
            "type": "string"
          },
          {
            "name": "NextToken",
            "in": "query",
            "description": "A string token returned in the response of your previous request.",
            "required": false,
            "type": "string"
          }
        ],

Example response:

                  "OrderItems": [
                    {
                      "ASIN": "BT0093TELA",
                      "OrderItemId": "68828574383266",
                      "SellerSKU": "CBA_OTF_1",
                      "Title": "Example item name",
                      "QuantityOrdered": 1,
                      "QShipped": 1,
                      "PointsGranted": {
                        "PointsNumber": 10,
                        "PointsMonetaryValue": {
                          "CurrencyCode": "JPY",
                          "Amount": "10.00"
                        },
                        "ItemTax":{
            "CurrencyCode":"USD",
            "Amount":"2.97"
         }
                      },
                      "ItemPrice": {
                        "CurrencyCode": "JPY",
                        "Amount": "25.99"
                      },
                      "ShippingPrice": {
                        "CurrencyCode": "JPY",
                        "Amount": "1.26"
                      },
                      "ScheduledDeliveryEndDate": "2013-09-09T01:30:00Z",
                      "ScheduledDeliveryStartDate": "2013-09-07T02:00:00Z",
                      "CODFee": {
                        "CurrencyCode": "JPY",
                        "Amount": "10.00"
                      },
                      "CODFeeDiscount": {
                        "CurrencyCode": "JPY",
                        "Amount": "1.00"
                      },
                      "PriceDesignation": "BusinessPrice",
                      "IossNumber":"GB12351661",
                        "StoreChainStoreId":"ISP1351",
                      "BuyerInfo": {
                        "BuyerCustomizedInfo": {
                          "CustomizedURL": "https://zme-caps.amazon.com/t/bR6qHkzSOxuB/J8nbWhze0Bd3DkajkOdY-XQbWkFralegp2sr_QZiKEE/1"
                        },

                        "GiftMessageText": "For you!",
                        "GiftWrapPrice": {
                          "CurrencyCode": "GBP",
                          "Amount": "41.99"
                        },
                        "GiftWrapLevel": "Classic"
                      }
                    },
                    "PromotionDiscount": {
                    "CurrencyCode": "USD",
                    "Amount": "2.00"
                },
                      "BuyerRequestedCancel": {
                        "IsBuyerRequestedCancel": true,
                        "BuyerCancelReason": "Found cheaper somewhere else."
                      }
                    },
                    {
                      "ASIN": "BCTU1104UEFB",
                      "OrderItemId": "79039765272157",
                      "SellerSKU": "CBA_OTF_5",
                      "Title": "Example item name",
                      "QuantityOrdered": 2,
                      "ItemPrice": {
                        "CurrencyCode": "JPY",
                        "Amount": "17.95"
                      },
                      "PromotionIds": [
                        "FREESHIP"
                      ],
                      "ConditionId": "Used",
                      "ConditionSubtypeId": "Mint",
                      "ConditionNote": "Example ConditionNote",
                      "PriceDesignation": "BusinessPrice",
                      "IossNumber":"GB12351661",
                        "StoreChainStoreId":"ISP1351",
                      "BuyerInfo": {
                        "BuyerCustomizedInfo": {
                          "CustomizedURL": "https://zme-caps.amazon.com/t/bR6qHkzSOxuB/J8nbWhze0Bd3DkajkOdY-XQbWkFralegp2sr_QZiKEE/1"
                        },

                        "GiftMessageText": "For you!",
                        "GiftWrapPrice": {
                          "CurrencyCode": "JPY",
                          "Amount": "1.99"
                        },
                        "GiftWrapLevel": "Classic"
                      },
                      "BuyerRequestedCancel": {
                        "IsBuyerRequestedCancel": true,
                        "BuyerCancelReason": "Found cheaper somewhere else."
                      }
                    }

Mapping:

<v2.9> AND Product In Order > Sales Tax Percent </v2.9>

<v2.9> AND Orders > Total Shipping Sales Tax </v2.9> | | | | ItemPrice | | | The selling price of the order item. Note that an order item is an item and a quantity. This means that the value of ItemPrice is equal to the selling price of the item multiplied by the quantity ordered. Note that ItemPrice excludes ShippingPrice and GiftWrapPrice. | | | | | | CurrencyCode | | The three-digit currency code. In ISO 4217 format | Orders > Order Currency | | | | | Amount | | The currency amount | Order Item > Item Price | Please note the amount is multiplied by the quantity and we need to divide it if more than 1 qty . Also we need to deduct any discounts if applicable in PromotionDiscount node | | | ShippingPrice | | | The shipping price of the item | | | | | | CurrencyCode | | The three-digit currency code. In ISO 4217 format | N/A | | | | | Amount | | The currency amount | Order item > Item Shipping Cost | | | | ScheduledDeliveryEndDate | | | The end date of the scheduled delivery window in the time zone of the order destination. In ISO 8601 date time format. | N/A | | | | ScheduledDeliveryStartDate | | | The start date of the scheduled delivery window in the time zone of the order destination. In ISO 8601 date time format. | N/A | | | | CODFee | | | The fee charged for COD service | | | | | | CurrencyCode | | The three-digit currency code. In ISO 4217 format | N/A | | | | | Amount | | The currency amount | Order Item Amazon > COD fee | New field | | | PriceDesignation | | | Indicates that the selling price is a special price that is available only for Amazon Business orders. Possible values: BusinessPrice - A special price that is available only for Amazon Business orders. | N/A | | | | IossNumber | | | | Order Item Amazon > IOSS | (new field) | | | StoreChainStoreId | | | | Order Item Amazon > Pickup Store ID | (new field) | | | BuyerInfo | | | A single item's buyer information. | | | | | | BuyerCustomizedInfo | | Buyer information for custom orders from the Amazon Custom program | N/A | | | | | | CustomizedURL | The location of a zip file containing Amazon Custom data | N/A | | | | | GiftMessageText | | A gift message provided by the buyer | Order Item Amazon > Gift Message | | | | | GiftWrapPrice | | The gift wrap price of the item | | | | | | | CurrencyCode | The three-digit currency code. In ISO 4217 format | N/A | | | | | | Amount | The currency amount | Order Item Amazon > Gift Wrap Price | | | | | GiftWrapLevel | | The gift wrap level specified by the buyer. | Order Item Amazon > Gift Wrap Level | | | | PromotionIds | | | A list of promotion identifiers provided by the seller when the promotions were created. | Order Item Amazon > Promotion IDs | New Field. If more than one ID separate them with comma “ , “ | | | ConditionId | | | The condition of the item. Possible values: New, Used, Collectible, Refurbished, Preorder, Club. | N/A | | | | ConditionSubtypeId | | | The sub condition of the item. Possible values: New, Mint, Very Good, Good, Acceptable, Poor, Club, OEM, Warranty, Refurbished Warranty, Refurbished, Open Box, Any, Other. | N/A | | | | ConditionNote | | | The condition of the item as described by the seller. | N/A | | | | PriceDesignation | | | | N/A | | | | PromotionDiscount | | | | | | | | | Amount | | | Order Item > Discount Amount | We need to calculate all order item discounts and store them also in Orders > Discount Value | | | | Currency | | | N/A | | | | BuyerRequestedCancel | | | | | | | | | IsBuyerRequestedCancel | | Indicates if there is cancellation request | | If this is set as TRUE we need to store a new claim for the order | | | | BuyerCancelReason | | The reason of the cancellation request | | |

Storing a Claim for Amazon

In Account Amazon table we will need to add additional option which will be Claim Action Default which will work as a default action if we would like to automatically accept or reject all claims for the specific account. Otherwise we will have to specify the desired action and based on the selection we will have two cases:

1Accept

We will have to create automatically refund row with reason “BuyerCanceled“ and based on the Order Claim Row > Order Item Line ID we get the Ids and the correct amounts. Then the refund row will be sent with the cancellation cron.

2 Reject

We do no nothing just set the status as “completed”

There are no additional request which we can do for acceptance or rejection thus this will be handled internally.

Possible error codes & messages:

Headers : x-amzn-RequestId (string) : Unique request reference ID. | | 404 | The resource specified does not exist. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference ID. | | 429 | The frequency of requests was greater than allowed. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference ID. | | 500 | An unexpected condition occurred that prevented the server from fulfilling the request. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference ID. | | 503 | Temporary overloading or maintenance of the server. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference ID. |

API call: GET /orders/v0/orders/{orderId}/address In order to get the full shipping address we will have to call each order separately. We will have to specify only the Amazon order ID and call each order one by one. Please note if the order status is still “pending“ we wont receive any shipping details in the response thus we have to wait the order status to be updated from Amazon. Also if we have a “cancelled“ status we wont receive any shipping details in the response but in this case we wont set the order as “incomplete“ because “cancelled“ is final status, and we want to store the order as “cancelled“.

Response Example:

{
    "payload": {
        "AmazonOrderId": "203-2155390-4461151",
        "ShippingAddress": {
            "StateOrRegion": "Northants",
            "AddressLine1": "Stamford Road",
            "Phone": "07769 908582",
            "PostalCode": "NN17 3BA",
            "City": "FINESHADE",
            "CountryCode": "GB",
            "AddressType": "Commercial",
            "Name": "Fineshade Priory"
        }
    }
}

Mapping:

Orders > Shipping Street 2 Orders > Billing Street 2 | | | | Phone | Orders > Shipping Phone Orders > Billing Phone | | | | | PostalCode | Orders > Shipping Postal Code Orders > Billing Postal Code | | | | | City | Orders > Shipping City Orders > Billing City Name | | | | | CountryCode | Orders > Shipping Country Code Orders > Billing Country Code | | | | | AddressType | N/A | | | | | Name | Orders > Billing Name Orders > Shipping Buyer Name | | | | | Country Name | | Based on the CountryCode we will need to populate the correct country name |

We want to obtain the whole order information before we store them in Hemi so once we get the order, the order item and finally the full shipping/billing address only then we store the order details in Hemi. Please note some of the fields in the response will be missing if not populated from the buyer also get modified order must not delete any details from the order because the address will be received only with this request. If for some reason we are not able to obtain the address for “Unshipped“ orders we set the Orders > Status = Incomplete

Get Modified Orders

We need to be able to update the orders according to their status on the Marketplace. The first run of the cron will need to check the order last updated in the last 30 days. Then we just check the last_date_run > date_create overlap 90mins. Every order we receive will need to be check and enriched like if we have not added the shipping, billing details, the taxes, payment rows, debundler etc. need to make sure get modified orders take cares of this. On Amazon the buyer is able to cancel the product within 30min after the order creation thus we keep the order on “pending“ and after the payment is cleared and the grease period expired get modified will double check the order items and if any of them are with cancelled status will be removed from the order.

Get Modified orders will ONLY update existing orders in Hemi, not create new orders.

Note: Please see below the details for adding a payment row.

Basically we will have two main cases:

1 Every time we download new order will be with pending status until the payment is cleared, and then get modified order will have to update the status and add the payment row.

2 We have order which is cancelled or shipped directly on Amazon so we will have to update the status as well as add the refund row if the order is cancelled. Partial refund cases are also possible

Once we successfully download an order with status different from “Pending“ and its items we need to add a payment row as well with the following details:

Order Statuses

Into the table, you can find Amazon order statuses, mapped to Hemi internal statuses.

Please note these statuses need to be reflected on the order items as well if there is cancellation, refund, shipping update or any other status change. In order to keep the status consistency across the whole order we will have to not only update Orders > Marketplace status but also all other Order Item >Status, Order Shipment > Courier, Orders > Tracking Num, Refund rows etc. Based on the status we received from the Marketplace. For the Order Item > Status we are using Amazon status.

Order Cancellation

Feed Type: POST_ORDER_ACKNOWLEDGEMENT_DATA

Docs: Feed Type Values (amazon.com)

The cancellation cron will pick refund for orders which are with status “Ready for shipping“ only. If an order is “Cancelled “or “Shipped” we are not able to cancel it. If we have “Ready for shipping“ order with payment row with type=refund on pending. we process the request to Amazon and only full refund are allowed pre-shipping. <v2.6> Which means we are specifying only the order item id and the quantity and Amazon is refunding all Shipping Costs and Amounts associated with that order item. If we have a refund with two refund rows one “item” type and one “shipping” type for the same order item id we want to push only one node in the request because the order item id has only one Product in Order > Item Order Line ID</v2.6>

Example XSD scheme:

<xsd:include schemaLocation="amzn-base.xsd"/>
    <xsd:element name="OrderAcknowledgement">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element ref="AmazonOrderID"/>
                <xsd:element ref="MerchantOrderID" minOccurs="0"/>
                <xsd:element name="StatusCode">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:enumeration value="Success"/>
                            <xsd:enumeration value="Failure"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:element>
                <xsd:element name="Item" minOccurs="0" maxOccurs="unbounded">
                    <xsd:complexType>
                        <xsd:sequence>
                            <xsd:element ref="AmazonOrderItemCode"/>
                            <xsd:element ref="MerchantOrderItemID" minOccurs="0"/>
                            <xsd:element name="CancelReason" minOccurs="0">
                                <xsd:simpleType>
                                    <xsd:restriction base="xsd:string">
                                        <xsd:enumeration value="NoInventory"/>
                                        <xsd:enumeration value="ShippingAddressUndeliverable"/>
                                        <xsd:enumeration value="CustomerExchange"/>
                                        <xsd:enumeration value="BuyerCanceled"/>
                                        <xsd:enumeration value="GeneralAdjustment"/>
                                        <xsd:enumeration value="CarrierCreditDecision"/>
                                        <xsd:enumeration value="RiskAssessmentInformationNotValid"/>
                                        <xsd:enumeration value="CarrierCoverageFailure"/>
                                        <xsd:enumeration value="CustomerReturn"/>
                                        <xsd:enumeration value="MerchandiseNotReceived"/>
                                        <xsd:enumeration value="CannotVerifyInformation"/>
                                        <xsd:enumeration value="PricingError"/>
                                        <xsd:enumeration value="RejectOrder"/>
                                        <xsd:enumeration value="WeatherDelay"/>
                                    </xsd:restriction>
                                </xsd:simpleType>
                            </xsd:element>
                             <xsd:element name="Quantity" type="xsd:positiveInteger" minOccurs="0"/>
                        </xsd:sequence>
                    </xsd:complexType>
                </xsd:element>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
</xsd:schema>

If the cancellation request is successful we will have to: After successful request we mark the payment row with type =refund status as “sent“ and based on the response we will have to:

1 Full refund we mark the payment status with type=refund as “Completed“ we update our tool status as “Cancelled“

If the order cancellation request is unsuccessful we mark the payment row status with type=refund as “Error” and store the relevant error message in Order Errors table Also if the refund row is not full refund we return an error.

Please note this need to be processed using our refund processor which means we must make sure all relevant fields are updated accordingly like orders>refunded so far sum , order item > refunded amount, order item > payment statuses etc.

Order Adjustments

The purpose of this section is to describe the process of triggering, mapping and sending a refund after shipment has already been done. (Issues a refund (adjustment) for an order.) Which means the adjustment cron must pick orders only with “Shipped“ or “Partially Shipped“ status and payment row with type=refund on pending.

Feed Type : POST_PAYMENT_ADJUSTMENT_DATA

Docs: Feed Type Values (amazon.com)

Example XSD scheme:

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xsd:include schemaLocation="amzn-base.xsd"/>
<xsd:element name="OrderAdjustment">
        <xsd:complexType>
            <xsd:sequence>

                <xsd:choice>
                    <xsd:element ref="AmazonOrderID"/>
                    <xsd:element ref="MerchantOrderID"/>
                </xsd:choice>

                <xsd:element name="ActionType" minOccurs="0" maxOccurs="1">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:enumeration value="Refund"/>
                            <xsd:enumeration value="Cancel"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:element>

                <xsd:element name="CODCollectionMethod" minOccurs="0">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:enumeration value="DirectPayment"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:element>

                <xsd:element name="AdjustedItem" maxOccurs="unbounded">
                    <xsd:complexType>
                        <xsd:sequence>

                            <xsd:choice>
                                <xsd:element ref="AmazonOrderItemCode"/>
                                <xsd:element ref="MerchantOrderItemID"/>
                            </xsd:choice>

                            <xsd:element name="MerchantAdjustmentItemID" type="StringNotNull"
                                minOccurs="0"/>

                            <xsd:element name="AdjustmentReason">
                                <xsd:simpleType>
                                    <xsd:restriction base="xsd:string">
                                        <xsd:enumeration value="NoInventory"/>
                                        <xsd:enumeration value="CustomerReturn"/>
                                        <xsd:enumeration value="GeneralAdjustment"/>
                                        <xsd:enumeration value="CouldNotShip"/>
                                        <xsd:enumeration value="DifferentItem"/>
                                        <xsd:enumeration value="Abandoned"/>
                                        <xsd:enumeration value="CustomerCancel"/>
                                        <xsd:enumeration value="PriceError"/>
                                        <xsd:enumeration value="ProductOutofStock"/>
                                        <xsd:enumeration value="CustomerAddressIncorrect"/>
                                        <xsd:enumeration value="Exchange"/>
                                        <xsd:enumeration value="Other"/>
                                        <xsd:enumeration value="CarrierCreditDecision"/>
                                        <xsd:enumeration value="RiskAssessmentInformationNotValid"/>
                                        <xsd:enumeration value="CarrierCoverageFailure"/>
                                        <xsd:enumeration value="TransactionRecord"/>
                                        <xsd:enumeration value="Undeliverable"/>
                                        <xsd:enumeration value="RefusedDelivery"/>
                                    </xsd:restriction>
                                </xsd:simpleType>
                            </xsd:element>

                            <xsd:element name="ItemPriceAdjustments" type="AdjustmentBuyerPrice"
                                minOccurs="0"/>

                            <xsd:element name="PromotionAdjustments" minOccurs="0"
                                maxOccurs="unbounded">
                                <xsd:complexType>
                                    <xsd:sequence>

                                        <xsd:element ref="PromotionClaimCode" minOccurs="0"/>
                                        <xsd:element ref="MerchantPromotionID" minOccurs="0"/>

                                        <xsd:element name="Component" maxOccurs="unbounded">
                                            <xsd:complexType>
                                                <xsd:sequence>

                                                  <xsd:element name="Type"
                                                  type="PromotionApplicationType"/>
                                                  <xsd:element name="Amount"
                                                  type="AdjustmentCurrencyAmount"/>

                                                </xsd:sequence>
                                            </xsd:complexType>
                                        </xsd:element>

                                    </xsd:sequence>
                                </xsd:complexType>
                            </xsd:element>
                            <xsd:element name="DirectPaymentAdjustments"
                                type="AdjustmentDirectPaymentType" minOccurs="0"/>
                            <xsd:element name="QuantityCancelled" type="xsd:positiveInteger"
                                minOccurs="0"/>
                            <xsd:element name="Quantity" type="xsd:positiveInteger" minOccurs="0"/>
                        </xsd:sequence>
                    </xsd:complexType>
                </xsd:element>

            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>

    <xsd:complexType name="AdjustmentBuyerPrice">
        <xsd:sequence>
            <xsd:element name="Component" maxOccurs="unbounded">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="Type">
                            <xsd:simpleType>
                                <xsd:restriction base="xsd:string">
                                    <xsd:enumeration value="Principal"/>
                                    <xsd:enumeration value="Shipping"/>
                                    <xsd:enumeration value="Tax"/>
                                    <xsd:enumeration value="ShippingTax"/>
                                    <xsd:enumeration value="RestockingFee"/>
                                    <xsd:enumeration value="RestockingFeeTax"/>
                                    <xsd:enumeration value="GiftWrap"/>
                                    <xsd:enumeration value="GiftWrapTax"/>
                                    <xsd:enumeration value="Surcharge"/>
                                    <xsd:enumeration value="ReturnShipping"/>
                                    <xsd:enumeration value="Goodwill"/>
                                    <xsd:enumeration value="ExportCharge"/>
                                    <xsd:enumeration value="COD"/>
                                    <xsd:enumeration value="CODTax"/>
                                    <xsd:enumeration value="Other"/>
                                    <xsd:enumeration value="FreeReplacementReturnShipping"/>
                                </xsd:restriction>
                            </xsd:simpleType>
                        </xsd:element>
                        <xsd:element name="Amount" type="AdjustmentCurrencyAmount"/>
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>
        </xsd:sequence>
    </xsd:complexType>

    <xsd:complexType name="AdjustmentCurrencyAmount">
        <xsd:simpleContent>
            <xsd:extension base="BaseCurrencyAmount">
                <xsd:attribute name="currency" type="BaseCurrencyCode" use="optional"/>
            </xsd:extension>
        </xsd:simpleContent>
    </xsd:complexType>

    <xsd:complexType name="AdjustmentDirectPaymentType">
        <xsd:sequence>
            <xsd:element name="Component" maxOccurs="unbounded">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="Type" type="xsd:string"/>
                        <xsd:element name="Amount" type="AdjustmentCurrencyAmount"/>
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>
        </xsd:sequence>
    </xsd:complexType>

</xsd:schema>

Mapping:

Principal Shipping Tax ShippingTax RestockingFee RestockingFeeTax GiftWrap GiftWrapTax Surcharge ReturnShipping Goodwill ExportCharge COD CODTax Other FreeReplacementReturnShipping | | Order Refund Row > Type

US: Principal - Product In Order > Item Price Shipping - Product In Order > Item Shipping Cost Tax - Product In Order > Item Sales Tax Price ShippingTax - Product In Order > Item Shipping Cost Sales Tax

Rest: Principal - Product In Order > Item Price - Product In Order > Vat Item Price Shipping - Product In Order > Item Shipping Cost - Product In Order > Vat Item Shipping Cost Tax - Product In Order > Vat Item Price ShippingTax - Product In Order > Vat Item Shipping Cost | Currently used: Principal = Item Shipping Tax ShippingTax At the moment with our current Amazon integration we are using only these 4 types when refunding orders. Principal is when we are refunding items Tax is when we are refunding the item tax Shipping is when we refund the shipping cost ShippingTax is when we are refunding the shipping tax Based on these 4 types we need to incorporate logic and trace if the refund row is for the item or for the shipping or for both and push the relevant types to Amazon.

Please note for all Amazons apart from the US the tax is incorporated in the Item Price. So If we have order with item price 20 and item tax 5. We need to refund in the payload: Principal = 15 Tax = 5 For Amazon US we just get the item price. Need to think how to handle the rest: GiftWrap GiftWrapTax With the current structure it is difficult to incorporate all of this without any major changes. Thus we will keep the same logic as we currently have with the only difference that if we have Gift Wrap and Gift Wrap Tax when doing full refund with populated Order Item Amazon > Gift Wrap Price we need to include this in the payload. | | | | | Amount | | | Order Refund Row > Amount | | | | PromotionAdjustments | | | | | N/A | | | | | PromotionClaimCode | | | | N/A | | | | | MerchantPromotionID | | | | N/A | | | | | Component | | | | | | | | | | Type | | | N/A | | | | | | Amount | | | N/A | | | | DirectPaymentAdjustments | | | | | N/A | | | | QuantityCancelled | | | | | N/A | | | | Quantity | | | | | N/A | | | AdjustmentBuyerPrice | | | | | | | | | | Component | | | | | | | | | Type | | | | | | | | АdjustmentCurrencyAmount | | | | | | N/A | | | | BaseCurrencyAmount | | | | | N/A | | | | | currency | | | | N/A | | | AdjustmentDirectPaymentType | | | | | | N/A | | | | Component | | | | | | | | | | Type | | | | N/A | | | | | Amount | | | | N/A | |

If the order adjustment request is successful we will have two cases: After successful request we mark the payment row with type =refund status as “sent“ and based on the response we will have to:

1 Full refund we mark the payment row status with type=refund as “Completed“ we update our tool status as “Cancelled“

2 Partial refund we mark the payment row status with type=refund as “Completed“ we DO NOT update our tool status if the order is not fully refunded.

If the order adjustment request is unsuccessful we mark the payment row status with type=refund as “Error” and store the relevant error message in Order Errors table

Please note this need to be processed using our refund processor which means we must make sure all relevant fields are updated accordingly like orders>refunded so far sum , order item > refunded amount, order item > payment statuses etc.

Order Fulfillment Feed

Feed Type : POST_ORDER_FULFILLMENT_DATA

Docs: Feed Type Values (amazon.com)

Directs Amazon to charge the buyer, credit your seller account, and notify the buyer that the order is on the way. To ship the order on Amazon we need to have tool status as “Ready for shipping“ or “Partially Shipped“ and Order Shipment > Status = “Pending”

We want to follow our standard procedure of Shipments as described here: https://wearepentagon.atlassian.net/wiki/spaces/HEMI/pages/2075820405/Order+management+general+requirements#Ship We want to improve the current flow and have a general marketplace structure. Thus we need to think of better way of taking care of shipping services because our current logic and flow is based on the label generation process, which is not completely correct.

Example XSD scheme:

<xsd:include schemaLocation="amzn-base.xsd"/>

    <xsd:element name="OrderFulfillment">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:choice>
                    <xsd:element ref="AmazonOrderID"/>
                    <xsd:element ref="MerchantOrderID"/>
                </xsd:choice>
                <xsd:element name="MerchantFulfillmentID" type="IDNumber" minOccurs="0"/>
                <xsd:element name="FulfillmentDate" type="xsd:dateTime"/>
                <xsd:element name="FulfillmentData" minOccurs="0">
                    <xsd:complexType>
                        <xsd:sequence>
                            <xsd:element ref="CarrierCode" minOccurs="0"/>
                            <xsd:element name="CarrierName" type="String" minOccurs="0"/>
                            <xsd:element name="ShippingMethod" type="String" minOccurs="0"/>
                            <xsd:element name="ShipperTrackingNumber" type="String" minOccurs="0"/>
                        </xsd:sequence>
                    </xsd:complexType>
                </xsd:element>

                <xsd:element name="CODCollectionMethod" minOccurs="0">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:enumeration value="DirectPayment"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:element>

                <xsd:element name="Item" minOccurs="0" maxOccurs="unbounded">
                    <xsd:complexType>
                        <xsd:sequence>
                            <xsd:choice>
                                <xsd:element ref="AmazonOrderItemCode"/>
                                <xsd:element ref="MerchantOrderItemID"/>
                            </xsd:choice>
                            <xsd:element name="MerchantFulfillmentItemID" type="IDNumber"
                                minOccurs="0"/>
                            <xsd:element name="Quantity" type="xsd:positiveInteger" minOccurs="0"/>
                             <xsd:element name="TransparencyCode" type="xsd:string" minOccurs="0" maxOccurs="10"/>
                        </xsd:sequence>
                    </xsd:complexType>
                </xsd:element>
                <xsd:element name="ShipFromAddress" type="AddressType" minOccurs="0" />

            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>

</xsd:schema>

Mapping:

else we send FulfillmentDate = NOW() -1 hour

If for some reason we have Orders Amazon >Latest Ship Date empty we push NOW() -1 hour | The dateTime is specified in the following form "YYYY-MM-DDThh:mm:ss" where: • YYYY indicates the year • MM indicates the month • DD indicates the day • T indicates the start of the required time section • hh indicates the hour • mm indicates the minute • ss indicates the second | | | FulfillmentData | | | N/A | | | | | CarrierCode | | N/A | | | | | CarrierName | | Order Shipment > Carrier OR Amazon Service Mapping > Amazon Courrier | Based on the mapping we might also use the Amazon Service Mapping > Amazon Courrier | | | | ShippingMethod | | Order Shipment > Service | New Field | | | | ShipperTrackingNumber | | Order Shipment > Tracking | | | | CODCollectionMethod | | | N/A | DirectPayment | | | Item | | | | | | | | AmazonOrderItemCode | | Product in Order > Item Order Line ID | Based on the Order Shipment Rows > Order Item ID we map and get the relevant details. To be checked if the same as OrderItemId | | | | MerchantFulfillmentItem | | TBD | To be checked if this is Item Transaction ID? | | | | Quantity | | Order Shipment Rows > Quantity | We need to make sure we are validating this quantity and we actually can ship the whole quantity. In order to do this we will have to check our Order Item > Fulfilment Status as described here. Order management general requirements | | | | TransparencyCode | | N/A | | | | ShipFromAddress | | | N/A | |

If the order is shipped successfully we set Order Shipment > Status = “Sent” and we wait for the feed to be processed and based on the result we mark the order as “Shipped“ or “Partially Shipped“ and Order Shipment > Status = “Completed” Because Amazon requires with the shipping information to provide the service we will introduce a new table “Amazon Service Mapping“ which will be a slave table of “Courier”. There we will store the mapping for each carrier and once we receive the shipping update from the client we can map the actual Order Shipment > Courier and the Orders > Shipping Service and get the correct Order Shipment > Service.

The table will look like:

Once we have received the details we will map the Order Shipment > Courier with Courier > Name then Orders > Shipping Service with Amazon Service Mapping > Amazon Service and push the actual Amazon Service Mapping > Courier Service Please note we should have a default option which will work as follows: if we leave the Amazon Service empty and our mapping does not meet any of the set rules we treat the empty Amazon Service as a default option.

This should be triggered with the shipping cron and after successful result to store the shipping service used based on the mapping in Order Shipment > Service

In cases where there is no courier added or to be matched we return error in the order. Since Amazon allows to ship an order without carrier and tracking we need to remove the validations and make the Tracking number and Courier compulsory. However if we have populated Orders > Shipping Courier we need to map it accordingly with our courier list.

We are using the Amazon Shipping Service in order to map the correct courier service however we will need to extend this mapping and include the carrier as well.

For example if we have a match of the Order Shipments > Courier against Courier > Name we will go to the Amazon Shipping Service Mapping for the correct account and get the correct Amazon Shipping Service Mapping > Courier Shipping Service. There we also would like to add “Amazon Courier” field which if populated to be send as the carrier. In this case we will receive carrier name “SEURTRACKETAIR“ which based on the mapping will push “USPS” to Amazon.

Again the carrier will be per service and if we have specified the Courier for the default service to be used as a default carrier. Also if there is no mapped service we will have to return an error.

Invoice Upload

Feed Type : UPLOAD_VAT_INVOICE

Docs: Feed Type Values (amazon.com)

Amazon requires Invoice upload for each of our orders. Using our invoice functionality we generate the actual invoices in Hemi Invoices >Generated file and then we push them to Amazon via feeds containing the actual invoice file url which is generated from Hemi. The Invoice Upload functionality need to work only for Amazon 'ES', 'UK', 'FR', 'DE', 'IT'. For all other Amazon sites we are not uploading invoices. The whole flow is controlled directly in Emails with invoices > Export to where and Emails with invoices > Integration. If we have: Emails with invoices > Export to where = Marketplace Integration Emails with invoices > Integration = Amazon Once we have set the SMTP and Invoice Template, Hemi will start generating invoices for the orders which will be stored in Invoice table. In order to send the actual invoice to Amazon we will need to check if: Invoice > Status = Sent AND Invoice > Sent By Integration = 0 and if the Invoice > Template ID = Email with invoices > Id of the email template. Then we pick the invoices for upload and generate the feed in Marketplace Feeds and the Marketplace Feed Objects > Object ID will be our Invoice > ID. If the invoice is picked and send to Amazon and the feed is still processing we will have Invoice > Sent By Integration = 2. Once the feed is processed successfully and we receive the response we will either have to set Invoice > Sent By Integration = 1 if success or store the error in Order Errors table and set Invoice > Sent By Integration = 3. Please note we push single invoice per feed and we will be generating a lot of feeds and we need to have the priority queue logic and process the Invoice Feeds last. Invoice > Sent By Integration label need to be changed to ““ and ****field type need to be changed to dropdown with the relevant enumerations:

Please note only Invoices that Invoice > ID is in the Feed Objects and Invoice > Sent By Integration = 2.

The invoice upload flow consist of several steps which we need to follow:

1. Call the createFeedDocument operation, specifying the content type for the feed that you are submitting.

   Amazon returns a feedDocumentId value and a URL for uploading the feed contents.

2. Upload your feed document contents to the URL from the previous step.

3. Call the createFeed operation. Use the inputFeedDocumentId parameter to pass in the feedDocumentId value from step 1. Specify the marketplaces that you want the feed to be applied to and any relevant feed options.

   Amazon returns a feedId value.

4. Periodically call getFeed, using the feedId from the previous step which provides information when the feed processing is CANCELLED, DONE or FATAL.

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

5. Call the getFeedDocument operation. Use the feedDocumentId parameter to pass in the resultFeedDocumentId value from the previous step.

   Amazon returns the feedDocumentId value, a URL for downloading the feed processing report, and the compression algorithm.

6. Download the feed processing report from the URL provided from the previous step.

7. Check the feed processing report for errors generated during feed processing. If there are errors, correct them and submit the corrected feed, starting at step 1. If there are no errors, your feed submission was successful.

Create Feed Document

First we create the feed document in order to get the feedDocumentId which we will need to create the actual feed but before that we are uploading the invoice pdf using the URL from the response. At this step we are not storing anything in Hemi. Feed Type : UPLOAD_VAT_INVOICE API Endpoint: POST /feeds/2021-06-30/documentsDocs: https://developer-docs.amazon.com/sp-api/docs/feeds-api-v2021-06-30-reference#post-feeds2021-06-30documents

Sample Request:

{
       "contentType":"application/pdf",
}

Request Mapping:

Sample Response:

{
    "feedDocumentId": "amzn1.tortuga.3.0f043bd3-cd2e-4537-b2a1-1e480f5cc8c4.T9XH32V2SR3MU",
    "url": "https://tortuga-prod-eu.s3-eu-west-1.amazonaws.com/%2FNinetyDays/amzn1.tortuga.3.0f043bd3-cd2e-4537-b2a1-1e480f5cc8c4.T9XH32V2SR3MU?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20220707T064054Z&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Expires=300&X-Amz-Credential=AKIAX2ZVOZFBG22SVBUH%2F20220707%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Signature=3bfcea080cb389a8fb28b7a7defb89f1a30b9a64dfe8cb883d85d6a7140a41ba"
}

Response Mapping:

Right after this step we are calling Create feed however if we receive and error we need to store it in Order Errors table.

Create Feed

Once we successfully upload the invoice with the URL provided from the previous step, we are now ready to create the feed. At this step we are making new record in Marketplace Feeds table

Feed Type : UPLOAD_VAT_INVOICE API Endpoint: POST /feeds/2021-06-30/feedsDocs: https://developer-docs.amazon.com/sp-api/docs/feeds-api-v2021-06-30-reference#post-feeds2021-06-30feeds

Sample Request:

{
    "feedType": "UPLOAD_VAT_INVOICE",
    "marketplaceIds": [
        "A1F83G8C2ARO7P"
    ],
    "inputFeedDocumentId": "amzn1.tortuga.3.5ecad965-2b47-4cce-a0f8-c6acd74c48c0.T4YDR9T5B1U6Z",
    "feedOptions": {
        "metadata:OrderId": "203-4341959-0391509",
        "metadata:InvoiceNumber": "231871"
    }
}

Request Mapping:

Sample Response:

{
"feedId":"1312412312"
    }

Response Mapping:

If we receive an error we need to store it in the log and no new records to be created in Marketplace Feed

Get Feed

In order to check if the feed is “DONE” we need to periodically check the status.

API Endpoint: GET /feeds/2021-06-30/feeds/{feedId}Docs: https://developer-docs.amazon.com/sp-api/docs/feeds-api-v2021-06-30-reference#getfeed

Sample Request:

No Body

Request Mapping:

Sample Response:

{
    "processingEndTime": "2022-07-06T10:29:54+00:00",
    "processingStatus": "DONE",
    "marketplaceIds": [
        "A1F83G8C2ARO7P"
    ],
    "feedId": "1810217019179",
    "feedType": "UPLOAD_VAT_INVOICE",
    "createdTime": "2022-07-06T10:29:24+00:00",
    "processingStartTime": "2022-07-06T10:29:32+00:00",
    "resultFeedDocumentId": "amzn1.tortuga.3.7d3d5af3-fdf3-45cc-980b-93849aaba121.T1UV1RVP4BYJBV"
}

Response Mapping:

If we receive an error we need to store it in the log and no new records to be created in Marketplace Feed. The Marketplace Feed Objects will be the Invoice > ID

Get Feed Document

One we receive status “DONE“ for the feed we can finally get the feed document which will return the actual report with the errors if any. In order to do so we will need to use the resultFeedDocumentId from the Get Feed Response in the previous step.

API Endpoint: GET /feeds/2021-06-30/documents/{feedDocumentId}Docs: https://developer-docs.amazon.com/sp-api/docs/feeds-api-v2021-06-30-reference#getfeeddocument

Sample Request:

No Body

Request Mapping:

Sample Response:

{
    "feedDocumentId": "amzn1.tortuga.3.7d3d5af3-fdf3-45cc-980b-93849aaba121.T1UV1RVP4BYJBV",
    "url": "https://tortuga-prod-eu.s3-eu-west-1.amazonaws.com/%2FNinetyDays/amzn1.tortuga.3.c9e81cfd-3aa3-4b32-beb3-a78d541e4d34.T10LQL6MEJWAGI?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20220707T112243Z&X-Amz-SignedHeaders=host&X-Amz-Expires=300&X-Amz-Credential=AKIAX2ZVOZFBG22SVBUH%2F20220707%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Signature=97266c78332c64601a613728058fdfcbb7e34c75df0fe9728cba6896ffc54e10"
}

From the response once we open the URL we will receive the following structure message:

Feed Processing Summary:
    Number of records processed     1
    Number of records successful        0

original-record-number  sku error-code  error-type  error-message
1       79554   Error   There is already a document with same invoice number

Which is the error report of the feed document. As you can seed we are receiving “DONE“ status for the feed but the actual document is with error. These errors need to be stored in Hemi in Order Errors table.

Prime flow

To fulfill Seller Fulfilled Prime orders

1. Identify Prime orders

   Identify the Prime orders in incoming order reports. Prime orders have the IsPrime element (for XML order reports) or the is-prime column (for flat file order reports) marked as true.

   Do not use the FulfillmentServiceLevel element or the ship-service-level column in order reports to attempt to identify Prime orders.

2. Determine the latest ship date for the Prime orders

   Use the LatestShipDate element (from an XML order report) or the latest-ship-date column (from a flat file order report) to determine the date by which Prime orders need to be shipped. Also we will need to specify the dimensions and the weight.

3. Get shipping service offers

   Call the GetEligibleShippingServices operation to get shipping service offers for the Prime orders identified in Step 1.

   Note:

   • For the ShipDate parameter, use the LatestShipDate value (XML report) or the latest-ship-date value (flat file report) from the order report.
   • Do not specify the MustArriveByDate parameter, as this will unnecessarily limit the number of shipping service offers that are returned.
   • Save the ShippingServiceId value from each shipping service offer that is returned. Use this for subsequent calls to the CreateShipment operation to create shipments for specific shipping service offers. For this step we will have additional table for courier rules on which we will decide which service and carrier to add in the label request. Once we add the label request we set the status on pending and also have to set the relevant Fulfillment status in orders.

4. Create a shipment

   Call the CreateShipment operation for one of the shipping service offers returned in the previous step. Use these parameter values:

   • ShipmentRequestDetails. Use the same values that were included in the call to the GetEligibleShippingServices operation in the previous step.
   • ShippingServiceId. Use the value associated with this shipping service offer.

   Calling the CreateShipment operation:

   • Triggers payment for shipping, which is deducted from the seller’s Amazon seller account.
   • Confirms the shipment. The seller does not have to confirm the shipment by other means. Create shipment basically process the label request and marks the order as shipped. We also get the content from the response which is the actual label and store it in Label Request Documents where also we will have to add additional field to store the ShipmentID

   Important: Save the ShipmentId value returned by the CreateShipment operation to identify the shipment in case the seller wants to print a new label, cancel a shipment, or check shipment status at a later time. Consider saving the item list along with each shipment ID to help the seller identify a shipment at a later time.

Get Eligible Shipping Services

EndPoint : POST /mfn/v0/eligibleShippingServices

Docs: https://developer-docs.amazon.com/sp-api/docs/merchant-fulfillment-api-v0-reference#geteligibleshipmentservicesrequest

Shipment information required for requesting shipping service offers.

Order Item > Length Order Item > Width | | Weight**required | The package weight. | Weight | Order Item > Weight | | MustArriveByDateoptional | The date by which the package must arrive to keep the promise to the customer, in ISO 8601 datetime format. If MustArriveByDate is specified, only shipping service offers that can be delivered by that date are returned. | Timestamp | | | ShipDateoptional | When used in a request, this is the date and time that the seller wants to ship the package. When used in a response, this is the date and time that the package can be shipped by the indicated method. | Timestamp | | | ShippingServiceOptionsrequired | Extra services offered by the carrier. | ShippingServiceOptions | TBC | | LabelCustomization**optional | Label customization options. | LabelCustomization | |

Example Request:

Example Response:

Create Shipment

EndPoint : POST /mfn/v0/eligibleShippingServices

Docs: https://developer-docs.amazon.com/sp-api/docs/merchant-fulfillment-api-v0-reference#createshipmentrequest

Request schema.

Example Request:

Example Response:

Limits