Setting up delivery notifications
Introduction
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 out for delivery and when they are delivered. This API is channel-agnostic. That means that anywhere you use Amazon Pay, you can use the Delivery Tracker API.
This guide will support you in adding Alexa Delivery Notifications to your existing Amazon Pay integration. You can either integrate the Delivery Tracker APIs yourself, or benefit form one of the pre-built solutions for your region below.
Ecommerce solution | Resources | Min. plugin version |
---|---|---|
Magento 1 | Installation steps and documentation | 1.7.2 |
Magento 2 | Installation steps and documentation | 1.0.0 |
Ecommerce solution | Resources | Min. plugin version |
---|---|---|
Magento 1 | Installation steps and documentation | 3.0.14 |
Magento 2 | Installation steps and documentation | 1.0.0 |
PrestaShop | Installation steps and documentation | 2.3.2 (PrestaShop 1.6) 3.3.0 (PrestaShop 1.7) |
JTL Shop 4 | Installation steps and documentation | 1.0.0 |
Ecommerce solution | Resources | Min. plugin version |
---|---|---|
We hope to offer you a solution soon. |
- Here's what your customer will experience
- Get your Public Key ID
- API reference
- Sample requests and responses
- Throttling limits
- SDK Support
- Testing your integration
Here's what your customer will experience
Customer: Alexa, read my notifications.
Out for delivery notification
Alexa: You have one new notification, from Amazon Pay. A shipment from [yourstorename] is scheduled to arrive by [date].
Delivery notification
Alexa: You have one new notification, from Amazon Pay. Your shipment from [yourstorename] has been delivered.
Get your Public Key ID
Amazon Pay uses asymmetric encryption to secure communication. You will need a public/private key pair and a corresponding Public Key ID (a unique Amazon Pay identifier for the key pair) to access Amazon Pay APIs. You can generate a public/private key pair and access the Public Key ID using Amazon Pay Integration Central inside your Seller Central. Please choose the URL to Seller Central matching your region.
Region | URL |
---|---|
NA | Integration Central |
EU/UK | Integration Central |
JP | Integration Central |
Instructions:
- Navigate to Amazon Pay Integration Central
- Choose the "Alexa" Integration channel
- From the "What are you looking to do?" drop-down menu select “Set up delivery notifications”
- Select “Get instructions”
- Create a public/private key pair
- Scroll down to the “API keys” section
- Click the “Create keys” button
- Use the default “Generate API credentials” setting
- Name your API keys. Use a descriptive name, the name will be used to differentiate between multiple keys when you need to manage them in Integration Central. When naming the keys, you should consider who is using it and what they’re using it for
- Click the “Create keys” button in the pop-up window to create the public/private key pair
- Store the private key and Public Key ID
- Creating the key pair will automatically start a download for the private key (.pem) file. Save the private key file in a secure location, you will need it to access Amazon Pay APIs. You do not need the public key.
- Store your Public Key ID, you will need it to access Amazon Pay APIs. Unlike the private key file, you can return to this page at a later time to access your Public Key ID.
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/UK | pay-api.amazon.eu |
JP | pay-api.amazon.jp |
Path: /live/v2/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
<?php
include 'vendor/autoload.php';
$amazonpay_config = array(
'public_key_id' => 'MY_PUBLIC_KEY_ID',
'private_key' => 'keys/private.pem',
'region' => 'US',
'sandbox' => false
);
$payload = array(
'amazonOrderReferenceId' => 'P00-0000000-0000000',
'deliveryDetails' => array(array(
'trackingNumber' => '1Z999AA10123456784',
'carrierCode' => 'UPS'
))
);
try {
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->deliveryTrackers($payload);
if ($result['status'] === 200) {
// success
echo $result['response'] . "\n";
} else {
// check the error
echo 'status=' . $result['status'] . '; response=' . $result['response'] . "\n";
}
} catch (\Exception $e) {
// handle the exception
echo $e . "\n";
}
?>
AmazonPayResponse response = null;
JSONObject payload = new JSONObject();
JSONObject deliveryDetails = new JSONObject();
JSONArray deliveryDetailsArray = new JSONArray();
deliveryDetails.put("trackingNumber", "1Z999AA10123456784");
deliveryDetails.put("carrierCode", "UPS");
deliveryDetailsArray.add(deliveryDetails);
payload.put("amazonOrderReferenceId", "P00-0000000-0000000");
payload.put("deliveryDetails", deliveryDetailsArray);
try {
response = client.deliveryTracker(payload);
} catch (AmazonPayClientException e) {
e.printStackTrace();
}
// prepare the request
var request = new DeliveryTrackerRequest
(
objectId: "P00-0000000-0000000", // ChargePermissionID or OrderReferenceID
objectIsChargePermission: true, // true if above is ChargePermissionID, false otherwise
trackingNumber: "1Z999AA10123456784",
carrierCode: "UPS"
);
// generate the button signature
var result = client.SendDeliveryTrackingInformation(request);
// check if API call was successful
if (!result.Success)
{
// do something, e.g. throw an error
}
return result;
const fs = require('fs');
const Client = require('../src/client');
const config = {
publicKeyId: 'ABC123DEF456XYZ',
privateKey: fs.readFileSync('tst/private.pem'),
region: 'us',
sandbox: true
};
const payload = {
amazonOrderReferenceId: 'P00-0000000-0000000',
deliveryDetails: [{
trackingNumber: '1Z999AA10123456789',
carrierCode: 'UPS'
}]
};
const testPayClient = new Client.AmazonPayClient(config);
const response = testPayClient.deliveryTrackers(payload);
POST /live/v2/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" : "P00-0000000-0000000",
"deliveryDetails" : [{
"trackingNumber" : "1Z999AA10123456784",
"carrierCode" : "UPS"
}]
}
Successful response message example
HTTP/1.1 200 OK
Host: pay-api.amazon.com
Content-type: application/json
{
"amazonOrderReferenceId" : "P00-0000000-0000000",
"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 merchant account is not authorized to execute this request. |
429 | TooManyRequests | The request is throttled, due to too many requests in a given amount of time. Refer to the throttling limits. |
500 | InternalServerError | There was an unknown error in the service. |
Throttling limits
When your website performs a given operation, the Amazon Pay service limits the number of requests that you can make in a given amount of time. This process of limiting, called throttling, protects the web service from being overwhelmed with requests and ensures that all authorized websites have access to the web service.
For definitions of throttling terminology and a complete explanation of throttling, see Throttling: Limits to how often you can submit requests in the Amazon MWS Developer Guide.
Production Max quota |
Production Restore rate |
Sandbox Max quota |
Sandbox Restore rate |
---|---|---|---|
10 | 1 | 1 | 1 |
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.
- PHP: https://github.com/amzn/amazon-pay-api-sdk-php
- Java: https://github.com/amzn/amazon-pay-api-sdk-java
- .Net: https://github.com/amzn/amazon-pay-api-sdk-dotnet
- NodeJS: https://github.com/amzn/amazon-pay-api-sdk-nodejs
Testing your integration
To test the Amazon Pay Delivery Tracker API, you will need an Amazon Pay “OrderReference ID” or “Charge Permission ID”. This is the ID that is generated when an order is placed on a merchant’s website using Amazon Pay. You can use this ID along with the carrier code and tracking code of a supported carrier to trigger an Alexa Delivery Notification. The following steps will explain in detail how to test this process both in a sandbox and live environment.
Sandbox Testing
The deliveryTrackers API for Alexa Delivery Notifications allows you to test your integration in the Amazon Pay sandbox environment. While this will not allow you to execute an end-to-end test - no Deliver Notification will be sent - it is sufficient to ensure a fully functional integration.
Testing your integration in sandbox is done as described below.
- Perform a test order or use an existing test order on the sandbox environment. Please note down the ChargePermissionID or OrderReferenceID of your test order.
- Execute the deliveryTrackers API call using your ChargePermissionID or OrderReferenceID, a random tracking code and a carrier code of one of our supported carriers. If you are using one of our SDKs, please check the samples.
- Verify that the API calls returns a 200 response (success).
Live testing (optional)
Live testing is the only way to test the full experience, including a notification on your Alexa-enabled device. A working sandbox integration is however sufficient to ensure your deliveryTrackers API integration will work as expected in a live environment. Please ensure the following before placing an order on your live system:
- Connect your Alexa-enabled device to the Amazon account that you will be using for the live order
- Enable delivery and out for delivery notifications at Settings -> Notifications -> Amazon Shopping in the Alexa app
After placing an order in the live system, you’ll have to wait for the order to be shipped so that you have a real tracking code available. Use this tracking code along with the carrier code and the ChargePermissionID or OrderReferenceID of your live order to call the deliveryTrackers API. As before, the API call should respond with a 200 code.
As soon as the order is being sent out, you should receive a notification on your Alexa-enabled device. For tracking codes of already delivered orders or when your order is actually delivered, you will recieve another notification informing about the successful delivery of the order.
Any tracking code can only be used once on the deliverTrackers API.