# 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](https://docs.shipium.com/docs/carrier-and-method-selection-and-shipment-label-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](https://docs.shipium.com/docs/carrier-and-method-selection-and-shipment-label-api) with the required fields for Amazon - Ship With Amazon included. This example is for a single-parcel shipment; for [multi-parcel shipments](https://docs.shipium.com/docs/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](https://docs.shipium.com/docs/non-us-address-formats).

Fields not defined in the table following this sample request are described in the [request fields table](https://docs.shipium.com/docs/carrier-and-method-selection-and-shipment-label-api#request-and-response-fields-for-api-calls) in the API documentation.

JSON

```json
{
  "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](https://docs.shipium.com/docs/carrier-and-method-selection-and-shipment-label-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. Conditional fields are described below.

## Required fields

| Request field | Details |
| --- | --- |
| `currencyCode` | **Type:** String<br>**Description:** Currency in which all the rates for shipping carrier selection costs will be calculated |
| `shipmentParameters.destinationAddress                     .countryCode` | **Type:** String<br>**Description:** The [ISO 3166-1 country code](https://docs.shipium.com/docs/non-us-address-formats) for the destination address. |
| `shipmentParameters.destinationAddress                     .postalCode` | **Type:** String<br>**Description:** A country-code-appropriate postal code for the destination address |
| `shipmentParameters.destinationAddress                     .addressType` | **Type:** String (enumeration)<br>**Values:**`commercial` or `residential`<br>**Description:** The type of location for the destination address |
| `shipmentParameters.shipFromAddress                     .countryCode` | **Type:** String<br>**Description:** The [ISO 3166-1 country code](https://docs.shipium.com/docs/non-us-address-formats) for the origin address |
| `shipmentParameters.shipFromAddress                     .postalCode` | **Type:** String<br>**Description:** A country-code-appropriate postal code for the origin address |
| `shipmentParameters.orderSourceName` | **Type:** String<br>**Note:** Required for SWA<br>**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)<br>**Note:** Required for SWA<br>**Description:** The value of the weight |
| `shipmentParameters.orderItemQuantities                     .itemWeight.weightUnit` | **Type:** String (enumeration)<br>**Values:**`g` (gram), `kg` (kilogram), `oz` (ounce), `lb` (pound)<br>**Note:** Required for SWA<br>**Description:** The unit in which weight values are provided |

## Conditional fields

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

## Optional fields

| Request field | Details |
| --- | --- |
| `generateLabel` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** When `true`, a request to the selected carrier will be sent to generate a [label](https://docs.shipium.com/docs/carrier-shipment-label-flow) 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<br>**Description:** Currency in which all the rates for shipping carrier selection costs will be calculated |
| `labelParameters.includeLabelImagesInResponse` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** If `true`, the response will include the raw image data of the [labels](https://docs.shipium.com/docs/carrier-shipment-label-flow) that were requested to be generated by the carrier. |
| `labelParameters.labelFormats` | **Type:** String (enumeration)<br>**Values:**`pdf`, `png`, `zpl`<br>**Description:** List of formats in which to generate the [package label](https://docs.shipium.com/docs/carrier-shipment-label-flow) |
| `labelParameters.eligibleForManifest` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** When `true`, or null, this label will be included in end-of-day and scheduled [manifests](https://docs.shipium.com/docs/shipment-manifesting); `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](https://docs.shipium.com/docs/carrier-and-method-selection-and-shipment-label-api) with the required fields for Amazon - Vendor Direct Fulfillment included. This example is for a single-parcel shipment; for [multi-parcel shipments](https://docs.shipium.com/docs/multi-parcel-shipments), the fields included in `shipmentParameters` would instead be included in `multiParcelShipmentParameters`.

JSON

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](https://docs.shipium.com/docs/carrier-and-method-selection-and-shipment-label-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. Conditional fields are described below.

## Required fields

| Request field | Details |
| --- | --- |
| `currencyCode` | **Type:** String<br>**Description:** Currency in which all the rates for shipping carrier selection costs will be calculated |
| `shipmentParameters.destinationAddress                     .countryCode` | **Type:** String<br>**Description:** The [ISO 3166-1 country code](https://docs.shipium.com/docs/non-us-address-formats) for the destination address |
| `shipmentParameters.destinationAddress                     .postalCode` | **Type:** String<br>**Description:** A country-code-appropriate postal code for the destination address |
| `shipmentParameters.destinationAddress                     .addressType` | **Type:** String (enumeration)<br>**Values:**`commercial` or `residential`<br>**Description:** The type of location for the destination address |
| `shipmentParameters.shipFromAddress                     .countryCode` | **Type:** String<br>**Description:** The [ISO 3166-1 country code](https://docs.shipium.com/docs/non-us-address-formats) for the origin address |
| `shipmentParameters.shipFromAddress.postalCode` | **Type:** String<br>**Description:** A country-code-appropriate postal code for the origin address |
| `shipmentParameters.carrierProcessingId` | **Type:** String<br>**Note:** Required for VDF<br>**Description:** Carrier-provided identifier; this is the purchase order number from the order step via Amazon. |
| `shipmentParameters.packageReferenceIdentifier` | **Type:** String<br>**Note:** Required for VDF<br>**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)<br>**Note:** Required for VDF<br>**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<br>**Note:** Required for VDF<br>**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)<br>**Note:** Required for VDF<br>**Description:** The number of units of this product |
| `shipmentParameters.packagingType                     .packagingWeight.weight` | **Type:** Number (float)<br>**Note:** Required for VDF<br>**Description:** The value of the weight |
| `shipmentParameters.packagingType                      .packagingWeight.weightUnit` | **Type:** String (enumeration)<br>**Values:**`g` (gram), `kg` (kilogram), `oz` (ounce), `lb` (pound)<br>**Note:** Required for VDF<br>**Description:** The unit in which weight values are provided |

## Conditional fields

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

## Optional fields