Create a Shipment

Creating a Shipment

When you create a shipment, we respond with a shipment_id that is a unique identifier inside of Broad Reach. Additionally, we realize that you may have your own identifier, you can set this by setting the external_shipment_id field in the request body.

International Shipping

To ship internationally, your package will be required to go through customs in the destination country. You must know about laws, regulations, and customs procedures that preside over customs.

It's required that you send us a list of contents with their declared value while requesting your label. A custom's item comprises of the following properties

Create Shipment API Request Structure

Property	Type	Description	Units
order_number	string	The unique identifier for the order.
shipment_reference	string	A unique reference for the shipment.
customer_reference	string	The reference provided by the customer for the order.
label_type	string	The type of label to be used.
client_id	string	The unique identifier for the client.
processing_location	string	The code for the processing location.	The Broad Reach location in where the physical package will be processed. Possible values: SFO, MIA, JFK, PHL, ORD, LAX, SLC, TOR, CAL, BUF
contents	object	Contains details about the items in the shipment.
contents.items	array	List of items included in the shipment.
contents.items[].sku	string	The stock keeping unit identifier for the item.
contents.items[].description	string	A description of the item.
contents.items[].quantity	string	The quantity of the item.
contents.items[].price	string	The price of the item.
contents.items[].country_of_origin	string	The country of origin for the item.
contents.items[].harmonized_tariff_code	string	The harmonized tariff code for the item.
contents.items[].weight	string	The weight of the item.	lbs
contents.items[].dimensions	object	The dimensions of the item
contents.items[].dimensions.length	string	The length of the item.	inch
contents.items[].dimensions.height	string	The height of the item.	inch
contents.items[].dimensions.width	string	The width of the item.	inch
ship_to	object	Contains details about the shipment destination.
ship_to.first_name	string	The first name of the recipient.
ship_to.last_name	string	The last name of the recipient.
ship_to.phone	string	The phone number of the recipient.
ship_to.email	string	The email address of the recipient.
ship_to.address_line1	string	The first line of the recipient's address.
ship_to.address_line2	string	The second line of the recipient's address.
ship_to.country_code	string	The country code of the recipient's address.
ship_to.postal_code	string	The postal code of the recipient's address.
ship_to.city_locality	string	The city or locality of the recipient's address.
ship_to.state_province	string	The state or province of the recipient's address.
vendor	object	Contains details about the vendor.
vendor.name	string	The name of the vendor.
vendor.company	string	The company of the vendor.
vendor.phone	string	The phone number of the vendor.
vendor.email	string	The email address of the vendor.
vendor.address_line1	string	The first line of the vendor's address.
vendor.address_line2	string	The second line of the vendor's address.
vendor.city_locality	string	The city or locality of the vendor's address.
vendor.state_province	string	The state or province of the vendor's address.
vendor.postal_code	string	The postal code of the vendor's address.
vendor.country_code	string	The country code of the vendor's address.
ship_from	object	Contains details about the shipment origin.
ship_from.company_name	string	The name of the company shipping the item
ship_from.first_name	string	The first name of the person shipping the item.
ship_from.last_name	string	The last name of the person shipping the item.
ship_from.phone	string	The phone number of the person shipping the item.
ship_from.email	string	The email address of the person shipping the item.
ship_from.address_line1	string	The first line of the shipment origin address.
ship_from.address_line2	string	The second line of the shipment origin address.
ship_from.country_code	string	The country code of the shipment origin address.
ship_from.postal_code	string	The postal code of the shipment origin address.
ship_from.city_locality	string	The city or locality of the shipment origin address.
ship_from.state_province	string	The state or province of the shipment origin address.
packages	object	Contains details about the packages in the shipment.
packages.package_reference	string	The reference for the package.
packages.weight	string	The weight of the package.	lbs
packages.price	string	The price of the package.
packages.dimensions	object	The dimensions of the package.
packages.dimensions.length	string	The length of the package.
packages.dimensions.height	string	The height of the package.
packages.dimensions.width	string	The width of the package.
metadata	array	Additional metadata for the shipment.
metadata[].name	string	The name of the metadata field.
metadata[].type	string	The type of the metadata field.
metadata[].value	string	The value of the metadata field.

Request

curl -X POST "https://client.brdrch.com/api/v1/shipments" \
-u "cd3b3de84cc1ee040bf06512d233719c" \
-d '{}'

{
    "order_number": "BRDRCH001",
    "shipment_reference": "1daa0c22",
    "customer_reference": "7852413698",
    "service_type":"STD",
    "label_type": "zpl",
    "client_id": "BR19060736D",
    "processing_location": "LAX",
    "contents": {
        "items": [
            {
                "sku": "250523",
                "description": "Nike Air Max Plus",
                "quantity": "10",
                "price": "10.9000",
                "country_of_origin": "CA",
                "harmonized_tariff_code": "5002.30",
                "weight": "7",
                "dimensions": {
                    "length": "5",
                    "height": "6",
                    "width": "7"
                }
            },
            {
                "sku": "25052023",
                "description": "Nike Dunk Low Next Nature SE",
                "quantity": "10",
                "price": "11.9000",
                "country_of_origin": "CA",
                "harmonized_tariff_code": "5002.30",
                "weight": "8",
                "dimensions": {
                    "length": "5",
                    "height": "6",
                    "width": "7"
                }
            }
        ]
    },
    "ship_to": {
        "first_name": "James",
        "last_name": "Doe",
        "phone": "90233333422",
        "email": "",
        "address_line1": "2830 Black Bear Crescent",
        "address_line2": "",
        "country_code": "CA",
        "postal_code": "V1A 1A1",
        "city_locality": "Kimberley",
        "state_province": "   BC   "
    },
    "vendor": {
        "name": "Hotwheels",
        "company": "Mattel Inc.",
        "phone": "444-444-4444",
        "email": "[email protected]",
        "address_line1": "454 GATEWAY CRES SOUTH",
        "address_line2": "",
        "city_locality": "LETHBRIDGE",
        "state_province": "AB",
        "postal_code": "T1K4X2",
        "country_code": "CA"
    },
    "ship_from": {
        "company_name": "Company co. ltd.",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "9000000001",
        "email": "[email protected]",
        "address_line1": "1355 Boul Henri-Bourassa E",
        "address_line2": "",
        "country_code": "CA",
        "postal_code": "H1A 1A1",
        "city_locality": "Montréal",
        "state_province": "QC"
    },
    "packages": {
        "package_reference": "180523",
        "weight": "15",
        "price": "22.8000",
        "dimensions": {
            "length": "6",
            "height": "7",
            "width": "5"
        }
    },
    "metadata": [
        {
            "name": "notes",
            "type": "string",
            "value": "delivery notes"
        }
    ]
}

{
  "code": "InvalidArgument",
  "message": {
    "error": 1900,
    "message": "One or more parameters required for this request are either missing or have an invalid format.",
    "cause": "Team IDs array missing",
    "request": "bc41a8eb-a604-4a1c-aa5a-e86a975c141b"
  }
}

{
  "code": "InvalidContent",
  "message": {
    "error": 1000,
    "message": "The values of one or more parameters are invalid.",
    "cause": "Invalid phone number format",
    "request": "fff8ed50-4ca0-4ff9-9230-b73096eb8502"
  }
}

{
  "code": "InvalidContent",
  "message": {
    "error": 1004,
    "message": "The values of one or more parameters break a uniqueness constraint.",
    "cause": {
      "type": "duplicateKey",
      "key": "unknown",
      "value": "unknown"
    },
    "request": "3eafc877-278c-40d1-993b-2acf2575c7d8"
  }
}

Response

{
    "order_number": "BRDRCH001",
    "shipment_reference": "1daa0c22",
    "customer_reference": "7852413698",
    "service_type":"STD",
    "label_type": "zpl",
    "client_id": "BR19060736D",
    "processing_location": "LAX",
    "contents": {
        "items": [
            {
                "sku": "250523",
                "description": "Nike Air Max Plus",
                "quantity": 10,
                "price": 10.9,
                "country_of_origin": "CA",
                "harmonized_tariff_code": "5002.30",
                "weight": 7,
                "dimensions": {
                    "length": 5,
                    "height": 6,
                    "width": 7
                }
            },
            {
                "sku": "25052023",
                "description": "Nike Dunk Low Next Nature SE",
                "quantity": 10,
                "price": 11.9,
                "country_of_origin": "CA",
                "harmonized_tariff_code": "5002.30",
                "weight": 8,
                "dimensions": {
                    "length": 5,
                    "height": 6,
                    "width": 7
                }
            }
        ]
    },
    "ship_to": {
        "first_name": "James",
        "last_name": "Doe",
        "phone": "90233333422",
        "email": "",
        "address_line1": "2830 Black Bear Crescent",
        "address_line2": "",
        "country_code": "CA",
        "postal_code": "V1A 1A1",
        "city_locality": "Kimberley",
        "state_province": "BC"
    },
     "vendor": {
        "name": "Hotwheels",
        "company": "Mattel Inc.",
        "phone": "444-444-4444",
        "email": "[email protected]",
        "address_line1": "454 GATEWAY CRES SOUTH",
        "address_line2": "",
        "city_locality": "LETHBRIDGE",
        "state_province": "AB",
        "postal_code": "T1K4X2",
        "country_code": "CA"
    },
    "ship_from": {
        "company_name": "Company co. ltd.",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "9000000001",
        "email": "[email protected]",
        "address_line1": "1355 Boul Henri-Bourassa E",
        "address_line2": "",
        "country_code": "CA",
        "postal_code": "H1A 1A1",
        "city_locality": "Montréal",
        "state_province": "QC"
    },
    "packages": {
        "package_reference": "180523",
        "weight": 15,
        "price": 22.8,
        "dimensions": {
            "length": 6,
            "height": 7,
            "width": 5
        },
        "package_id": 19,
        "tracking_number": "BBRO0000180523673014",
        "carrier_tracking_number": "BBRO0000180523673014",
        "billable_weight": "15"
    },
    "metadata": [
        {
            "name": "notes",
            "type": "string",
            "value": "delivery notes"
        }
    ],
    "shipment_id": 19,
    "pre_process": false,
    "label_download": {
        "package_reference": "180523",
        "br_tracking_id": "BBRO0000180523673014",
        "carrier_tracking_number": "BBRO0000180523673014",
        "carrier_tracking_link": "",
        "zpl": "https://brdrch-storage.brdrch.com/argos/brdrch/zpl/a1fd9598-132d-4709-ba7e-d9fadc8f81db.zpl",
        "zpl_base64": "XlhBXkxSTl5NTl...",
        "sort_code": ""
    }
}