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. Conditional fields are described below.

Required fields

Request field	Details
`currencyCode`	Type: String Description: Currency in which all the rates for shipping carrier selection costs will be calculated
`shipmentParameters.destinationAddress .countryCode`	Type: String Description: The ISO 3166-1 country code for the destination address.
`shipmentParameters.destinationAddress .postalCode`	Type: String Description: A country-code-appropriate postal code for the destination address
`shipmentParameters.destinationAddress .addressType`	Type: String (enumeration) Values: `commercial` or `residential` Description: The type of location for the destination address
`shipmentParameters.shipFromAddress .countryCode`	Type: String Description: The ISO 3166-1 country code for the origin address
`shipmentParameters.shipFromAddress .postalCode`	Type: String Description: A country-code-appropriate postal code for the origin address
`shipmentParameters.orderSourceName`	Type: String Note: Required for SWA Description: The source of the order that was placed; if the source is Amazon Marketplace, you'll enter `amazon` for this value.
`shipmentParameters.orderItemQuantities .itemWeight.weight`	Type: Number (float) Note: Required for SWA Description: The value of the weight
`shipmentParameters.orderItemQuantities .itemWeight.weightUnit`	Type: String (enumeration) Values: `g` (gram), `kg` (kilogram), `oz` (ounce), `lb` (pound) Note: Required for SWA Description: The unit in which weight values are provided

Conditional fields

Request field	Details
`shipmentParameters.carrierProcessingId`	Type: String Condition: Required for SWA if the value provided for `orderSourceName` is `amazon` Description: Carrier-provided identifier; this is the purchase order number from the order step via Amazon.
`shipmentParameters.orderItemQuantities .hazmatInfo.packingInstructionCode`	Type: String (enumeration) Condition: Required for SWA for international shipments and shipments containing hazardous materials Values: `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]) Description: The specific packing instruction of the item being shipped
`shipmentParameters.orderItemQuantities .productId`	Type: String Example: `RN03947--Z43121` Condition: Required for international shipments and shipments containing hazardous materials Description: A product ID for the product being checked (ISBN, UPC, etc.)
`shipmentParameters.orderItemQuantities .quantity`	Type: Integer (int32) Example: `3` Condition: Required for international shipments and shipments containing hazardous materials Description: The number of units of the product
`shipmentParameters.packagingType .packagingTypeId`	Type: String Example: `ebd94f8b-d390-4c9c-987f-b88343f5bf45` Condition: Required if `linearDimensions` is not provided Description: 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`	Type: Number (float) Example: `13` Condition: Required if the `packagingTypeId` is not included Description: The longest linear dimension (i.e., the longest side of a box or envelope)
`shipmentParameters.packagingType .linearDimensions.width`	Type: Number (float) Example: `12` Condition: Required if the `packagingTypeId` is not included Description: The second longest linear dimension (i.e., the second longest side of a box or envelope)
`shipmentParameters.packagingType .linearDimensions.height`	Type: Number (float) Example: `10` Condition: Required if the `packagingTypeId` is not included Description: The least long linear dimension (i.e., the shortest side of a box or envelope) Note: For 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`	Type: String (enumeration) Values: `cm` (centimeter) or `in` (inch) Condition: Required if the `packagingTypeId` is not included Description: The unit in which linear dimensions are provided

Optional fields

Request field	Details
`generateLabel`	Type: Boolean Values: `true` or `false` Description: 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`	Type: String Description: Currency in which all the rates for shipping carrier selection costs will be calculated
`labelParameters.includeLabelImagesInResponse`	Type: Boolean Values: `true` or `false` Description: If `true`, the response will include the raw image data of the labels that were requested to be generated by the carrier.
`labelParameters.labelFormats`	Type: String (enumeration) Values: `pdf`, `png`, `zpl` Description: List of formats in which to generate the package label
`labelParameters.eligibleForManifest`	Type: Boolean Values: `true` or `false` Description: 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.

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. Conditional fields are described below.

Required fields

Request field	Details
`currencyCode`	Type: String Description: Currency in which all the rates for shipping carrier selection costs will be calculated
`shipmentParameters.destinationAddress .countryCode`	Type: String Description: The ISO 3166-1 country code for the destination address
`shipmentParameters.destinationAddress .postalCode`	Type: String Description: A country-code-appropriate postal code for the destination address
`shipmentParameters.destinationAddress .addressType`	Type: String (enumeration) Values: `commercial` or `residential` Description: The type of location for the destination address
`shipmentParameters.shipFromAddress .countryCode`	Type: String Description: The ISO 3166-1 country code for the origin address
`shipmentParameters.shipFromAddress.postalCode`	Type: String Description: A country-code-appropriate postal code for the origin address
`shipmentParameters.carrierProcessingId`	Type: String Note: Required for VDF Description: Carrier-provided identifier; this is the purchase order number from the order step via Amazon.
`shipmentParameters.packageReferenceIdentifier`	Type: String Note: Required for VDF Description: Used to correlate parcels to label documents from the carrier; this is the container identifier that Amazon uses as a parcel identifier.
`shipmentParameters.orderItemQuantities .orderItemReferenceIdentifier`	Type: Integer (int32) Note: Required for VDF Description: 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`	Type: String Note: Required for VDF Description: 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`	Type: Integer (int32) Note: Required for VDF Description: The number of units of this product
`shipmentParameters.packagingType .packagingWeight.weight`	Type: Number (float) Note: Required for VDF Description: The value of the weight
`shipmentParameters.packagingType .packagingWeight.weightUnit`	Type: String (enumeration) Values: `g` (gram), `kg` (kilogram), `oz` (ounce), `lb` (pound) Note: Required for VDF Description: The unit in which weight values are provided

Conditional fields

Request field	Details
`shipmentParameters.packagingType .packagingTypeId`	Type: String Example: `ebd94f8b-d390-4c9c-987f-b88343f5bf45` Condition: Required if `linearDimensions` is not provided. Description: 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`	Type: Number (float) Example: `13` Condition: Required if the `packagingTypeId` is not included. Description: The longest linear dimension (i.e., the longest side of a box or envelope)
`shipmentParameters.packagingType .linearDimensions.width`	Type: Number (float) Example: `12` Condition: Required if the `packagingTypeId` is not included Description: The second longest linear dimension (i.e., the second longest side of a box or envelope)
`shipmentParameters.packagingType .linearDimensions.height`	Type: Number (float) Example: `10` Condition: Required if the `packagingTypeId` is not included Description: The least long linear dimension (i.e., the shortest side of a box or envelope) Note: For 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`	Type: String (enumeration) Values: `cm` (centimeter) or `in` (inch) Condition: Required if the `packagingTypeId` is not included Description: The unit in which linear dimensions are provided

Optional fields

Request field	Details
`generateLabel`	Type: Boolean Values: `true` or `false` Description: 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`	Type: String Description: Currency in which all the rates for shipping carrier selection costs will be calculated
`labelParameters.includeLabelImagesInResponse`	Type: Boolean Values: `true` or `false` Description: If `true`, the response will include the raw image data of the labels that were requested to be generated by the carrier.
`labelParameters.labelFormats`	Type: String (enumeration) Values: `pdf`, `png`, `zpl` Description: List of formats in which to generate the package label
`labelParameters.eligibleForManifest`	Type: Boolean Values: `true` or `false` Description: 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.