Launch Announcement: Package Handoff API for Amazon Shipping

We are excited to announce the Package Handoff API, a new capability in the Amazon Shipping V2 API that enables shippers to share package handoff details with Amazon Shipping. This API provides real-time visibility into shipment status by allowing shippers to notify Amazon Shipping when packages are ready for pickup or have been physically handed off to Amazon Shipping, improving delivery accuracy and operational efficiency.

What is changing?

The Amazon Shipping V2 API is introducing a new endpoint, CreatePackageHandoffBatch, that allows shippers to communicate package handoff events directly to Amazon Shipping. With this launch, you'll be able to:

• Notify Pre-Handoff Status: Signal when packages are prepared, labeled, and ready for Amazon Shipping pickup using the PRE_HANDOFF process type.
• Confirm Post-Handoff Status: Confirm when packages have been physically handed off to Amazon Shipping using the POST_HANDOFF process type.
• Batch Processing: Submit up to 100 packages per API call for efficient bulk operations.
• Capture Package Details: Optionally include package dimensions, weight, container identifiers, and pickup vehicle identifiers for enhanced tracking.

Which marketplaces are affected?

This change applies to the following marketplaces: United States, United Kingdom, Italy, Spain, France.

What action is required?

If you have an application that integrates with Amazon Shipping APIs, be sure to:

• Review the new POST /shipping/v2/packageHandoff endpoint documentation below
• Update your integration to call the Package Handoff API after packages are prepared and/or handed off to Amazon Shipping
• Implement error handling for partial success responses (the API returns both successes and errors arrays)
• Test your implementation in the sandbox environment before using in production

Technical Implementation Details

API Endpoint:

Method: POST
Endpoint: /shipping/v2/packageHandoff
Operation ID: CreatePackageHandoffBatch

Schema Details:

Request — CreatePackageHandoffBatchRequest

HandoffPackage Object

Process Types

Response — CreatePackageHandoffBatchResponse

Package Error Codes

Header Parameters:

Sample API Request:

{
  "shipFrom": {
    "name": "Warehouse Operations",
    "addressLine1": "123 Warehouse Street",
    "city": "Seattle",
    "stateOrRegion": "WA",
    "postalCode": "98101",
    "countryCode": "US"
  },
  "packages": [
    {
      "trackingId": "TBA324991996260",
      "processType": "PRE_HANDOFF",
      "processTimestamp": "2026-03-15T09:01:00Z",
      "dimensions": {
        "length": 12.5,
        "width": 10.0,
        "height": 8.0,
        "unit": "INCH"
      },
      "weight": {
        "value": 2.5,
        "unit": "POUND"
      }
    }
  ]
}

{
  "shipFrom": {
    "name": "Warehouse Operations",
    "addressLine1": "123 Warehouse Street",
    "city": "Seattle",
    "stateOrRegion": "WA",
    "postalCode": "98101",
    "countryCode": "US"
  },
  "packages": [
    {
      "trackingId": "TBA324991996260",
      "processType": "POST_HANDOFF",
      "processTimestamp": "2026-03-15T14:30:00Z"
    },
    {
      "trackingId": "TBA324991996261",
      "processType": "POST_HANDOFF",
      "processTimestamp": "2026-03-15T14:30:00Z"
    },
    {
      "trackingId": "TBA324991996262",
      "processType": "POST_HANDOFF",
      "processTimestamp": "2026-03-15T14:30:00Z"
    }
  ]
}

Sample API Response:

{
  "successes": [
    {
      "trackingId": "TBA324991996260"
    },
    {
      "trackingId": "TBA324991996261"
    },
    {
      "trackingId": "TBA324991996262"
    }
  ],
  "errors": []
}

{
  "successes": [
    {
      "trackingId": "TBA324991996260"
    },
    {
      "trackingId": "TBA324991996261"
    }
  ],
  "errors": [
    {
      "trackingId": "TBA324991996262",
      "code": "INVALID_PACKAGE_IDENTIFIER",
      "message": "Package identifier is invalid"
    }
  ]
}

FAQs:

1. Will this feature impact my existing API integration?
   No. The Package Handoff API is a new, standalone endpoint. Existing integrations for label creation, tracking, and cancellation continue to work without changes.

2. Is it mandatory to call the Package Handoff API?
   It is not mandatory, but it is strongly recommended. Sharing handoff events with Amazon Shipping helps align delivery metric calculations, enables more accurate estimated delivery dates, supports proactive alerting for delayed or missing packages, and provides end-to-end shipment visibility across the fulfillment lifecycle. Integrating this API is recommended to get the most out of your Amazon Shipping experience.

3. Do I need to send both PRE_HANDOFF and POST_HANDOFF?
   No. You may send PRE_HANDOFF, POST_HANDOFF, or both based on your shipping processes. Process types should align with your operational workflow. However, sending both provides Amazon Shipping with the most complete picture of your handoff timeline.

4. What happens if I submit duplicate tracking IDs in the same request?
   One instance will be processed successfully, and the duplicate will be returned in the errors array with the DUPLICATE_PACKAGE_IN_REQUEST error code.

5. What is the maximum number of packages per request?
   You can submit up to 100 packages per API call. Requests exceeding this limit will be rejected with a http 400 Bad Request.

6. Are dimensions and weight required?
   No. Dimensions and weight are optional fields. However, providing them when available improves tracking accuracy.

7. What rate limits apply to this API?
   The API supports 5 requests per second. Monitor the x-amzn-RateLimit-Limit response header and implement exponential backoff for 429 responses.

8. Can I use this API in the sandbox environment?
   Yes. The Package Handoff API supports dynamic sandbox testing. Use your sandbox credentials to test before moving to production.