Creating a Shipment

This JSON schema is your go-to guide for integrating with our system to create shipments, whether you're shipping internationally or domestically. It covers everything you need, from shipment references and customer info to package details. You can include multiple items in a shipment, each with its own SKU, price, and size. Plus, it’s got sections for shipping and vendor details, along with spots for any extra notes and label references. Basically, it’s everything you need to make sure your shipments get processed smoothly, labels get generated, and tracking is a breeze.

Create Shipment API Request Structure

Property	Type	Description	Units
shipment_reference	String	Unique identifier for the shipment.
additional_shipment_reference	String	Additional reference number for the shipment.
customer_reference	String	Customer’s reference number.
process_label	Boolean	Indicates whether to process and generate a label (true/false).
label_type	String	Type of label to be generated. Options: "pdf", "zpl".
service_code	String	Code representing the shipping service to be used.
store_id	String	Identifier for the store or location from which the shipment is originating.
client_id	String	Unique identifier for the client.
processing_location	String	Location where the shipment will be processed (e.g., "LAX").
pre_process	Boolean	Indicates if the shipment should be pre-processed before the final processing (true/false).
shipment_type	String	Type of shipment. Options: "domestic", "international".
transaction_type	String	Type of transaction. Example: "B2BDDP" (Business to Business Delivery Duty Paid).
dangerous_goods	Boolean	Indicates if the shipment contains dangerous goods (true/false).
contents.items[]	Array of Objects	Array of items contained within the shipment.
contents.items[].sku	String	Stock Keeping Unit identifier for the item.
contents.items[].quantity	Integer	Quantity of the item being shipped.
contents.items[].price	String	Price of a single item.
contents.items[].currency	String	Currency code (e.g., "USD").
contents.items[].description	String	Description of the item.
contents.items[].country_of_origin	String	Country where the item was manufactured or produced.
contents.items[].harmonized_tariff_code	String	Harmonized Tariff Code for the item.
contents.items[].original_harmonized_code	String	Original harmonized code used before any modifications.
contents.items[].package_reference	String	Reference for the package containing this item.
contents.items[].product	String	Name of the product.
contents.items[].product_code	String	Code representing the product.
contents.items[].weight	String	Weight of the item (typically in pounds).	LBS
contents.items[].dimensions	Object	Dimensions of the item.
contents.items[].dimensions.length	String	Length of the item in the package.	inch
contents.items[].dimensions.height	String	Height of the item in the package.	inch
contents.items[].dimensions.width	String	Width of the item in the package.	inch
ship_to	Object	Object containing the recipient's shipping information.
ship_to.name	String	Name of the recipient.
ship_to.phone	String	Phone number of the recipient.
ship_to.email	String	Email address of the recipient.
ship_to.address_line1	String	First line of the recipient's address.
ship_to.address_line2	String	Second line of the recipient's address (optional).
ship_to.city_locality	String	City or locality of the recipient's address.
ship_to.state_province	String	State or province of the recipient's address.
ship_to.postal_code	String	Postal or ZIP code of the recipient's address.
ship_to.country_code	String	ISO country code of the recipient's address.
vendor	Object	Object containing the vendor's information.
vendor.name	String	Name of the vendor.
vendor.company	String	Company name of the vendor.
vendor.phone	String	Phone number of the vendor.
vendor.email	String	Email address of the vendor.
vendor.address_line1	String	First line of the vendor's address.
vendor.address_line2	String	Second line of the vendor's address (optional).
vendor.city_locality	String	City or locality of the vendor's address.
vendor.state_province	String	State or province of the vendor's address.
vendor.postal_code	String	Postal or ZIP code of the vendor's address.
vendor.country_code	String	ISO country code of the vendor's address.
packages[]	Array of Objects	Array of packages included in the shipment.
packages[].package_reference	String	Unique reference for the package.
packages[].br_tracking_id	String	Tracking ID for the package.
packages[].weight	String	Weight of the package.	lbs
packages[].dimensions	Object	Dimensions of the package.
packages[].dimensions.length	String	Length of the package.	inch
packages[].dimensions.height	String	Height of the package.	inch
packages[].dimensions.width	String	Width of the package.	inch
metadata[]	Array of Objects	Array of metadata objects for additional information.
metadata[].name	String	Name of the metadata field.
metadata[].type	String	Type of the metadata value (e.g., "string", "number").
metadata[].value	String	Value of the metadata field.
label_reference[]	Array of Objects	Array of references related to the labels.
label_reference[].reference	String	Reference identifier for the label.

Request

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

{
  "shipment_reference": "1daa0c22",
  "additional_shipment_reference": "112302152233",
  "customer_reference": "1451451547",
  "process_label": true,
  "label_type": "pdf", // "zpl"
  "service_code": "BRCExp",
  "store_id":"24",
  "client_id": "12546254",
  "processing_location": "LAX",
  "pre_process": true,
  "shipment_type": "domestic",
  "transaction_type": "B2BDDP",
  "dangerous_goods": true,
  "contents": {
    "items": [
      {
        "sku": "4225-776-3234",
        "quantity": 4,
        "price": 10.99,
        "currency": "USD",
        "description": "Mens Polo Shirt Cotton",
        "country_of_origin": "US",
        "harmonized_tariff_code": "4817.20",
        "original_harmonized_code": "234434",
        "package_reference": "ABC1234",      
        "weight": 10,
        "dimensions": {
           "length": 10,
           "height": 10,
           "width": 10
        }
      }
    ]
  },
  "ship_to": {
    "name": "James Cameron",
    "phone": "555-555-5555",
    "email": "[email protected]",
    "address_line1": "655 Queen Street West",
    "address_line2": "apt 123",
    "city_locality": "Toronto",
    "state_province": "ON",
    "postal_code": "M6J 1E4",
    "country_code": "CA"
  },
  "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"
  },
  "packages": [
    {
      "package_reference": "ABC1234",
      "br_tracking_id":"BR23445634532",
      "weight": 10,
      "dimensions": {
        "length": 10,
        "height": 10,
        "width": 10
      },
      "product" : "e-PAQ Select Pre Alert Canada FTA",
      "product_code": "A1207",  
    },
    {
      "package_reference": "4567",
      "br_tracking_id":"BR23445634533",
      "weight": 10,
      "dimensions": {
        "length": 10,
        "height": 10,
        "width": 10
      },
      "product" : "e-PAQ Select Pre Alert Canada FTA",
      "product_code": "A1207",  
    }
  ],
  "metadata": [
    {
      "name": "notes",
      "type": "string",
      "value": "delivery notes"
    }
  ],
  "label_reference":[
    {"reference":"reference one"},
    {"reference":"reference two"},
    {"reference":"reference three"}
  ]
}

{
  "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

{
  "shipment_reference": "1daa0c22",
  "additional_shipment_reference": "112302152233",
  "customer_reference": "1451451547",
  "process_label": true,
  "label_type": "pdf",
  "service_code": "BRCExp",
  "store_id":"24",
  "client_id": "12546254",
  "processing_location": "LAX",
  "shipment_type": "domestic",
  "transaction_type": "B2BDDP",
  "dangerous_goods": true,
  "contents": {
    "items": [
      {
        "sku": "4225-776-3234",
        "quantity": 4,
        "price": 10.99,
        "currency": "USD",
        "description": "Mens Polo Shirt Cotton",
        "country_of_origin": "US",
        "harmonized_tariff_code": "4817.20",
        "package_reference": "ABC1234",
        "weight": 10,
        "dimensions": {
           "length": 10,
           "height": 10,
           "width": 10
        }
      }
    ]
  },
  "ship_to": {
    "name": "James Cameron",
    "phone": "555-555-5555",
    "email": "[email protected]",
    "address_line1": "655 Queen Street West",
    "address_line2": "apt 123",
    "city_locality": "Toronto",
    "state_province": "ON",
    "postal_code": "M6J 1E4",
    "country_code": "CA"
  },
  "packages": [
    {
      "package_reference": "ABC1234",
      "weight": 10,
      "dimensions": {
        "length": 10,
        "height": 10,
        "width": 10
      },
      "product" : "e-PAQ Select Pre Alert Canada FTA",
      "product_code": "A1207",
      "sort_code":"BRE",
      "package_id":123,
      "carrier_tracking_number":"123456789012BR8447"
    },
    {
      "package_reference": "4567",
      "weight": 10,
      "dimensions": {
        "length": 10,
        "height": 10,
        "width": 10
      },
      "product" : "e-PAQ Select Pre Alert Canada FTA",
      "product_code": "A1207",
      "sort_code":"BRE",
      "package_id":321,
      "carrier_tracking_number":"123456789012BR8448"
    }
  ],
  "metadata": [
    {
      "name": "notes",
      "type": "string",
      "value": "delivery notes"
    }
  ],
  "label_reference":[
    {"reference":"reference one"},
    {"reference":"reference two"},
    {"reference":"reference three"}
  ],
  "label_download": [
    {
     "package_reference": "ABC1234",
     "br_tracking_id":"BR23445634532",
     "pdf": "https://api.brdrch.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.pdf",
     "pdf_base64": "1791234h1239412h34-219u349u9128347123984h1234h-912834y12h381234yh123812348"
    },
    {
     "package_reference": "4567",
     "br_tracking_id":"BR23445634532",
     "pdf": "https://api.brdrch.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.pdf",
     "pdf_base64": "1791234h1239412h34-219u349u9128347123984h1234h-912834y12h381234yh123812348"
    },
    {
      "br_tracking_id": "BR23445634532",
      "carrier_tracking_number": "123456789012BR8447",
      "carrier_tracking_link": "https://www.canadapost-postescanada.ca/track-reperage/en#/search?searchFor=123456789012BR8447",
      "zpl": "https://emaildata.dev.brdrch.com/argos/canadapost/zpl/123456789012BR8447.zpl",
      "zpl_base64": "XlhBDQpeQ0kxMw0KXk1..."
    }
   ]
}