Anmelden

Vielen Dank für deinen Besuch. Diese Seite ist nur in Englisch verfügbar.

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 plugins ready for Alexa Delivery Notifications

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)

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

Note: Amazon Pay does not require separate credentials for different environments. You can use the same Public Key ID and key pair for both Live and Sandbox.

Instructions:

Navigate to Amazon Pay Integration Central
Choose the "Alexa" Integration channel
1. From the "What are you looking to do?" drop-down menu select “Set up delivery notifications”
2. Select “Get instructions”
Create a public/private key pair
1. Scroll down to the “API keys” section
2. Click the “Create keys” button
3. Use the default “Generate API credentials” setting
4. 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
5. 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
1. 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.
2. 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.

Warning: You should never share your private key with anyone and this is the only time that you will be able to download the private key file. If you lose access to your private key, you must generate a new key pair.

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();
}

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.

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 receive notifications 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.