Setting up delivery notifications

Provide shipment tracking information to Amazon Pay using Create Delivery Tracker 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.

Buyer experience
Ecommerce plugins
Integration steps

Buyer experience

Here is what your buyer 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.

Ecommerce plugins

You can either integrate the Delivery Tracker APIs yourself, or use one of the pre-built solutions for your region below.

Ecommerce solution	Resources	Min. plugin version
Magento 1	Installation steps and documentation	3.0.14
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

We hope to offer you a solution soon.

Integration steps

1. Create a Delivery Tracker

Call Create Delivery Tracker with the Amazon chargePermissionID, shipping company carrierCode, and trackingNumber to enable delivery notifications.

Request

<?php
include 'vendor/autoload.php';

$amazonpay_config = array(
    'public_key_id' => 'YOUR_PUBLIC_KEY_ID',
    'private_key'   => 'keys/private.pem',
    'region'        => 'YOUR_REGION_CODE',
    'algorithm' => 'AMZN-PAY-RSASSA-PSS-V2'
);
$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: 'YOUR_PUBLIC_KEY_ID',
    privateKey: fs.readFileSync('tst/private.pem'),
    region: 'YOUR_REGION_CODE',
    algorithm: 'AMZN-PAY-RSASSA-PSS-V2'
};

const payload = {
    amazonOrderReferenceId: 'P00-0000000-0000000',
    deliveryDetails: [{
        trackingNumber: '1Z999AA10123456789',
        carrierCode: 'UPS'
    }]
};

const testPayClient = new Client.AmazonPayClient(config);
const response = testPayClient.deliveryTrackers(payload);


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

{
    "amazonOrderReferenceId" : "P00-0000000-0000000",
    "deliveryDetails" : [{
    "trackingNumber" : "1Z999AA10123456784",
    "carrierCode" : "UPS"
  }]
}

<?php
include 'vendor/autoload.php';

$amazonpay_config = array(
  'public_key_id' => 'MY_PUBLIC_KEY_ID',
  'private_key'   => 'keys/private.pem',
  'region'        => 'US',
  'sandbox'       => false,
  'algorithm' => 'AMZN-PAY-RSASSA-PSS-V2'
);
$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: 'YOUR_PUBLIC_KEY_ID',
    privateKey: fs.readFileSync('tst/private.pem'),
    region: 'us',
    sandbox: true,
    algorithm: 'AMZN-PAY-RSASSA-PSS-V2'
};

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-V2 PublicKeyId=f4fc06fc-c5a7-11e7-abc4-cec278b6b50a, SignedHeaders=content-type;x-amz-pay-date;x-amz-pay-region, Signature=4164128ec5d1b9da1700167ab2ccda8125f472c8bb9de447cebf5d741ee317c8       
X-Amz-Pay-Date: 20190305T024410Z
Content-type: application/json

{
    "amazonOrderReferenceId" : "P00-0000000-0000000",
    "deliveryDetails" : [{
    "trackingNumber" : "1Z999AA10123456784",
    "carrierCode" : "UPS"
  }]
}

Request parameters

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

Response

{
    "amazonOrderReferenceId": "P00-0000000-0000000",
    "deliveryDetails": [{
        "trackingNumber": "1Z999AA10123456784",
        "carrierCode": "UPS"
    }]
}

2. Test your integration

You will need an Alexa-enabled device for end-to-end testing.

Sandbox testing

You can ensure a fully functional integration by executing an end-to-end test in Sandbox but no Delivery Notification will be sent. To test in Sandbox:

Create a test order and save the chargePermissionID or orderReferenceID
Call Create Delivery Tracker using the ChargePermissionID or OrderReferenceID, a random tracking code, and a carrier code of one of the supported carriers.
Verify that the API calls returns a HTTP 200 (OK) status.

Live testing (optional)

A successful sandbox test is sufficient for ensuring the integration will work as expected but Live testing is the only way to trigger the full experience including a notification on your Alexa-enabled device. Prerequisites:

Your Alexa-enabled device must be connected to the Amazon account you’re using for the Live order
You must enable delivery and out for delivery notification under Settings → Notifications → Amazon Shopping in the Alexa app. Note that for customer outside of the US, the account must have at least one order fulfilled by Amazon to be enrolled for notifications, otherwise you will not see the settings.

Call Create Delivery Tracker once the order has been shipped and a real tracking code has been generated. You should receive a notification on your Alexa-enabled device when the order is shipped and when the order is delivered. Note that tracking codes can only be used once.