Announcements
Developer CentralAPI StatusSupport
Back to All
added

Pre-Launch Announcement: Label Customisation for US and India Non-Amazon marketplace volume (OFF-Amazon)

18 days ago by Ziaur Raheman Khan

We are excited to announce the “Label Customisation” feature. This feature allows the Amazon Shipping API customers to add referenceId/OrderId or Seller Name or COD Value (India only) on the shipping labels.

Why is this important?

The Amazon Shipping API gives shippers programmatic access to Amazon Shipping services. By enabling the "requestedLabelCustomization/requestAttributes/ (PACKAGE_CLIENT_REFERENCE_ID or SELLER_DISPLAY_NAME or COLLECT_ON_DELIVERY_AMOUNT” field we provide a seamless way to display the seller’s name, referenceId or COD on label. We are confident this experience of label customisation will be more engaging and tailored to end customer needs and the details on this feature can significantly streamline warehouse operations and improve the customer experience!

The Challenge We Sought to Address

Across the globe, shippers have voiced a growing demand for more control over the information displayed on their shipping labels. Details that can significantly streamline warehouse operations and improve the customer experience!

The Custom Labels Solution

Label Customisation - a transformative new feature that empowers you to add a variety of artifacts to their Amazon Shipping labels. We with our initial launch, you'll be able to add:

• Order ID/Package Client ReferenceId: Shippers will be able to include the order's identification number or referenceId on the label. This will help them correlate the label to the specific package within their warehouse, ensuring the right products are sent to the right customers.
• Seller Name (Not applicable for India Marketplace): Shippers will be able to display their business name on the label. For third-party logistics providers fulfilling orders on behalf of sellers, this field can be used to inform the recipient of the originating seller.
• COD Value (For India only): Shippers will be able to include the COD value payable by recipient on the Label. This will help in case of COD deliveries by bridging the trust gap on payable amount between recipient and DA as Label will serve as proof.

How can I create a custom label for my Amazon Shipping parcel?

The custom label will be made available via Amazon Shipping V2 API (PurchaseShipment API and oneClickShipment API For Off-Amazon). The entire configuration process is a straightforward, simple integration and need to add an object in purchaseShipment or oneClickShipment API mentioning what field should appear on label.

Below, please find a sample of the change required to get started!

"requestedLabelCustomization": {	//Object to be included for label customisation
"requestAttributes": [   // requestAttributes is an Array, please include the field names that needs to be displayed on label
        "PACKAGE_CLIENT_REFERENCE_ID",
        "SELLER_DISPLAY_NAME",
        "COLLECT_ON_DELIVERY_AMOUNT"
    ]}

Note: requestedLabelCustomization is optional, if this is not passed in the request then default standard label will be created.

Sample purchaseShipment API request with Label Customisation fields:

{
  "requestToken": "amzn1.rq.85432213067105.100",
  "rateId": "75ec65c101bdb68ac979032268ba119ec17dda9a5e84312351bd9503a1bc058b1721804036099",
  "requestedDocumentSpecification": {
    "format": "PDF",
    "size": {
      "width": 4,
      "length": 6,
      "unit": "INCH"
    },
    "dpi": 203,
    "pageLayout": "DEFAULT",
    "needFileJoining": false,
    "requestedDocumentTypes": [
      "LABEL"
    ],
    "requestedLabelCustomization": {
      "requestAttributes": [
        "PACKAGE_CLIENT_REFERENCE_ID",
        "SELLER_DISPLAY_NAME",
        "COLLECT_ON_DELIVERY_AMOUNT"
      ]
    }
  }
}

Sample oneClickShipment API request with Label Customisation fields:

{
  "shipFrom": {
    "name": "SWA_Test_MFN202201",
    "addressLine1": "12801 S CENTRAL AVE",
    "stateOrRegion": "CA",
    "city": "LOS ANGELES",
    "postalCode": "90059",
    "countryCode": "US",
    "phoneNumber": "01928571677"
  },
  "shipTo": {
    "name": "SWA TEST ACCOUNT",
    "addressLine1": "7227 CENTRAL AVE",
    "city": "RIVERSIDE",
    "stateOrRegion": "CA",
    "countryCode": "US",
    "postalCode": "92504-1432",
    "email": "[email protected]",
    "phoneNumber": "999999999"
  },
  "serviceSelection": {
    "serviceId": [
      "std-us-swa-mfn"
    ]
  },
  "packages": [
    {
      "sellerDisplayName": "A TEST Seller",
      "insuredValue": {
        "unit": "USD",
        "value": 29.98
      },
      "weight": {
        "unit": "KILOGRAM",
        "value": 1.14159
      },
      "items": [
        {
          "quantity": 1,
          "itemValue": {
            "unit": "USD",
            "value": 1.99
          },
          "description": "Supplements",
          "weight": {
            "unit": "KILOGRAM",
            "value": 1
          },
          "itemIdentifier": "64618560956686",
          "isHazmat": false,
          "productType": "Medicine"
        },
        {
          "quantity": 1,
          "itemValue": {
            "unit": "USD",
            "value": 10
          },
          "description": "Supplements",
          "weight": {
            "unit": "OUNCE",
            "value": 1
          },
          "itemIdentifier": "8766",
          "isHazmat": false,
          "productType": " Medicine "
        }
      ],
      "isHazmat": false,
      "packageClientReferenceId": "ORDER-12345",
      "dimensions": {
        "unit": "CENTIMETER",
        "length": 3,
        "width": 3.14159,
        "height": 3.14159
      }
    }
  ],
  "labelSpecifications": {
    "dpi": 300,
    "format": "PNG",
    "needFileJoining": false,
    "pageLayout": "DEFAULT",
    "requestedDocumentTypes": [
      "LABEL"
    ],
    "size": {
      "length": 6.0,
      "unit": "INCH",
      "width": 4.0
    },
    "requestedLabelCustomization": {
      "requestAttributes": [
        "PACKAGE_CLIENT_REFERENCE_ID",
        "SELLER_DISPLAY_NAME",
        "COLLECT_ON_DELIVERY_AMOUNT"
      ]
    }
  },
  "channelDetails": {
    "channelType": "EXTERNAL"
  }
}

Note: The new element, requestedLabelCustomization/requestAttributes, needs to be added to the purchaseShipmentAPI, specifying the field names(Ex : PACKAGE_CLIENT_REFERENCE_ID or SELLER_DISPLAY_NAME or COLLECT_ON_DELIVERY_AMOUNT) you want to include on the label.

Field-Name: requestedLabelCustomization (optional)

Field-Type: A request label customisation object

NameDescriptionSchema
requestAttributes(required)The array of label customisation fields.array of labelCustomization value String

Label customization values:

ValueDescription
PACKAGE_CLIENT_REFERENCE_IDThe unique identifier for shipment used in the get-rates or oneclick shipment. Please refer packageClientReferenceId
SELLER_DISPLAY_NAMEThe seller name displayed on the label provided in the get-rates or oneclick shipment request. Note Available only for US.
COLLECT_ON_DELIVERY_AMOUNTThe monetary value in the currency indicated, in ISO 4217 standard format. Please refer CollectOnDelivery . Note Available only for IN.

When will this change be launched?

The Custom Labels feature will be available in early October'24 for Off-Amazon Shippers in the US and India.

What’s Next?

The launch of Customized Labels is just the beginning. In our upcoming release, expected in Q4, shippers will be able to include product SKUs and utilize freeform text fields to add more information. We're also expanding our custom label features to support MFN (Merchant Fulfilled Network)/ON Amazon orders. Stay tuned for more updates as we work to continuously enhance the Customized Labels feature to meet the changing needs of our shippers.

FAQs:

  1. What are Custom Labels in Amazon Shipping?
    Custom Labels is a new feature that allows shippers to add specific information such as Order ID, Seller Name, and COD Value (for India) to their Amazon Shipping labels, providing greater flexibility and control over label content.

  2. Who can use the Custom Labels feature?
    Amazon shipping OFF Amazon shippers in the United States and India can use this feature, starting from Early October.

  3. How do I get started with Custom Labels?
    To get started, review the updated Amazon Shipping V2 API documentation. In the purchaseShipment or oneClickShipment API, add the additionalLabelAttributes field, specifying the names of the fields you want to display on the label (Please refer the sample API request provided above).

  4. Are there any character limits for custom text fields like Seller Name or orderId?
    Yes, there are character limits to ensure the information fits within the label design.
    For US Character limit for OrderId/PackageClientReferenceId is 20 Characters and limit Seller Name 20 Characters.
    For India Character limit for OrderId/PackageClientReferenceId is 15 Characters and limit COD 8 Characters.
    The exact limits will be detailed in the API documentation.
    Note : If the value provided in the fields exceeds the character limit, the API request will not fail. Instead, the system will truncate the input, selecting the first 20 characters(For US :OrderId/PackageClientReferenceId, and Seller Name), 15 characters (For IN :OrderId/PackageClientReferenceId, and COD) and display them on the label.

  5. Can I keep using PurchaseShipment or OneclickShipment API after the rollout of new fields?
    Yes, you can continue using your API without mapping the new fields, ensuring backward compatibility.