Setting up delivery notifications

Note:
• If you are on Magento 1, refer here for installation steps and documentation (v1.7.2).
• If you are on Magento 1 for Europe, refer here for installation steps and documentation (v3.0.14).
• If you are on Magento 2, refer here for installation steps and documentation.

The Amazon Pay Delivery Tracker API lets you provide shipment tracking information to Amazon Pay so that Amazon Pay can notify buyers on Alexa when shipments are delivered. This API is channel-agnostic. That means that anywhere you use Amazon Pay, you can use the Delivery Tracker API.

Here's what your customer will experience
Before you begin
API reference
Sample requests and responses
SDK Support
Testing your integration

Here's what your customer will experience

Customer: Alexa, read my notifications.

Out for delivery notification
Alexa: One new notification, from Amazon Pay. A shipment from [yourstorename] is scheduled to arrive by [date].

Delivery notification
Alexa: One new notification, from Amazon Pay. Your shipment from [yourstorename] has been delivered.

Before you begin

Complete the following steps before integrating with the Amazon Pay Delivery Tracker API.

Generate a one-time private and public key pair

If you already created your keys and received a Public Key ID for your Amazon Pay integration, you can skip this step.
- Linux / Mac
- Windows 10
Open Command Prompt or Terminal and generate a one-time private and public key pair by running the following commands:
```
openssl genrsa -out <directory path>/<private key file name>.pem 2048
openssl rsa -in <directory path>/<private key file name>.pem -pubout > <directory path>/<public key file name>.pub
     
```
Open a Windows command prompt or PowerShell and generate a one-time private and public key pair by running the following commands:
```
       
ssh-keygen -t rsa -b 2048 -f <directory path>/<private key file name>
ssh-keygen -f <directory path>/<private key file name> -e -m PKCS8 > <directory path>/<public key file name>
       
     
```
Note: Alternatively, you can also use the Linux commands using a BASH emulation like Git BASH.
Get the Public Key ID by providing the Seller ID, Public Key and your region in email to Amazon Pay at amazon-pay-delivery-notifications@amazon.com.
For the security of your account, Amazon Pay will email your Public Key ID to the email associated with your Seller Central account. Your Public Key ID will also be available in your Seller Central account within 1–2 business days.
Before integrating yourself, check if we can support you using one of our SDKs
Sign all requests made to the Delivery Tracker API with the private key.
Include the Public Key ID in the authorization header in all requests made to the Delivery Tracker API.

API reference

You can call the HTTP POST request with the endpoint, path, and headers specified below.

Region	Endpoint
NA	pay-api.amazon.com
EU	pay-api.amazon.eu
JP	pay-api.amazon.jp

Path: /live/v1/deliveryTrackers

Request headers

Header	Description	Type
Authorization (required)	The signature algorithm, public key ID, signed headers, and the signature in the following format: Signature_Algorithm PublicKeyId=publicKeyId, SignedHeaders=SignedHeaders, Signature=signature	String
X-Amz-Pay-Date (required)	The time at which the signature was generated. The signature, including timestamp, is generated in the payload. The date is in format YYYYMMDD’T’HHMMS’Z’ in ISO 8601 format.	String

Request parameters

Parameter	Description	Type
amazonOrderReferenceId - or - chargePermissionId (required)	The Amazon Order Reference ID or Charge Permission ID associated with the order for which the shipments need to be tracked	String
trackingNumber (required)	The tracking number for the shipment provided by the shipping company	String
carrierCode (required)	The shipping company code used for delivering goods to the customer Download carrierCode list	String

Sample requests and responses

Request message example

POST /live/v1/deliveryTrackers HTTP/1.1
Host: pay-api.amazon.com 
Accept: application/json 
Authorization: AMZN-PAY-RSASSA-PSS PublicKeyId=f4fc06fc-c5a7-11e7-abc4-cec278b6b50a, SignedHeaders=content-type;x-amz-pay-date, Signature=4164128ec5d1b9da1700167ab2ccda8125f472c8bb9de447cebf5d741ee317c8       
X-Amz-Pay-Date: 20190305T024410Z
Content-type: application/json

{
    "amazonOrderReferenceId" : "P01-5728498-6728743",
    "deliveryDetails" : [{
    "trackingNumber" : "1Z999AA10123456784",
    "carrierCode" : "UPS"
  }]
}

Successful response message example

HTTP/1.1 200 OK 
Host: pay-api.amazon.com
Content-type: application/json

{
  "amazonOrderReferenceId" : "P01-5728498-6728743",
  "deliveryDetails" : [{
    "trackingNumber" : "1Z999AA10123456784",
    "carrierCode" : "UPS"
  }]
}

Successful response headers

Header	Description
Content-Type	application/json

Successful response parameters

Parameter	Description	Type
amazonOrderReferenceId	The order reference ID associated with the order for which the shipments need to be tracked	String
trackingNumber	The tracking number for the shipment provided by the shipping company	String
carrierCode	The shipping company used for delivering goods to the customer	String

Error response

HTTP/1.1 400 Bad Request 
Content-Type: application/json; 
{ 
    "reasonCode": "InvalidParameterValue", 
    "message": "The amazonOrderReferenceId that you submitted in this request is invalid.”
}

Error response parameters

Parameter	Description	Type
reasonCode	Machine readable error code	String
message	Human-readable error description	String

Error response message examples

If there is a problem fulfilling your request, you receive an HTTP error. The error codes for Delivery Tracker API request include:

Status	Error code	Description
400	InvalidInputFormat	The input provided is not in the required format.
400	InvalidParameterValue	The [parameterName] parameter is required.
400	InvalidParameterValue	The amazonOrderReferenceId that you submitted in this request is invalid.
400	InvalidParameterValue	The trackingNumber or carrierCode that you submitted in this request is invalid.
401	UnauthorizedAccess	The specified seller account is not authorized to execute this request.
500	InternalServerError	There was an unknown error in the service.

SDK Support

Use an Amazon Pay SDK to simplify the integration. Please reach out to your Amazon Pay account manager or merchant support if you don’t see a SDK in your preferred language.

Testing your integration

To test the Amazon Pay Delivery Tracker API, you will need

An Amazon Pay OrderReference ID of an order placed between the customer intended to receive the notification and the merchant as the party shipping the order. Notifications will only be sent when using a live Order Reference ID, sandbox Order References can be used to test the server to server integration.
Tracking number(s) of a supported carrier and the matching carrier code.
For end-to end testing, an Alexa-enabled device connected to the customer's account to receive the notifications.

Using a tracking number of an already delivered order will cause a Delivery notification. A tracking number of an order still in transit will cause an Out for delivery notification.

Note:
To actually receive the notification on the customer’s Alexa device, ensure the customer account has delivery and out for delivery notifications enabled at Settings -> Notifications -> Amazon Shopping. For customers outside of the US, at least one order fulfilled by Amazon is required to be enrolled into those notifications and to see the corresponding settings.