About shipping with Amazon

Both Amazon carrier services, Ship With Amazon (SWA) and Vendor Direct Fulfillment (VDF), require that additional fields be included in your API calls. This document provides sample calls to Shipium's Carrier and Method Selection & Label Generation API with the required fields for SWA and VDF.

Ship With Amazon

The following JSON example is a call request to Shipium's Carrier and Method Selection & Label Generation API with the required fields for Amazon - Ship With Amazon included. This example is for a single-parcel shipment; for multi-parcel shipments, the fields included in shipmentParameters would instead be included in multiParcelShipmentParameters.

While not all fields in the example are required, they are suggested for a request to determine the carrier service method for a shipment and also retrieve a shipment label. The labelParameters object must be defined when generating a label. Address requirements vary by carrier, so Shipium suggests supplying as much information as possible. You can find guidance for address variations in Non-U.S. Address Formats.

Fields not defined in the table following this sample request are described in the request fields table in the API documentation.

{
  "currencyCode": "usd",
  "generateLabel": true,
  "labelParameters": {
      "currencyCode": "usd",
      "includeLabelImagesInResponse": true,
      "labelFormats": [
          "zpl"
      ],
      "eligibleForManifest": true
  },
  "shipmentParameters": {
        "shippedDateTime": "2024-04-06T18:30:55.558Z",
        "orderedDateTime": "2024-04-03T18:30:55.558Z",
        "testMode": true,
        "destinationAddress": {
            "countryCode": "US",
            "postalCode": "87121",
            "addressType": "commercial",
            "city": "Albuquerque",
            "name": "Wile E. Coyote",
            "phoneNumber": "888-555-1234",
            "state": "NM",
            "street1": "123 Main St.",
            "street2": "Suite 42"
        },
        "shipFromAddress": {
            "countryCode": "US",
            "postalCode": "17901",
            "city": "Pottsville",
            "state": "PA",
            "street1": "401 N. Centre St."
        },
        "orderSourceName": "amazon",
        "carrierProcessingId": "PO1234",
        "orderItemQuantities": [
            {
            "hazmatInfo": {
               "packingInstructionCode": "967"
        },
            "itemWeight": {
               "weightUnit": "lb",
               "weight": 50
            }, 
            "productId": "ET-14-4000",
            "quantity": 2
            }
        ],
        "packagingType": {
            "packagingMaterial": "box",
            "packagingWeight": {
                "weight": 13,
                "weightUnit": "oz"
            },
            "linearDimensions": {
                "length": 15,
                "width": 10,
                "height": 5,
                "linearUnit": "in"
            }
        },
        "totalWeight": {
            "weight": 13,
            "weightUnit": "oz"
        }
  }
}

When shipping with Amazon - Ship With Amazon, you must include the required fields listed in the following table, flagged as required specifically for Ship With Amazon (SWA), in your API call. The other fields marked as required are needed for any request call to Shipium's Carrier and Method Selection & Label Generation API. Optional (but suggested) fields not specifically related to SWA are included in the sample call request above but are not in defined in the following table. They are described in the request fields table in the API documentation.

Reference field	Required/Optional	Field properties	Description
`currencyCode`	Required	String	Currency in which all the rates for shipping carrier selection costs will be calculated
`generateLabel`	Optional	Boolean `true` or `false`	When `true`, a request to the selected carrier will be sent to generate a label for the shipment based on the information provided in the `labelParameters` field of this object. When `false`, this step is skipped and the system will record what carrier service method would have generated a label for.
`labelParameters .currencyCode`	Optional	String	Currency in which all the rates for shipping carrier selection costs will be calculated
`labelParameters .includeLabelImages InResponse`	Optional	Boolean `true`or`false`	If `true`, the response will include the raw image data of the labels that were requested to be generated by the carrier.
`labelParameters .labelFormats`	Optional	String enumeration Supported formats are: - `pdf` - `png` - `zpl`	List of formats in which to generate the package label
`labelParameters .eligibleForManifest`	Optional	Boolean `true`or`false`	When `true`, or null, this label will be included in end-of-day and scheduled manifests. `False` indicates that the label should not be included in any manifests.
`shipmentParameters .destinationAddress .countryCode`	Required	String	The ISO 3166-1 country code for the destination address
`shipmentParameters .destinationAddress .postalCode`	Required	String	A country-code-appropriate postal code for the destination address
`shipmentParameters .destinationAddress .addressType`	Required	String enumeration Values are: - `commercial` - `residential`	The type of location for the destination address
`shipmentParameters .shipFromAddress .countryCode`	Required	String	The ISO 3166-1 country code for the origin address
`shipmentParameters .shipFromAddress .postalCode`	Required	String	A country-code-appropriate postal code for the origin address
`shipmentParameters .orderSourceName`	Required, for SWA	String	The source of the order that was placed; if the source is Amazon Marketplace, you'll enter `amazon` for this value.
`shipmentParameters .carrierProcessingId`	Required if the value provided for `orderSourceName` is `amazon`, for SWA	String	Carrier-provided identifier; this is the purchase order number from the order step via Amazon.
`shipmentParameters .orderItemQuantities .hazmatInfo .packingInstruction Code`	Required for international shipments and shipments containing hazardous materials, for SWA	String enumeration Values are: - `PI965_SECTION_IA` (Ion PI965 Section IA [LiBa]) - `PI965_SECTION_IB` (Ion PI965 Section IB [LiBa]) - `PI965_SECTION_II` ( [LiBa]) - `PI966_SECTION_I` (Ion PI966 Section I [LiBa with equipment]) - `PI966_SECTION_II` (Ion PI966 Section II [LiBa with equipment]) - `PI967_SECTION_I` (Ion PI967 Section I [LiBa in equipment]) - `PI967_SECTION_II`(Ion PI967 Section II [LiBa in equipment]) - `PI968_SECTION_IA` (Metal PI968 Section IA [LiBa]) - `PI968_SECTION_IB` (Metal PI968 Section IB [LiBa]) - `PI969_SECTION_I` (Metal PI969 Section I [LiBa with equipment]) - `PI969_SECTION_II` (Metal PI969 Section II [LiBa with equipment]) - `PI970_SECTION_I` (Metal PI970 Section I [LiBa in equipment]) - `PI970_SECTION_II` (Metal PI970 Section II [LiBa in equipment])	The specific packing instruction of the item being shipped
`shipmentParameters .orderItemQuantities .itemWeight.weight`	Required, for SWA	Number	The value of the weight
`shipmentParameters .orderItemQuantities .itemWeight .weightUnit`	Required, for SWA	String enumeration Values are: - `g` (gram) - `kg` (kilogram) - `oz` (ounce) - `lb` (pound)	The unit in which weight values are provided
`shipmentParameters .orderItemQuantities .productId`	Optional, but required for international shipments and shipments containing hazardous materials	String Ex.: `RN03947--Z43121`	A product ID for the product being checked (ISBN, UPC, etc.)
`shipmentParameters .orderItemQuantities .quantity`	Optional, but required for international shipments and shipments containing hazardous materials	Integer ($int32) Ex.: `3`	The number of units of the product
`shipmentParameters .packagingType .packagingTypeId`	Optional, but required if `linearDimensions` is not provided	String Ex.: `ebd94f8b-d390-4c9c-987f-b88343f5bf45`	The `packagingTypeId` that was used for this package; when this value is present, the dimensions pre-configured by your organization are used. When this value is absent, `linearDimensions` is required.
`shipmentParameters .packagingType .linearDimensions .length`	Optional, but required if the `packagingTypeId` is not included	Number ($float) Ex.: `13`	The longest linear dimension (i.e., the longest side of a box or envelope)
`shipmentParameters .packagingType .linearDimensions .width`	Optional, but required if the `packagingTypeId` is not included	Number ($float) Ex.: `12`	The second longest linear dimension (i.e., the second longest side of a box or envelope)
`shipmentParameters .packagingType .linearDimensions .height`	Optional, but required if the `packagingTypeId` is not included	Number ($float) Ex.: `10`	The least long linear dimension (i.e., the shortest side of a box or envelope). Note on envelopes: This height should represent the highest product you would reasonably put in this envelope before losing more than 10% of the length of the envelope in other dimensions.
`shipmentParameters .packagingType .linearDimensions .linearUnit`	Optional, but required if the `packagingTypeId` is not included	String enumeration Values are: - `cm` (centimeter) - `in` (inch)	The unit in which linear dimensions are provided

Vendor Direct Fulfillment

The following JSON example is a call request to Shipium's Carrier and Method Selection & Label Generation API with the required fields for Amazon - Vendor Direct Fulfillment included. This example is for a single-parcel shipment; for multi-parcel shipments, the fields included in shipmentParameters would instead be included in multiParcelShipmentParameters.

Fields not defined in the table following this sample request are described in the request fields table in the API documentation.

{
  "currencyCode": "usd",
  "generateLabel": true,
  "labelParameters": {
      "currencyCode": "usd",
      "includeLabelImagesInResponse": true,
      "labelFormats": [
          "zpl"
      ],
      "eligibleForManifest": true
  },
  "shipmentParameters": {
        "shippedDateTime": "2024-04-06T18:30:55.558Z",
        "orderedDateTime": "2024-04-03T18:30:55.558Z",
        "testMode": true,
        "destinationAddress": {
            "countryCode": "US",
            "postalCode": "87121",
            "addressType": "commercial",
            "city": "Albuquerque",
            "name": "Wile E. Coyote",
            "phoneNumber": "888-555-1234",
            "state": "NM",
            "street1": "123 Main St.",
            "street2": "Suite 42"
        },
        "shipFromAddress": {
            "countryCode": "US",
            "postalCode": "17901",
            "city": "Pottsville",
            "state": "PA",
            "street1": "401 N. Centre St."
        },
        "carrierProcessingId": "PO1234",
        "packageReferenceIdentifier": "package1",
        "orderItemQuantities": [
            {
            "orderItemReferenceIdentifier": "someIdentifier",
              "productId": "ET-14-4000",
            "quantity": 2
            }
        ],
        "packagingType": {
            "packagingMaterial": "box",
            "packagingWeight": {
                "weight": 13,
                "weightUnit": "oz"
            },
            "linearDimensions": {
                "length": 15,
                "width": 10,
                "height": 5,
                "linearUnit": "in"
            }
        },
        "totalWeight": {
            "weight": 13,
            "weightUnit": "oz"
        }
  }
}

When shipping with Amazon - Vendor Direct Fulfillment, you must include the required fields listed in the following table, flagged as required specifically for Vendor Direct Fulfillment (VDF), in your API call. The other fields marked as required are needed for any request call to Shipium's Carrier and Method Selection & Label Generation API. Optional (but suggested) fields not specifically related to VDF are included in the sample call request above but are not in defined in the following table. They are described in the request fields table in the API documentation.

Reference field	Required/Optional	Field properties	Description
`currencyCode`	Required	String	Currency in which all the rates for shipping carrier selection costs will be calculated
`generateLabel`	Optional	Boolean `true` or `false`	When `true`, a request to the selected carrier will be sent to generate a label for the shipment based on the information provided in the `labelParameters` field of this object. When `false`, this step is skipped and the system will record what carrier service method would have generated a label for.
`labelParameters .currencyCode`	Optional	String	Currency in which all the rates for shipping carrier selection costs will be calculated
`labelParameters .includeLabelImages InResponse`	Optional	Boolean `true`or`false`	If `true`, the response will include the raw image data of the labels that were requested to be generated by the carrier.
`labelParameters .labelFormats`	Optional	String enumeration Supported formats are: - `pdf` - `png` - `zpl`	List of formats in which to generate the package label
`labelParameters .eligibleForManifest`	Optional	Boolean `true`or`false`	When `true`, or null, this label will be included in end-of-day and scheduled manifests. `False` indicates that the label should not be included in any manifests.
`shipmentParameters .destinationAddress .countryCode`	Required	String	The ISO 3166-1 country code for the destination address
`shipmentParameters .destinationAddress .postalCode`	Required	String	A country-code-appropriate postal code for the destination address
`shipmentParameters .destinationAddress .addressType`	Required	String enumeration Values are: - `commercial` - `residential`	The type of location for the destination address
`shipmentParameters .shipFromAddress .countryCode`	Required	String	The ISO 3166-1 country code for the origin address
`shipmentParameters .shipFromAddress .postalCode`	Required	String	A country-code-appropriate postal code for the origin address
`shipmentParameters .carrierProcessingId`	Required, for VDF	String	Carrier-provided identifier; this is the purchase order number from the order step via Amazon.
`shipmentParameters .packageReference Identifier`	Required, for VDF	String	Used to correlate parcels to label documents from the carrier; this is the container identifier that Amazon uses as a parcel identifier.
`shipmentParameters .orderItemQuantities .orderItemReference Identifier`	Required, for VDF	Integer	A carrier-provided identifier that references the order item; this is the item sequence number returned from Amazon during the order placement step.
`shipmentParameters .orderItemQuantities .productId`	Required, for VDF	String	A product ID for the product being checked; this is the vendor product identifier you received from Amazon in the purchase order.
`shipmentParameters .orderItemQuantities .quantity`	Required, for VDF	Integer	The number of units of this product
`shipmentParameters .packagingType .packagingWeight .weight`	Required, for VDF	Number	The value of the weight
`shipmentParameters .packagingType .packagingWeight .weightUnit`	Required, for VDF	String enumeration Values are: - `g` (gram) - `kg` (kilogram) - `oz` (ounce) - `lb` (pound)	The unit in which weight values are provided
`shipmentParameters .packagingType .packagingTypeId`	Optional, but required if `linearDimensions` is not provided	String Ex.: `ebd94f8b-d390-4c9c-987f-b88343f5bf45`	The `packagingTypeId` that was used for this package; when this value is present, the dimensions pre-configured by your organization are used. When this value is absent, `linearDimensions` is required.
`shipmentParameters .packagingType .linearDimensions .length`	Optional, but required if the `packagingTypeId` is not included	Number ($float) Ex.: `13`	The longest linear dimension (i.e., the longest side of a box or envelope)
`shipmentParameters .packagingType .linearDimensions .width`	Optional, but required if the `packagingTypeId` is not included	Number ($float) Ex.: `12`	The second longest linear dimension (i.e., the second longest side of a box or envelope)
`shipmentParameters .packagingType .linearDimensions .height`	Optional, but required if the `packagingTypeId` is not included	Number ($float) Ex.: `10`	The least long linear dimension (i.e., the shortest side of a box or envelope). Note on envelopes: This height should represent the highest product you would reasonably put in this envelope before losing more than 10% of the length of the envelope in other dimensions.
`shipmentParameters .packagingType .linearDimensions .linearUnit`	Optional, but required if the `packagingTypeId` is not included	String enumeration Values are: - `cm` (centimeter) - `in` (inch)	The unit in which linear dimensions are provided