Introduction

Welcome to the Vanlo API! You can use our API to verify addresses, rate and create shipments and shipping labels, and monitor tracking codes.

This is an EasyPost-compatible API, so switching from EasyPost to Vanlo is as simple as changing your request URL and API key!

We have client libraries / SDKs for Ruby, Python, PHP and C#. You can view code examples on the right, and you can switch the programming language of the examples with the tabs in the top right.

Request URL

Test: https://test.vanlo.com/api/v1/...

Production: https://www.vanlo.com/api/v1/...

Authentication

Authentication is performed by including your API key with every request (cURL), or by setting it globally in one of our client libraries / SDKs:

curl -X METHOD https://www.vanlo.com/api/v1/... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'

Vanlo.api_key = 'VANLO_API_KEY'

import vanlo

vanlo.api_key = 'VANLO_API_KEY'

require_once("/path/to/lib/vanlo.php");

\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

using Vanlo;

ClientManager.SetCurrent("VANLO_API_KEY");

Make sure to replace VANLO_API_KEY with your API key.

Vanlo uses API keys for authentication and identification.

Vanlo expects for the API key to be included in all API requests as an authorization bearer token:

Authorization: Bearer VANLO_API_KEY

Test Environment

In the client libraries / SDKs you can access the test environment by setting the API base value before performing any actions:

curl -X METHOD https://test.vanlo.com/api/v1/... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'

Vanlo.api_key = 'VANLO_API_KEY'
Vanlo.api_base = 'https://test.vanlo.com/api/v1'

import vanlo

vanlo.api_key = 'VANLO_API_KEY'
vanlo.api_base = 'https://test.vanlo.com/api/v1'

require_once("/path/to/lib/vanlo.php");

\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');
\Vanlo\Vanlo::setApiBase('https://test.vanlo.com/api/v1');

using Vanlo;

ClientManager.SetCurrent("VANLO_API_KEY", "https://test.vanlo.com/api/v1");

Vanlo offers a test environment which you can develop against without incurring any real charges or generating any live postage labels or tracking codes.

You can find your test API Key by logging in to the Vanlo Dashboard, entering "test mode" by clicking the toggle in the bottom of the left side bar, and then visiting the API Keys page: https://dashboard.vanlo.com/apikey

Shipments

Shipment Object

Parameter	Type	Specification
id	string	Unique identifier, begins with "shp_"
object	string	"Shipment"
usps_zone	integer	The USPS zone of the shipment, if purchased with USPS
to_address	<Address>	The destination address
from_address	<Address>	The origin address
parcel	<Parcel>	The dimensions and weight of the package
customs_info	<CustomsInfo>	Information for the processing of customs
rates	[<Rate>...]	All associated Rate objects
selected_rate	<Rate>	The specific rate purchased for the shipment, or null if unpurchased or purchased through another mechanism
tracker	<Tracker>	The associated Tracker object
postage_label	<PostageLabel>	The associated PostageLabel object
refund_status	string	The current status of the shipment refund process. Possible values are "submitted", "refunded", "rejected"
tracking_code	string	If purchased, the tracking code will appear here as well as within the Tracker object
status	string	The current tracking status of the shipment
is_return	boolean	Set true to create as a return
options	<Options>	All of the options passed to the shipment, discussed in more depth below
return_address	<Address>	Optional return address, if different from the origin address
buyer_address	<Address>	Optional buyer address, if different from the destination address
usps_tracking_code	string	USPS tracking code, present when purchased with a USPS service
created_at	datetime	When the shipment was created
updated_at	datetime	When the shipment was last updated

Rate Object

Parameter	Type	Specification
id	string	Unique identifier, begins with 'rate_'
object	string	"Rate"
carrier	string	name of carrier
service	string	name of service
rate	string	the actual rate quote for this service
delivery_date	string	date for delivery
delivery_date_guaranteed	boolean	indicates if delivery window is guaranteed (true) or not (false)
delivery_days	string	delivery days for this service
created_at	datetime

PostageLabel Object

Parameter	Type	Specification
id	string	Unique identifier, begins with 'pl_'
object	string	"PostageLabel"
integrated_form	string
label_date	string	Date on label
label_epl2_url	string	URL for epl2 label(if applicable)
label_pdf_url	string	URL for PDF label(if applicable)
label_zpl_url	string	URL for ZPL label(if applicable)
label_resolution	string	Resolution of label image
label_size	string	size of label
label_type	string	Type of label
label_file_type	string	Label file type
label_url	string	URL of label image
created_at	datetime
updated_at	datetime

Options Object

Parameter	Type	Specification
carrier_insurance_amount	float	Set the amount in USD to be covered by insurance. USPS only.
create_and_buy	boolean	Set this to true to create and buy the label in one pass with the service given in the same request.
delivery_confirmation	string	Request a signature. Look for valid values in the block below. NO_SIGNATURE is the default.
fetch_express_delivery_date	boolean	Set to true to get the guaranteed delivery date for USPS Express service.
hazmat	string	Set this if the package includes hazardous materials. Look for valid values in the block below.
is_return	boolean	Set this to true if you want to use the return service sub-type.
label_format	string	Supported label formats are "PNG", "PDF", "ZPL", and "EPL2". "PNG" is the only format that allows for conversion.
label_size	string	Physical size of the label to be printed in inches. "4X6" or "8.5X11". Default is "4X6" which is the standard size suitable for label writers. "8.5X11" provides the same physical size of the label and adds blank space around for lazer printers and such.
label_date	string	Set the date that will appear on the postage label. Accepts ISO 8601 formatted string including time zone offset. Vanlo stores all dates as UTC time.
machinable	boolean	Default is true. Set this to false to mark the package as non-machinable. Applicable for USPS First shipments.
postage_label_inline	boolean	Set this to true to receive a base64-encoded label image in the label_file field of the response instead of a label url. Combine with create_and_buy option to get the label image with a single request.
special_rates_eligibility	string	This option allows you to request restrictive rates from USPS. Can set to 'USPS.MEDIAMAIL' or 'USPS.LIBRARYMAIL'.
print_custom	[<PrintCustom>...]	You can optionally print custom messages on labels. The locations of these fields show up on different spots on the carrier's labels. Up to 3 items.
FedEx specific
endorsement	string	Ancillary endorsement request for Smartpost. See below for values.
smartpost_manifest	string
smartpost_hub	string	Smartpost hub ID.
saturday_delivery	boolean	Set this to true for FedEx shipments to request for saturday delivery.
UniUni specific
hub_id	integer	Pickup warehouse ID. Required for UniUni shipments. See the hub sheet at docs.uniuni.com for valid values.
batch_number	string	Associate the shipment with a batch.
tracking_number	string	You can set your custom tracking code using this option. Make sure it's unique.
bag_number	string	Print the bag number on the label.
buzz_code	string	Print the recipient buzz code on the label.
total_value	float	Set the value of the shipment contents for help with lost packages.
driver_notes	string	Print the notes for the driver on the label.
danger_type	integer	In UniUni an analog of hazmat is set as a sum of the numbers representing contents properties: 1: Fragile; 8: Has battery; 16: Sensitive; 32: Has Liquid. For example, if it has all the hazardous properties at the same time, pass 57.

Valid option values

Valid values for delivery_confirmation:

• NO_SIGNATURE
  
• SIGNATURE
  
• ADULT_SIGNATURE
  
• SIGNATURE_RESTRICTED
  
• ADULT_SIGNATURE_RESTRICTED
  

USPS values for hazmat:

• PRIMARY_CONTAINED
  
• PRIMARY_PACKED
  
• PRIMARY
  
• SECONDARY_CONTAINED
  
• SECONDARY_PACKED
  
• SECONDARY
  
• ORMD
  
• LIMITED_QUANTITY
  
• LITHIUM
  
• AIR_ELIGIBLE_ETHANOL
  
• CLASS_1
  
• CLASS_3
  
• CLASS_7
  
• CLASS_8_CORROSIVE
  
• CLASS_8_WET_BATTERY
  
• CLASS_9_NEW_LITHIUM_INDIVIDUAL
  
• CLASS_9_USED_LITHIUM
  
• CLASS_9_NEW_LITHIUM_DEVICE
  
• CLASS_9_DRY_ICE
  
• CLASS_9_UNMARKED_LITHIUM
  
• CLASS_9_MAGNETIZED
  
• DIVISION_4_1
  
• DIVISION_5_1
  
• DIVISION_5_2
  
• DIVISION_6_1
  
• DIVISION_6_2
  
• EXCEPTED_QUANTITY_PROVISION
  
• GROUND_ONLY
  
• ID8000
  
• LIGHTERS
  
• SMALL_QUANTITY_PROVISION
  

Valid values for endorsement:

• ADDRESS_CORRECTION
  
• CARRIER_LEAVE_IF_NO_RESPONSE
  
• CHANGE_SERVICE
  
• FORWARDING_SERVICE
  
• RETURN_SERVICE
  

PrintCustom Object

Parameter	Type	Specification
name	string	First part of text to print on label
value	string	Last part of text to print on label
barcode	boolean	print the value as barcode (USPS only)

Create a Shipment

curl -X POST https://www.vanlo.com/api/v1/shipments \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'shipment[to_address][name]=To Name' \
  -d 'shipment[to_address][street1]=To Street 1' \
  -d 'shipment[to_address][city]=To City' \
  -d 'shipment[to_address][state]=CA' \
  -d 'shipment[to_address][zip]=90277' \
  -d 'shipment[to_address][country]=US' \
  -d 'shipment[to_address][phone]=4151234567' \
  -d 'shipment[to_address][email]=to@example.com' \
  -d 'shipment[from_address][name]=From Name' \
  -d 'shipment[from_address][company]=From Company' \
  -d 'shipment[from_address][street1]=From Street 1' \
  -d 'shipment[from_address][street2]=From Street 2' \
  -d 'shipment[from_address][city]=From City' \
  -d 'shipment[from_address][state]=CA' \
  -d 'shipment[from_address][zip]=94104' \
  -d 'shipment[from_address][country]=US' \
  -d 'shipment[from_address][phone]=4157654321' \
  -d 'shipment[from_address][email]=from@example.com' \
  -d 'shipment[parcel][length]=8.1' \
  -d 'shipment[parcel][width]=7.2' \
  -d 'shipment[parcel][height]=6' \
  -d 'shipment[parcel][weight]=65.9'

# OR reference previously created objects

curl -X POST https://www.vanlo.com/api/v1/shipments \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'shipment[to_address][id]=adr_...' \
  -d 'shipment[from_address][id]=adr_...' \
  -d 'shipment[parcel][id]=prcl_...' \
  -d 'shipment[customs_info][id]=cstinfo_...'

require 'vanlo'
Vanlo.api_key = "VANLO_API_KEY"

Vanlo::Shipment.create(
  to_address: {
    name: 'To Name',
    street1: 'To Street',
    city: 'To City',
    state: 'CA',
    zip: '90277',
    country: 'US',
    phone: '4151234567',
    email: 'to@example.com'
  },
  from_address: {
    name: 'From Name',
    company: 'From Company',
    street1: 'From Street 1',
    street2: 'From Street 2',
    city: 'From City',
    state: 'CA',
    zip: '94104',
    country: 'US',
    phone: '4157654321',
    email: 'from@example.com'
  },
  parcel: {
    length: 8.1,
    width: 7.2,
    height: 6,
    weight: 65.9
  }
)

# OR reference previously created objects

to_address = Vanlo::Address.create(...)
from_address = Vanlo::Address.create(...)
parcel = Vanlo::Parcel.create(...)
customs_info = Vanlo::CustomsInfo.create(...)

Vanlo::Shipment.create(
  to_address: to_address,
  from_address: from_address,
  parcel: parcel,
  customs_info: customs_info
)

import vanlo
vanlo.api_key = "VANLO_API_KEY"

shipment = vanlo.Shipment.create(
  to_address={
    "name": 'To Name',
    "street1": 'To Street',
    "city": 'To City',
    "state": 'CA',
    "zip": '90277',
    "country": 'US',
    "phone": '4151234567',
    "email": 'to@example.com'
  },
  from_address={
    "name": 'From Name',
    "company": 'From Company',
    "street1": 'From Street 1',
    "street2": 'From Street 2',
    "city": 'From City',
    "state": 'CA',
    "zip": '94104',
    "country": 'US',
    "phone": '4157654321',
    "email": 'from@example.com'
  },
  parcel={
    "length": 8.1,
    "width": 7.2,
    "height": 6,
    "weight": 65.9
  }
)

# OR reference previously created objects

to_address = vanlo.Address.create(...)
from_address = vanlo.Address.create(...)
parcel = vanlo.Parcel.create(...)
customs_info = vanlo.CustomsInfo.create(...)

shipment = vanlo.Shipment.create(
  to_address=to_address,
  from_address=from_address,
  parcel=parcel,
  customs_info=customs_info
)

require_once("path/to/lib/vanlo.php");
\Vanlo\Vanlo::setApiKey("VANLO_API_KEY");

$shipment = \Vanlo\Shipment::create(array(
  "to_address" => array(
    'name' => 'To Name',
    'street1' => 'To Street',
    'city' => 'To City',
    'state' => 'CA',
    'zip' => '90277',
    'country' => 'US',
    'phone' => '4151234567',
    'email' => 'to@example.com'
  ),
  "from_address" => array(
    'name' => 'From Name',
    'company' => 'From Company',
    'street1' => 'From Street 1',
    'street2' => 'From Street 2',
    'city' => 'From City',
    'state' => 'CA',
    'zip' => '94104',
    'country' => 'US',
    'phone' => '4157654321',
    'email' => 'from@example.com'
  ),
  "parcel" => array(
    "length" => 8.1,
    "width" => 7.2,
    "height" => 6,
    "weight" => 65.9
  )
));

# OR reference previously created objects

$to_address = \Vanlo\Address::create(...);
$from_address = \Vanlo\Address::create(...);
$parcel = \Vanlo\Parcel::create(...);
$customs_info = \Vanlo\CustomsInfo::create(...);

$shipment = \Vanlo\Shipment::create(array(
  "to_address" => $to_address,
  "from_address" => $from_address,
  "parcel" => $parcel,
  "customs_info" => $customs_info
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Address fromAddress = new Address() {
    name = "From Name",
    company = "From Company",
    street1 = "From Street 1",
    street2 = "From Street 2",
    city = "From City",
    state = "CA",
    zip = "94104",
    country = "US",
    phone = "4157654321",
    email = "from@example.com"
 };

Address toAddress = new Address() {
    name = "To Name",
    street1 = "To Street",
    city = "To City",
    state = "CA",
    zip = "90277",
    country = "US",
    phone = "4151234567",
    email = "to@example.com"

};

Parcel parcel = new Parcel() {
    length = 8.1,
    width = 7.2,
    height = 6,
    weight = 65.9
};

Shipment shipment = new Shipment() {
    from_address = fromAddress,
    to_address = toAddress,
    parcel = parcel,
};

shipment.Create();

// OR reference previously created objects

Address to_address = Address.Create(...);
Address from_address = Address.Create(...);
Parcel parcel = Parcel.Create(...);
CustomsInfo customs_info = CustomsInfo.Create(...);

Shipment shipment = new Shipment() {
    to_address = to_address,
    from_address = from_address,
    parcel = parcel,
    customs_info = customs_info
};

shipment.Create();

The above command returns JSON structured like this:

{
  "id": "shp_...",
  "object": "Shipment",
    "to_address": {
    "id": "adr_...",
    "object": "Address",
    "name": "To Name",
    "company": null,
    "street1": "To Street",
    "street2": null,
    "city": "To City",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "4151234567",
    "residential": null,
    "email": "to@example.com",
    "created_at": "2019-04-22T05:39:56Z",
    "updated_at": "2019-04-22T05:39:56Z"
  },
  "from_address": {
    "id": "adr_...",
    "object": "Address",
    "name": "From Name",
    "company": "From Company",
    "street1": "From Street 1",
    "street2": "From Street 2",
    "city": "From City",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4157654321",
    "email": "from@example.com",
    "residential": null,
    "created_at": "2019-04-22T05:39:57Z",
    "updated_at": "2019-04-22T05:39:57Z"
  },
  "parcel": {
    "id": "prcl_...",
    "object": "Parcel",
    "length": 8.2,
    "width": 7.1,
    "height": 6.0,
    "predefined_package": null,
    "weight": 65.9,
    "created_at": "2019-04-22T05:39:57Z",
    "updated_at": "2019-04-22T05:39:57Z"
  },
  "rates": [
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "ParcelSelect",
      "rate": "9.02",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 5
    },
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "Express",
      "rate": "40.16",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": null
    },
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "Priority",
      "rate": "7.91",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 2
    }
  ],
  "selected_rate": null,
  "postage_label": null,
  "tracking_code": null,
  "refund_status": null,
  "created_at": "2019-04-22T05:40:57Z",
  "updated_at": "2019-04-22T05:40:57Z"
}

Shipments are the central objects of the Vanlo API. You will use them to send origin and destination addresses, parcel characteristics, and information for customs(when required).

Once a shipment is created we will attach the available shipping services (as Rate objects), and then a shipping label can be purchased by 'buying' one of the Rates.

An origin Address, destination Address, and Parcel are required for domestic rating and shipping. You will also have to include CustomsInfo whenever a shipment requires it (or include it on all shipments to simplify application logic).

The associated Rates, Tracker, and PostageLabel are generated by Vanlo and cannot be modified directly.

HTTP Request

POST https://www.vanlo.com/api/v1/shipments

Create Shipment Request Parameters

Parameter	Type	Required?	Specification
from_address	<Address>	Required	Your warehouse address
to_address	<Address>	Required	Recipient address
parcel	<Parcel>	Required	Package properties
customs_info	<CustomsInfo>	Optional	Only required for international shipments and shipments to APO/DPO/FPO.
service	string	Optional	When given along with create_and_buy option, the label is purchased immediately.
carrier	string	Optional	The carrier name to ship. Default value is USPS.
carrier_accounts	[string...]	Optional	One or more Carrier Account ids to get rates from. Default value is your default USPS account.
reference	string	Optional	Arbitrary string that you can use later to look up the shipment or filter all the shipments with the same reference to include in a ScanForm.
custom_id	string	Optional	Arbitrary but unique string that you can use later to look up the shipment.
return_address	<Address>	Optional	Distinct return address if it differs from from_address.
buyer_address	<Address>	Optional	Distinct buyer address if it differs from to_address.
parcels	[<Parcel>...]	Optional	FedEx only. Pass multiple parcel objects instead of a single object in the parcel field to create a multi-piece shipment.

Buy a Shipment

curl -X POST https://www.vanlo.com/api/v1/shipments/shp_.../buy \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'rate[id]=rate_...'

require 'vanlo'
Vanlo.api_key = "VANLO_API_KEY"

shipment = Vanlo::Shipment.retrieve("shp_...")
shipment.buy(rate: shipment.lowest_rate)

import vanlo
vanlo.api_key = "VANLO_API_KEY"

shipment = vanlo.Shipment.retrieve("shp_...")
shipment.buy(rate=shipment.lowest_rate())

require_once("path/to/lib/vanlo.php");
\Vanlo\Vanlo::setApiKey("VANLO_API_KEY");

$shipment = \Vanlo\Shipment::retrieve("shp_...");
$shipment->buy(array(
  'rate'      => $shipment->lowest_rate()
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Shipment shipment = Shipment.Retrieve("shp...");
Rate lowestRate = shipment.LowestRate();

shipment.Buy(lowestRate);

The above command returns JSON structured like this:

{
  "id": "shp_...",
  "object": "Shipment",
  "to_address": {
    "id": "adr_...",
    "object": "Address",
    "name": "To Name",
    "company": null,
    "street1": "To Street",
    "street2": null,
    "city": "To City",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "4151234567",
    "residential": null,
    "email": "to@example.com",
    "created_at": "2019-04-22T05:39:56Z",
    "updated_at": "2019-04-22T05:39:56Z"
  },
  "from_address": {
    "id": "adr_...",
    "object": "Address",
    "name": "From Name",
    "company": "From Company",
    "street1": "From Street 1",
    "street2": "From Street 2",
    "city": "From City",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4157654321",
    "email": "from@example.com",
    "residential": null,
    "created_at": "2019-04-22T05:39:57Z",
    "updated_at": "2019-04-22T05:39:57Z"
  },
  "parcel": {
    "id": "prcl_...",
    "object": "Parcel",
    "length": 8.2,
    "width": 7.1,
    "height": 6,
    "predefined_package": null,
    "weight": 65.9,
    "created_at": "2019-04-22T05:39:57Z",
    "updated_at": "2019-04-22T05:39:57Z"
  },
  "rates": [
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "ParcelSelect",
      "rate": "9.02",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 5
    },
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "Express",
      "rate": "40.16",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": null
    },
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "Priority",
      "rate": "7.91",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 2
    }
  ],
  "selected_rate": {
    "id": "rate_...",
    "object": "Rate",
    "created_at": "2019-04-22T05:40:57Z",
    "carrier": "USPS",
    "service": "Priority",
    "rate": "7.91",
    "delivery_date": null,
    "delivery_date_guaranteed": false,
    "delivery_days": 2
  },
  "postage_label": {
    "object": "PostageLabel",
    "created_at": "2019-04-22T05:40:57Z",
    "updated_at": "2019-04-22T05:40:57Z",
    "id": "pl_...",
    "integrated_form": null,
    "label_date": "2019-04-23",
    "label_epl2_url": null,
    "label_file_type": "image/png",
    "label_pdf_url": null,
    "label_resolution": null,
    "label_size": null,
    "label_type": null,
    "label_url": "https://....png",
    "label_zpl_url": null
  },
  "tracker": {
    "object": "Tracker",
    "created_at": "2019-04-22T05:40:57Z",
    "updated_at": "2019-04-22T05:40:57Z",
    "id": "trk_...",
    "shipment_id": "shp_...",
    "status": null,
    "tracking_code": "9405500205903028777744",
    "tracking_details": [],
    "public_url": null
  },
  "options": {
    "label_format": "png"
  },
  "created_at": "2019-04-22T05:40:57Z",
  "updated_at": "2019-04-22T05:40:57Z"
}

To purchase a Shipment you only need to specify the Rate to purchase. This operation creates a Tracker and PostageLabel and returns the updated Shipment. The default image format of the associated PostageLabel is PNG. To change this default see the label_format option.

HTTP Request

POST https://www.vanlo.com/api/v1/shipments/:id/buy

Buy Shipment Request Parameters

Parameter	Type	Specification
rate	object	Rate object to purchase, must include id (e.g. {id: "rate_..."})

Refund a Shipment

curl -X POST https://www.vanlo.com/api/v1/shipments/shp_.../refund \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = "VANLO_API_KEY"

shipment = Vanlo::Shipment.retrieve("shp_...")
shipment.refund

import vanlo
vanlo.api_key = "VANLO_API_KEY"

shipment = vanlo.Shipment.retrieve("shp_...")
shipment.refund()

require_once("path/to/lib/vanlo.php");
\Vanlo\Vanlo::setApiKey("VANLO_API_KEY");

$shipment = \Vanlo\Shipment::retrieve("shp_...");
$shipment->refund();

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Shipment ship ment = Shipment.Retrieve("shp...");
shipment.Refund();

The above command returns JSON structured like this:

{
  "id": "shp_...",
  "object": "Shipment",
  "to_address": {
    "id": "adr_...",
    "object": "Address",
    "name": "To Name",
    "company": null,
    "street1": "To Street",
    "street2": null,
    "city": "To City",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "4151234567",
    "residential": null,
    "email": "to@example.com",
    "created_at": "2019-04-22T05:39:56Z",
    "updated_at": "2019-04-22T05:39:56Z"
  },
  "from_address": {
    "id": "adr_...",
    "object": "Address",
    "name": "From Name",
    "company": "From Company",
    "street1": "From Street 1",
    "street2": "From Street 2",
    "city": "From City",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4157654321",
    "email": "from@example.com",
    "residential": null,
    "created_at": "2019-04-22T05:39:57Z",
    "updated_at": "2019-04-22T05:39:57Z"
  },
  "parcel": {
    "id": "prcl_...",
    "object": "Parcel",
    "length": 8.2,
    "width": 7.1,
    "height": 6.0,
    "predefined_package": null,
    "weight": 65.9,
    "created_at": "2019-04-22T05:39:57Z",
    "updated_at": "2019-04-22T05:39:57Z"
  },
  "rates": [
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "ParcelSelect",
      "rate": "9.02",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 5
    },
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "Express",
      "rate": "40.16",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": null
    },
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "Priority",
      "rate": "7.91",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 2
    }
  ],
  "selected_rate": null,
  "postage_label": null,
  "tracking_code": null,
  "refund_status": "submitted",
  "created_at": "2019-04-22T05:40:57Z",
  "updated_at": "2019-04-22T05:40:57Z"
}

Once the refund has been submitted, refund_status attribute of the Shipment will be populated with one of the possible values: "submitted", "refunded", "rejected".

HTTP Request

POST https://www.vanlo.com/api/v1/shipments/:id/refund

Refund Shipment Request Parameters

Parameter	Type	Specification
id	string	Unique identifier of the shipment to refund

Addresses

Address Object

Parameter	Type	Specification
id	string	Unique identifier, begins with "adr_"
object	string	"Address"
name	string	Name of the person or contact
company	string	Company name associated with the address
street1	string	First line of the street address
street2	string	Second line of the street address
city	string	City
state	string	State or province (2-letter code for US, CA, AU)
zip	string	Zip or postal code
country	string	Two-letter ISO 3166 country code
phone	string	Phone number associated with the address
email	string	Email address
residential	boolean	Whether the address is a residential address
verifications	object	Address verification results, if requested
created_at	datetime	When the address was created
updated_at	datetime	When the address was last updated

Create an address

curl -X POST https://www.vanlo.com/api/v1/addresses \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d "address[company]=VANLO" \
  -d "address[street1]=123 MONTGOMERY ST" \
  -d "address[street2]=STE 400" \
  -d "address[city]=SAN FRANCISCO" \
  -d "address[state]=CA" \
  -d "address[zip]=94104" \
  -d "address[country]=US" \
  -d "address[phone]=4151234567"

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Address.create(
  company: "VANLO",
  street1: "123 MONTGOMERY ST",
  street2: "STE 400",
  city: "SAN FRANCISCO",
  state: "CA",
  zip: "94104",
  country: "US",
  phone: "4151234567"
)

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Address.create(
  company="VANLO",
  street1="123 MONTGOMERY ST",
  street2="STE 400",
  city="SAN FRANCISCO",
  state="CA",
  zip="94104",
  country="US",
  phone="4151234567"
)

require_once("/path/to/lib/vanlo.php");
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$address_params = array(
  "company" => "VANLO",
  "street1" => "123 MONTGOMERY ST",
  "street2" => "STE 400",
  "city" => "SAN FRANCISCO",
  "state" => "CA",
  "zip" => "94104",
  "country" => "US",
  "phone" => "4151234567"
);

\Vanlo\Address::create($address_params);

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Address address = Address.Create(
    new Dictionary<string, object>() {
        { "street1", "123 MONTGOMERY ST" },
        { "street2", "STE 400" },
        { "city", "SAN FRANCISCO" },
        { "state", "CA" },
        { "zip", "94104" },
        { "country", "US" },
        { "phone", "415-123-4567" }
    }
);

The above command returns JSON structured like this:

{
  "id": "adr_...",
  "object": "Address",
  "created_at": "2019-09-06T12:01:52.503Z",
  "updated_at": "2019-09-06T12:01:52.503Z",
  "name": null,
  "company": "VANLO",
  "street1": "123 MONTGOMERY ST",
  "street2": "STE 400",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94104",
  "country": "US",
  "phone": "4151234567",
  "email": null,
  "residential": false
}

This endpoint retrieves a specific address.

HTTP Request

POST https://www.vanlo.com/api/v1/addresses

Create Address Request Parameters

Parameter	Type	Specification
name	string	Name of the person or contact
company	string	Company name associated with the address
street1	string	First line of the street address
street2	string	Second line of the street address
city	string	City
state	string	State or province (2-letter code for US, CA, AU)
zip	string	Zip or postal code
country	string	Two-letter ISO 3166 country code
phone	string	Phone number
email	string	Email address
residential	boolean	Whether the address is residential
verify	string	Set to "delivery" to verify the address upon creation

Get a Specific Address

curl -X GET https://www.vanlo.com/api/v1/addresses/adr_... \
  -H 'Authorization: Bearer VANLO_API_KEY' \

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Address.retrieve('adr_...')

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Address.retrieve('adr_...')

require_once("/path/to/lib/vanlo.php");
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

\Vanlo\Address::retrieve('adr_...');

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Address address = Address.Retrieve("adr_...");

The above command returns JSON structured like this:

{
  "id": "adr_...",
  "object": "Address",
  "created_at": "2019-09-06T12:01:52.503Z",
  "updated_at": "2019-09-06T12:01:52.503Z",
  "name": null,
  "company": "VANLO",
  "street1": "123 MONTGOMERY ST",
  "street2": "STE 400",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94104",
  "country": "US",
  "phone": "4151234567",
  "email": null,
  "residential": false
}

This endpoint retrieves a specific address.

HTTP Request

GET https://www.vanlo.com/api/v1/addresses/:id

Parcels

Parcel Object

Parameter	Type	Specification
id	string	Unique identifier, begins with "prcl_"
object	string	"Parcel"
length	float	Length of the parcel in inches
width	float	Width of the parcel in inches
height	float	Height of the parcel in inches
weight	float	Weight of the parcel in ounces
predefined_package	string	Carrier predefined package type, if applicable
created_at	datetime	When the parcel was created
updated_at	datetime	When the parcel was last updated

Create a Parcel

curl -X POST https://api.vanlo.com/api/v1/parcels \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'parcel[length]=20.2' \
  -d 'parcel[width]=10.9' \
  -d 'parcel[height]=5' \
  -d 'parcel[weight]=65.9'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Parcel.create(
  length: 20.2,
  width: 10.9,
  height: 5,
  weight: 65.9
)

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Parcel.create(
  length=20.2,
  width=10.9,
  height=5,
  weight=65.9
)

require_once("/path/to/lib/vanlo.php");
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

\Vanlo\Parcel::create(array(
    "length" => 20.2,
    "width" => 10.9,
    "height" => 5,
    "weight" => 65.9
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Parcel parcel = Parcel.Create(new Dictionary<string, object>() {
    { "length", 10 },
    { "width", 20 },
    { "height", 5 },
    { "weight", 1.8 }
});

The above command returns JSON structured like this:

{
  "id": "prcl_...",
  "object": "Parcel",
  "length": 20.2,
  "width": 10.9,
  "height": 5.0,
  "predefined_package": null,
  "weight": 65.9,
  "created_at": "2019-04-22T05:40:57Z",
  "updated_at": "2019-04-22T05:40:57Z"
}

Create commonly sized parcels and save the returned id for use in future shipments. Remember to use the correct predefined_package when shipping with carrier supplied packaging.

HTTP Request

POST https://www.vanlo.com/api/v1/parcels

Create Parcel Request Parameters

Parameter	Type	Specification
length	float	Length of the parcel in inches
width	float	Width of the parcel in inches
height	float	Height of the parcel in inches
weight	float	Weight of the parcel in ounces
predefined_package	string	Carrier predefined package type. See list of predefined packages

Retrieve a Parcel

curl -X GET https://www.vanlo.com/api/v1/parcels/prcl_... \
  -H 'Authorization: Bearer VANLO_API_KEY' \

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Parcel.retrieve("prcl_...")

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Parcel.retrieve("prcl_...")

require_once("/path/to/lib/vanlo.php");
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

\Vanlo\Parcel::retrieve("prcl_...");

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Parcel parcel = Parcel.Retrieve("prcl_...");

The above command returns JSON structured like this:

{
  "id": "prcl_...",
  "object": "Parcel",
  "length": 20.2,
  "width": 10.9,
  "height": 5.0,
  "predefined_package": null,
  "weight": 65.9,
  "created_at": "2019-04-22T05:40:57Z",
  "updated_at": "2019-04-22T05:40:57Z"
}

Get a Parcel by its id. In general you should not need to use this in your automated solution. A Parcel's id can be inlined into the creation call to other objects. This allows you to only create one Parcel for each package you will be using.

HTTP Request

GET https://vanlo.com/api/v1/parcels/:id

CustomsInfos

CustomsInfo Object

Parameter	Type	Specification
id	string	Unique identifier, begins with "cstinfo_"
object	string	"CustomsInfo"
contents_type	string	Type of item being shipped: "documents", "gift", "merchandise", "returned_goods", "sample", or "other"
contents_explanation	string	Human-readable description of content, required if contents_type is "other"
customs_certify	boolean	Whether the customs form has been signed by the customs_signer
customs_signer	string	Name of the person signing the customs form
eel_pfc	string	Electronic Export License or PFC number. For items valued under $2,500 use "NOEEI 30.37(a)"
non_delivery_option	string	Action to take if the package cannot be delivered: "abandon" or "return" (default)
restriction_comments	string	Additional comments for restricted shipments, required if restriction_type is "other"
restriction_type	string	Type of restriction: "none", "other", "quarantine", or "sanitary_phytosanitary_inspection"
customs_items	[<CustomsItem>...]	Array of CustomsItem objects describing the contents
created_at	datetime	When the customs info was created
updated_at	datetime	When the customs info was last updated

CustomsItem Object

Parameter	Type	Specification
id	string	Unique identifier, begins with "cstitem_"
object	string	"CustomsItem"
description	string	Human-readable description of the item
hs_tariff_number	string	Harmonized System tariff code for the item
origin_country	string	Two-letter ISO 3166 country code of the item's origin
quantity	integer	Number of items
value	float	Total value of the items in USD
weight	float	Total weight of the items in ounces
created_at	datetime	When the customs item was created
updated_at	datetime	When the customs item was last updated

Create CustomsInfo

curl -X POST https://www.vanlo.com/api/v1/customs_infos \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'customs_info[customs_certify]=true' \
  -d 'customs_info[customs_signer]=Name of Signer' \
  -d 'customs_info[contents_type]=merchandise' \
  -d 'customs_info[contents_explanation]=' \
  -d 'customs_info[restriction_type]=none' \
  -d 'customs_info[eel_pfc]=NOEEI 30.37(a)' \
  -d 'customs_info[customs_items][0][description]=Button' \
  -d 'customs_info[customs_items][0][quantity]=2' \
  -d 'customs_info[customs_items][0][value]=23' \
  -d 'customs_info[customs_items][0][weight]=11' \
  -d 'customs_info[customs_items][0][hs_tariff_number]=112233'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::CustomsInfo.create(
  customs_certify: true,
  customs_signer: 'Name of Signer',
  contents_type: 'merchandise',
  restriction_type: 'none',
  eel_pfc: 'NOEEI 30.37(a)',
  customs_items: [
    {
      description: 'Button',
      quantity: '2',
      value: '23',
      weight: '11',
      hs_tariff_number:'11223',
    }
  ]
)

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

customs_info = vanlo.CustomsInfo.create(
    customs_certify=True,
    customs_signer='Name of Signer',
    contents_type='merchandise',
    restriction_type='none',
    eel_pfc='NOEEI 30.37(a)',
    customs_items=[{
        'description': 'Button',
        'quantity': '2',
        'value': '23',
        'weight': '11',
        'hs_tariff_number':'11223',
    }]
)

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$customs_info = \Vanlo\CustomsInfo::create(array(
  'customs_certify' => true,
  'customs_signer' => 'Name of Signer',
  'contents_type' => 'merchandise',
  'restriction_type' => 'none',
  'eel_pfc' => 'NOEEI 30.37(a)',
  'customs_items' => array(array(
    'description' => 'Button',
    'quantity' => 2,
    'value' => 23,
    'weight' => 11,
    'hs_tariff_number' => '11223',
  ))
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Dictionary<string, object> item = new Dictionary<string, object>() {
    { "description", "TShirt" },
    { "quantity", 1 },
    { "weight", 8 },
    { "origin_country", "US" }
};

CustomsInfo info = CustomsInfo.Create(new Dictionary<string, object>() {
    { "customs_certify", true },
    { "eel_pfc", "NOEEI 30.37(a)" },
    { "customs_signer", "Steve Brule" },
    { "contents_type", "merchandise" },
    { "customs_items", new List<Dictionary<string, object>>() { item } }
});

The above command returns JSON structured like this:

{
  "id": "cstinfo_...",
  "object": "CustomsInfo",
  "contents_explanation": null,
  "contents_type": "merchandise",
  "customs_certify": true,
  "customs_signer": "Name of Signer",
  "eel_pfc": "NOEEI 30.37(a)",
  "non_delivery_option": "return",
  "restriction_comments": null,
  "restriction_type": "none",
  "customs_items": [{
      "id": "cstitem_...",
      "object": "CustomsItem",
      "description": "T-Shirt",
      "hs_tariff_number": "123456",
      "origin_country": "US",
      "quantity": 1,
      "value": 10,
      "weight": 5,
      "created_at": "2019-04-22T07:17:51Z",
      "updated_at": "2019-04-22T07:17:51Z"
    }, {
      "id": "cstitem_...",
      "object": "CustomsItem",
      "description": "Button",
      "hs_tariff_number": "112233",
      "origin_country": "US",
      "quantity": 2,
      "value": 23,
      "weight": 11,
      "created_at": "2019-04-22T07:17:51Z",
      "updated_at": "2019-04-22T07:17:51Z"
    }
  ],
  "created_at": "2019-04-22T07:17:51Z",
  "updated_at": "2019-04-22T07:17:51Z"
}

A CustomsItem object describes goods for international shipment and should be created then included in a CustomsInfo object.

HTTP Request

POST https://www.vanlo.com/api/v1/customs_infos

Create CustomsInfo Request Parameters

Parameter	Type	Specification
eel_pfc	string	Electronic Export License or PFC number. For items valued under $2,500 use "NOEEI 30.37(a)"
contents_type	string	"documents", "gift", "merchandise", "returned_goods", "sample", or "other"
contents_explanation	string	Description of goods, required when contents_type is "other"
customs_certify	boolean	Whether the customs form has been signed
customs_signer	string	Name of the person signing the customs form
restriction_type	string	"none", "other", "quarantine", or "sanitary_phytosanitary_inspection"
restriction_comments	string	Additional comments, required when restriction_type is "other"
non_delivery_option	string	"abandon" or "return" (default)
customs_items	[<CustomsItem>...]	Array of CustomsItem objects describing the contents

Batches

Batch Object

Parameter	Type	Specification
id	string	Unique identifier, begins with "batch_"
object	string	"Batch"
state	string	Current state of the batch: "creating", "created", "purchasing", "purchased", "purchase_failed", "label_generating", or "label_generated"
status	<BatchStatus>	Counts of shipments in each processing state
num_shipments	integer	Total number of shipments in the batch
reference	string	Arbitrary reference string
scan_form	<ScanForm>	The associated ScanForm object, if generated
shipments	[<BatchShipment>...]	Array of BatchShipment objects with per-shipment status
label_url	string	URL of the consolidated label PDF, if generated
created_at	datetime	When the batch was created
updated_at	datetime	When the batch was last updated

BatchStatus Object

Parameter	Type	Specification
created	integer	Number of shipments that have been created but not yet queued
queued_for_purchase	integer	Number of shipments queued for postage purchase
creation_failed	integer	Number of shipments that failed to be created
postage_purchased	integer	Number of shipments with postage successfully purchased
postage_purchase_failed	integer	Number of shipments where postage purchase failed

BatchShipment Object

Parameter	Type	Specification
id	string	Unique identifier of the shipment, begins with "shp_"
batch_status	string	Status of the shipment within the batch: "created", "queued_for_purchase", "postage_purchased", or "postage_purchase_failed"
batch_message	string	Error message if the shipment failed during batch processing
tracking_code	string	Tracking code for the shipment, if purchased

Create a Batch

curl -X POST https://www.vanlo.com/api/v1/batches \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'batch[shipments][0][id]=shp_...' \
  -d 'batch[shipments][1][id]=shp_...'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Batch.create(shipments: [shipment])

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Batch.create(shipments = [shipment]);

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$batch = \Vanlo\Batch::create(array(
  'shipments' => array(array(
    'id' => 'shp_...'
  ))
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Batch batch = Batch.Create(new Dictionary<string, object>() {
    { "shipments", new List<Dictionary<string, object>>() {
        new Dictionary<string, object>() { { "id", "shp_..." } }
    } }
});

The above command returns JSON structured like this:

{
  "id": "batch_...",
  "object": "Batch",
  "num_shipments": 2,
  "reference": null,
  "scan_form": null,
  "shipments": [
    {
      "id": "shp_...",
      "batch_status": "postage_purchased",
      "batch_message": null,
      "tracking_code": "9405500205903028777744"
    },
    {
      "id": "shp_...",
      "batch_status": "postage_purchased",
      "batch_message": null,
      "tracking_code": "9405500205903028777755"
    }
  ],
  "state": "creating",
  "status": {
    "created": 0,
    "queued_for_purchase": 0,
    "creation_failed": 0,
    "postage_purchased": 2,
    "postage_purchase_failed": 0
  },
  "label_url": null,
  "created_at": "2019-07-22T07:34:39Z",
  "updated_at": "2019-07-22T07:34:39Z"
}

A Batch can be created with or without Shipments. When created with Shipments the initial state will be 'creating'. Once the state changes to created a webhook Event will be sent. When created with no Shipments the initial state will be 'created' and a webhook will be sent.

HTTP Request

POST https://www.vanlo.com/api/v1/batches

Create Batch Parameters

Parameter	Type	Specification
shipments	[<Shipment>...]	Array of Shipment objects (or objects with shipment id) to include in the batch

Batch Labels

curl -X POST https://www.vanlo.com/api/v1/batches/batch_.../label \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'file_format=zpl'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

batch = Vanlo::Batch.retrieve('batch_...')
batch.label(file_format: 'zpl')

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

batch = vanlo.Batch.retrieve('batch_...')
batch.label(file_format = 'zpl')

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$batch = \Vanlo\Batch::retrieve('batch_...');
$batch->label(array('file_format' => 'zpl'));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Batch batch = Batch.Retrieve("batch_...");

batch.GenerateLabel("zpl");

The above command returns JSON structured like this:

{
  "id": "batch_...",
  "object": "Batch",
  "num_shipments": 2,
  "reference": null,
  "scan_form": null,
  "shipments": [
    {
      "id": "shp_...",
      "batch_status": "postage_purchased",
      "batch_message": null,
      "tracking_code": "9405500205903028777744"
    },
    {
      "id": "shp_...",
      "batch_status": "postage_purchased",
      "batch_message": null,
      "tracking_code": "9405500205903028777755"
    }
  ],
  "state": "creating",
  "status": {
    "created": 0,
    "queued_for_purchase": 0,
    "creation_failed": 0,
    "postage_purchased": 2,
    "postage_purchase_failed": 0
  },
  "label_url": null,
  "created_at": "2019-07-22T07:34:39Z",
  "updated_at": "2019-07-22T07:34:39Z"
}

One of the advantages of processing Shipments in batches is the ability to consolidate the PostageLabel into one file. This can only be done once for each batch and all Shipments must have a status of 'postage_purchased'.

Available label formats are 'pdf', 'zpl' or 'epl2' format.

HTTP Request

POST https://www.vanlo.com/api/v1/batches/:id/label

Batch Label Parameters

Parameter	Type	Specification
file_format	string	Label file format: "pdf", "zpl", or "epl2"

Scan Forms

curl -X POST https://www.vanlo.com/api/v1/batches/batch_.../scan_form \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

batch = Vanlo::Batch.retrieve('batch_...')
batch.create_scan_form

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

batch = vanlo.Batch.retrieve('batch_...')
batch.create_scan_form()

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$batch = \Vanlo\Batch::retrieve('batch_...');
$batch->create_scan_form();

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Batch batch = Batch.Retrieve("batch_...");

batch.GenerateScanForm();

The above command returns JSON structured like this:

{
  "id": "batch_...",
  "num_shipments": 2,
  "object": "Batch",
  "reference": null,
  "scan_form": null,
  "shipments": [
    {
      "id": "shp_...",
      "batch_status": "created",
      "batch_message": null,
      "tracking_code": null
    },
    {
      "id": "shp_...",
      "batch_status": "created",
      "batch_message": null,
      "tracking_code": null
    }
  ],
  "state": "creating",
  "status": {
    "created": 2,
    "queued_for_purchase": 0,
    "creation_failed": 0,
    "postage_purchased": 0,
    "postage_purchase_failed": 0
  },
  "label_url": null,
  "created_at": "2019-07-22T07:34:39Z",
  "updated_at": "2019-07-22T07:34:39Z"
}

See Scan Form rules and Object Definition.

HTTP Request

POST https://www.vanlo.com/api/v1/batches/:id/scan_form

Get a specific Batch

curl -X GET https://www.vanlo.com/api/v1/batches/batch_... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Batch.retrieve('batch_...')

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Batch.retrieve('batch_...')

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$batch = \Vanlo\Batch::retrieve('batch_...');

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Batch batch = Batch.Retrieve("batch_...");

The above command returns JSON structured like this:

{
  "id": "batch_...",
  "object": "Batch",
  "num_shipments": 2,
  "reference": null,
  "scan_form": null,
  "shipments": [
    {
      "id": "shp_...",
      "batch_status": "created",
      "batch_message": null,
      "tracking_code": null
    },
    {
      "id": "shp_...",
      "batch_status": "created",
      "batch_message": null,
      "tracking_code": null
    }
  ],
  "state": "creating",
  "status": {
    "created": 2,
    "queued_for_purchase": 0,
    "creation_failed": 0,
    "postage_purchased": 0,
    "postage_purchase_failed": 0
  },
  "label_url": null,
  "created_at": "2019-07-22T07:34:39Z",
  "updated_at": "2019-07-22T07:34:39Z"
}

This endpoint retrieves a specific batch.

HTTP Request

GET https://www.vanlo.com/api/v1/batches/:id

ScanForms

ScanForm Object

Parameter	Type	Specification
id	string	Unique identifier, begins with "sf_"
object	string	"ScanForm"
tracking_codes	[string...]	Array of tracking codes included in the scan form
address	<Address>	The Address that the scan form applies to
status	string	Current status of the scan form: "created", "ready", or "failed"
message	string	Error message if the scan form failed to generate
form_url	string	URL of the scan form PDF document
form	string	Base64-encoded scan form document, if available
batch_id	string	Identifier of the associated Batch, begins with "batch_"
reference	string	Arbitrary reference string for the scan form
created_at	datetime	When the scan form was created
updated_at	datetime	When the scan form was last updated

Create a ScanForm

curl -X POST https://www.vanlo.com/api/v1/scan_forms \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'shipments[0][id]=shp_...' \
  -d 'shipments[1][id]=shp_...'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

shipment = Vanlo::Shipment.retrieve('shp_...')

Vanlo::ScanForm.create(shipments: [shipment])

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.ScanForm.create(shipments=[shipment])

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$shipment = \Vanlo\Shipment::retrieve('shp_...')

$scan_form = \Vanlo\ScanForm::create(array(
  'shipments' => array($shipment)
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

List<Shipment> shipments = new List<Shipment>() {
    new Shipment() { id = "shp_..." }
};

ScanForm scanForm = ScanForm.Create(shipments);

The above command returns JSON structured like this:

{
   "id":"sf_...",
   "object":"ScanForm",
   "created_at":"2019-01-20T22:59:03Z",
   "updated_at":"2019-01-20T22:59:04Z",
   "tracking_codes":[
      "8888888888888888888888"
   ],
   "address":{
      "id":"adr_...",
      "object":"Address",
      "created_at":"2019-10-04T19:08:20Z",
      "updated_at":"2019-10-04T19:08:20Z",
      "name":"Vanlo",
      "company":null,
      "street1":"123 MONTGOMERY ST",
      "street2":"STE 400",
      "city":"SAN FRANCISCO",
      "state":"CA",
      "zip":"94104",
      "country":"US",
      "phone":"4151234567",
      "email":"from@example.com",
      "residential":null,
      "verifications":{}
   },
   "status":"created",
   "message":null,
   "form_url":"https://....pdf",
   "form_file_type":null,
   "batch_id":"batch_...",
   "confirmation":null
}

A ScanForm can be created in two ways:

Add Shipments to a Batch and create a ScanForm for a Batch of Shipments or create a ScanForm for shipments directly without adding shipments to a Batch.

Note: A Batch is created in the background for Shipments as an intermediate process to creating ScanForms. You can create a ScanForm for 1 or a group of Shipments.

HTTP Request

POST https://www.vanlo.com/api/v1/scan_forms

Create ScanForm Request Parameters

Parameter	Type	Specification
shipments	[<Shipment>...]	Array of Shipment objects (or objects with shipment id) to include in the scan form

Retrieve a list of a ScanForms

curl -X GET https://www.vanlo.com/api/v1/scan_forms \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'page_size=2'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::ScanForm.all(page_size: 2)

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.ScanForm.all(page_size=2)

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$scan_forms = \Vanlo\ScanForm::all(array('page_size' => 2));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

var listParams = new Dictionary<string, object>() {
    { "page_size", 2 },
    { "start_datetime", "2016-01-02T08:50:00Z" }
};

ScanFormList scanFormList = ScanForm.List(listParams);

The above command returns JSON structured like this:

{
  "scan_forms":[
    {
      "id":"sf_...",
      "object":"ScanForm",
      "created_at":"2019-01-20T23:06:56Z",
      "updated_at":"2019-01-20T23:06:56Z",
      "tracking_codes":[
        "8888888888888888888888"
      ],
      "address":{
        "id":"adr_...",
        "object":"Address",
        "created_at":"2019-10-04T19:08:20Z",
        "updated_at":"2019-10-04T19:08:20Z",
        "name":"Vanlo",
        "company":null,
        "street1":"123 MONTGOMERY ST",
        "street2":"STE 400",
        "city":"SAN FRANCISCO",
        "state":"CA",
        "zip":"94104",
        "country":"US",
        "phone":"4151234567",
        "email":"from@example.com",
        "residential":null,
        "verifications":{}
      },
      "status":"created",
      "message":null,
      "form_url":"https://vanlo-files.s3-us-west-2.amazonaws.com/files/scan_form/20170120/f02edb1487474db2b7dddd36d467e1f1.pdf",
      "batch_id":"batch_...",
    },
    {
      "id":"sf_...",
      "object":"ScanForm",
      "created_at":"2019-01-20T23:06:48Z",
      "updated_at":"2019-01-20T23:06:48Z",
      "tracking_codes":[],
      "address":null,
      "status":"failed",
      "message":"A consistent from_address is required to create a USPS ScanForm.",
      "form_url":null,
      "batch_id":"batch_...",
    }
  ],
  "has_more":true
}

The ScanForm List is a paginated list of all ScanForm objects associated with the given API key. It accepts a variety of parameters which can be used to modify the scope. The 'has_more' attribute indicates whether or not additional pages can be requested. The recommended way of paginating is to use either the 'before_id' or 'after_id' parameter to specify where the next page begins.

HTTP Request

GET https://www.vanlo.com/api/v1/scan_forms

Retrieve a list of ScanForms Request Parameters

Parameter	Type	Specification
before_id	string	Return scan forms created before this id
after_id	string	Return scan forms created after this id
start_datetime	datetime	Only return scan forms created after this timestamp
end_datetime	datetime	Only return scan forms created before this timestamp
page_size	integer	Number of scan forms to return per page (default 20)

Retrieve a ScanForm

curl -X GET https://www.vanlo.com/api/v1/scan_forms/sf_... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::ScanForm.retrieve('sf_...')

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.ScanForm.retrieve('sf_...')

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$scan_form = \Vanlo\ScanForm::retrieve('sf_...')

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

ScanForm otherScanForm = ScanForm.Retrieve("sf_...");

The above command returns JSON structured like this:

{
   "id":"sf_...",
   "object":"ScanForm",
   "created_at":"2019-01-20T22:59:03Z",
   "updated_at":"2019-01-20T22:59:04Z",
   "tracking_codes":[
      "8888888888888888888888"
   ],
   "address":{
      "id":"adr_...",
      "object":"Address",
      "created_at":"2019-10-04T19:08:20Z",
      "updated_at":"2019-10-04T19:08:20Z",
      "name":"Vanlo",
      "company":null,
      "street1":"123 MONTGOMERY ST",
      "street2":"STE 400",
      "city":"SAN FRANCISCO",
      "state":"CA",
      "zip":"94104",
      "country":"US",
      "phone":"4151234567",
      "email":"from@example.com",
      "residential":null,
      "verifications":{}
   },
   "status":"created",
   "message":null,
   "form_url":"https://....pdf",
   "batch_id":"batch_...",
}

Retrieve a ScanForm by id.

HTTP Request

GET https://www.vanlo.com/api/v1/scan_forms/:id

Retrieve a ScanForm Request Parameters

Parameter	Type	Specification
id	string	Unique identifier of the scan form

Trackers

Tracker Object

Parameter	Type	Specification
id	string	Unique identifier, begins with "trk_"
object	string	"Tracker"
shipment_id	string	The id of the Shipment object associated with the Tracker (if any)
tracking_details	[<TrackingDetails>...]	Array of the associated TrackingDetail objects
carrier_detail	[<CarrierDetail>...]	associated CarrierDetail object
carrier	string	The name of the carrier handling the shipment
status	string	The current status of the package, possible values are "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled" or "error"
tracking_code	string	The tracking code provided by the carrier
public_url	string	URL to a publicly-accessible html page that shows tracking details for this tracker
created_at	datetime
updated_at	datetime

CarrierDetail Object

Parameter	Type	Specification
object	string	"CarrierDetail"
service	string	The service level the associated shipment was shipped with (if available)
container_type	string	The type of container the associated shipment was shipped in (if available)
origin_location	string	The location from which the package originated, stringified for presentation (if available)
alternate_identifier	string	The alternate identifier for this package as provided by the carrier (if available)
destination_location	string	The location to which the package is being sent, stringified for presentation (if available)
est_delivery_date_local	string	The estimated delivery date as provided by the carrier, in the local time zone (if available)
est_delivery_time_local	string	The estimated delivery time as provided by the carrier, in the local time zone (if available)
guaranteed_delivery_date	string	The date and time the carrier guarantees the package to be delivered by (if available)
initial_delivery_attempt	string	The date and time of the first attempt by the carrier to deliver the package (if available)
origin_tracking_location	<TrackingLocation>	The location from which the package originated
destination_tracking_location	<TrackingLocation>	The location to which the package is being sent

TrackingDetails Object

Parameter	Type	Specification
object	string	"TrackingDetail"
status	string	status of the package at the time of the scan event, possible values are "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled" or "error"
message	string	Description of the scan event
source	string	The original source of the information for this scan event, usually the carrier
datetime	datetime	The timestamp when the tracking scan occurred
tracking_location	<TrackingLocation>	The location associated with the scan event
pod_urls	[string...]	Proof-of-delivery image URLs, if available
created_at	datetime
updated_at	datetime

TrackingLocation Object

Parameter	Type	Specification
zip	string	The postal code where the scan event occurred (if available)
city	string	The city where the scan event occurred (if available)
state	string	The state where the scan event occurred (if available)
country	string	The country where the scan event occurred (if available)

Testing Specific Tracking States

Sometimes you may want to simulate specific tracking statuses (e.g. "out_for_delivery") within your application to test how your application responds. Vanlo has a set of test tracking_codes that, when sent to the API, respond with specific tracking statuses and send a webhook Event to your test mode URL. The tracking updates that are sent by these tracking_codes will contain canned information, but it will be similar in form to the information normally provided by the carrier you selected.

Test Tracking Codes

tracking_code	status
EZ1000000001	pre_transit
EZ2000000002	in_transit
EZ3000000003	out_for_delivery
EZ4000000004	delivered
EZ5000000005	return_to_sender
EZ6000000006	failure
EZ7000000007	unknown

Create a Tracker

curl -X POST https://api.vanlo.com/api/v1/trackers \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'tracker[tracking_code]=EZ2000000002'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Tracker.create(
  tracking_code: 'EZ2000000002'
)

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Tracker.create(tracking_code='EZ2000000002')

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');


$tracker = \Vanlo\Tracker::create(array(
  'tracking_code' => 'EZ2000000002',
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Tracker tracker = Tracker.Create("USPS", "EZ2000000002");

The above command returns JSON structured like this:

{
    "id": "trk_...",
    "object": "Tracker",
    "shipment_id": null,
    "tracking_details": [
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T16:09:53.467Z",
            "updated_at": "2020-03-31T16:09:53.467Z",
            "status": "pre_transit",
            "message": "Pre-Shipment information received",
            "datetime": "2020-02-29T16:09:53.000Z",
            "source": null,
            "tracking_location": {
                "zip": null,
                "city": null,
                "state": null,
                "country": null
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T16:09:53.487Z",
            "updated_at": "2020-03-31T16:09:53.487Z",
            "status": "pre_transit",
            "message": "Shipping label created",
            "datetime": "2020-03-01T10:58:53.000Z",
            "source": null,
            "tracking_location": {
                "zip": null,
                "city": null,
                "state": null,
                "country": null
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T16:09:53.500Z",
            "updated_at": "2020-03-31T16:09:53.500Z",
            "status": "in_transit",
            "message": "Picked Up",
            "datetime": "2020-03-01T16:09:53.000Z",
            "source": null,
            "tracking_location": {
                "zip": "94612",
                "city": "Oakland",
                "state": "CA",
                "country": "US"
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T16:09:53.516Z",
            "updated_at": "2020-03-31T16:09:53.516Z",
            "status": "in_transit",
            "message": "Arrived at Sort Facility",
            "datetime": "2020-03-02T10:36:53.000Z",
            "source": null,
            "tracking_location": {
                "zip": "60290",
                "city": "Chicago",
                "state": "IL",
                "country": "US"
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T16:09:53.530Z",
            "updated_at": "2020-03-31T16:09:53.530Z",
            "status": "in_transit",
            "message": "Departed Sort Facility",
            "datetime": "2020-03-03T11:16:53.000Z",
            "source": null,
            "tracking_location": {
                "zip": "60290",
                "city": "Chicago",
                "state": "IL",
                "country": "US"
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T16:09:53.544Z",
            "updated_at": "2020-03-31T16:09:53.544Z",
            "status": "in_transit",
            "message": "Arrived at Distribution Center",
            "datetime": "2020-03-03T16:09:53.000Z",
            "source": null,
            "tracking_location": {
                "zip": "19087",
                "city": "Radnor",
                "state": "PA",
                "country": "US"
            }
        }
    ],
    "created_at": "2020-03-31T16:09:53.436Z",
    "updated_at": "2020-03-31T16:09:53.436Z",
    "carrier": "USPS",
    "status": "in_transit",
    "tracking_code": "EZ...",
    "public_url": "https://..."
}

A Tracker encapsulates all tracking information for a shipment.

HTTP Request

POST https://www.vanlo.com/api/v1/trackers

Create Tracker Parameters

Parameter	Type	Specification
tracking_code	string	The tracking code to track
carrier	string	Name of the carrier (e.g. "USPS", "FedEx")

List trackers

curl -X GET https://api.vanlo.com/api/v1/trackers \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Tracker.all

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Tracker.all(page_size = 2)

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$trackers = \Vanlo\Tracker::all(array(
  'page_size' => 2
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

listParams = new Dictionary<string, object>() {
    { "page_size", 2 },
    { "start_datetime", "2016-01-02T08:50:00Z" }
};

TrackerList trackerList = Tracker.List(listParams);
TrackerList nextTrackerList = trackerList.Next();

The above command returns JSON structured like this:

{
    "trackers": [
        {
            "id": "trk_...",
            "object": "Tracker",
            "shipment_id": null,
            "tracking_details": [
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:07:05.580Z",
                    "updated_at": "2020-03-30T23:07:05.580Z",
                    "status": "pre_transit",
                    "message": "Pre-Shipment information received",
                    "datetime": "2020-02-29T23:07:05.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": null,
                        "city": null,
                        "state": null,
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:07:05.599Z",
                    "updated_at": "2020-03-30T23:07:05.599Z",
                    "status": "pre_transit",
                    "message": "Shipping label created",
                    "datetime": "2020-03-01T17:56:05.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": null,
                        "city": null,
                        "state": null,
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:07:05.622Z",
                    "updated_at": "2020-03-30T23:07:05.622Z",
                    "status": "in_transit",
                    "message": "Picked Up",
                    "datetime": "2020-03-01T23:07:05.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "94612",
                        "city": "Oakland",
                        "state": "CA",
                        "country": "US"
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:07:05.644Z",
                    "updated_at": "2020-03-30T23:07:05.644Z",
                    "status": "in_transit",
                    "message": "Arrived at Sort Facility",
                    "datetime": "2020-03-02T17:34:05.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "60290",
                        "city": "Chicago",
                        "state": "IL",
                        "country": "US"
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:07:05.666Z",
                    "updated_at": "2020-03-30T23:07:05.666Z",
                    "status": "in_transit",
                    "message": "Departed Sort Facility",
                    "datetime": "2020-03-03T18:14:05.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "60290",
                        "city": "Chicago",
                        "state": "IL",
                        "country": "US"
                    }
                }
            ],
            "created_at": "2020-03-30T23:07:05.547Z",
            "updated_at": "2020-03-30T23:07:05.547Z",
            "carrier": "USPS",
            "status": "out_for_delivery",
            "tracking_code": "EZ3000000003",
            "public_url": "https://..."
        },
        {
            "id": "trk_...",
            "object": "Tracker",
            "shipment_id": "shp_dab9ace301d690b3473d5e7f5c9dfba2",
            "tracking_details": [
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:08:45.296Z",
                    "updated_at": "2020-03-30T23:08:45.296Z",
                    "status": "pre_transit",
                    "message": "Pre-Shipment Info Sent to USPS",
                    "datetime": "2020-02-29T23:07:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": null,
                        "city": null,
                        "state": null,
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:08:45.311Z",
                    "updated_at": "2020-03-30T23:08:45.311Z",
                    "status": "pre_transit",
                    "message": "Shipping Label Created",
                    "datetime": "2020-03-01T11:44:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "77063",
                        "city": "HOUSTON",
                        "state": "TX",
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:09:45.402Z",
                    "updated_at": "2020-03-30T23:09:45.402Z",
                    "status": "pre_transit",
                    "message": "Pre-Shipment Info Sent to USPS",
                    "datetime": "2020-02-29T23:08:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": null,
                        "city": null,
                        "state": null,
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:09:45.416Z",
                    "updated_at": "2020-03-30T23:09:45.416Z",
                    "status": "pre_transit",
                    "message": "Shipping Label Created",
                    "datetime": "2020-03-01T11:45:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "77063",
                        "city": "HOUSTON",
                        "state": "TX",
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:09:45.430Z",
                    "updated_at": "2020-03-30T23:09:45.430Z",
                    "status": "in_transit",
                    "message": "Arrived at USPS Origin Facility",
                    "datetime": "2020-03-01T21:50:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "77315",
                        "city": "NORTH HOUSTON",
                        "state": "TX",
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:09:45.444Z",
                    "updated_at": "2020-03-30T23:09:45.444Z",
                    "status": "in_transit",
                    "message": "Arrived at USPS Facility",
                    "datetime": "2020-03-02T23:26:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "29201",
                        "city": "COLUMBIA",
                        "state": "SC",
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:09:45.470Z",
                    "updated_at": "2020-03-30T23:09:45.470Z",
                    "status": "in_transit",
                    "message": "Arrived at Post Office",
                    "datetime": "2020-03-03T02:17:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "29407",
                        "city": "CHARLESTON",
                        "state": "SC",
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:09:45.483Z",
                    "updated_at": "2020-03-30T23:09:45.483Z",
                    "status": "in_transit",
                    "message": "Sorting Complete",
                    "datetime": "2020-03-03T07:57:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "29407",
                        "city": "CHARLESTON",
                        "state": "SC",
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:10:45.659Z",
                    "updated_at": "2020-03-30T23:10:45.659Z",
                    "status": "pre_transit",
                    "message": "Pre-Shipment Info Sent to USPS",
                    "datetime": "2020-02-29T23:09:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": null,
                        "city": null,
                        "state": null,
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:10:45.680Z",
                    "updated_at": "2020-03-30T23:10:45.680Z",
                    "status": "pre_transit",
                    "message": "Shipping Label Created",
                    "datetime": "2020-03-01T11:46:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "77063",
                        "city": "HOUSTON",
                        "state": "TX",
                        "country": null
                    }
                }
            ],
            "created_at": "2020-03-30T23:07:09.998Z",
            "updated_at": "2020-03-30T23:07:09.998Z",
            "carrier": "USPS",
            "status": "unknown",
            "tracking_code": "9405....",
            "public_url": "https://..."
        }
    ],
    "has_more": true
}

Retrieve an paginated list of all Trackers available to the authenticated account.

HTTP Request

GET https://www.vanlo.com/api/v1/trackers

Get a Tracker

curl -X GET https://www.vanlo.com/api/v1/trackers/trk_... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Tracker.retrieve('trk_...')

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Tracker.retrieve('trk_...')

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$tracker = \Vanlo\Tracker::retrieve('trk_...');

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Tracker tracker = Tracker.Retrieve("trk_...");

The above command returns JSON structured like this:

{
    "id": "trk_...",
    "object": "Tracker",
    "shipment_id": null,
    "tracking_details": [
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T15:11:17.488Z",
            "updated_at": "2020-03-31T15:11:17.488Z",
            "status": "pre_transit",
            "message": "Pre-Shipment information received",
            "datetime": "2020-02-29T15:11:17.000Z",
            "source": null,
            "tracking_location": {
                "zip": null,
                "city": null,
                "state": null,
                "country": null
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T15:11:17.499Z",
            "updated_at": "2020-03-31T15:11:17.499Z",
            "status": "pre_transit",
            "message": "Shipping label created",
            "datetime": "2020-03-01T10:00:17.000Z",
            "source": null,
            "tracking_location": {
                "zip": null,
                "city": null,
                "state": null,
                "country": null
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T15:11:17.510Z",
            "updated_at": "2020-03-31T15:11:17.510Z",
            "status": "in_transit",
            "message": "Picked Up",
            "datetime": "2020-03-01T15:11:17.000Z",
            "source": null,
            "tracking_location": {
                "zip": "94612",
                "city": "Oakland",
                "state": "CA",
                "country": "US"
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T15:11:17.521Z",
            "updated_at": "2020-03-31T15:11:17.521Z",
            "status": "in_transit",
            "message": "Arrived at Sort Facility",
            "datetime": "2020-03-02T09:38:17.000Z",
            "source": null,
            "tracking_location": {
                "zip": "60290",
                "city": "Chicago",
                "state": "IL",
                "country": "US"
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T15:11:17.532Z",
            "updated_at": "2020-03-31T15:11:17.532Z",
            "status": "in_transit",
            "message": "Departed Sort Facility",
            "datetime": "2020-03-03T10:18:17.000Z",
            "source": null,
            "tracking_location": {
                "zip": "60290",
                "city": "Chicago",
                "state": "IL",
                "country": "US"
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T15:11:17.542Z",
            "updated_at": "2020-03-31T15:11:17.542Z",
            "status": "in_transit",
            "message": "Arrived at Distribution Center",
            "datetime": "2020-03-03T15:11:17.000Z",
            "source": null,
            "tracking_location": {
                "zip": "19087",
                "city": "Radnor",
                "state": "PA",
                "country": "US"
            }
        }
    ],
    "created_at": "2020-03-31T15:11:17.461Z",
    "updated_at": "2020-03-31T15:11:17.461Z",
    "carrier": "USPS",
    "status": "in_transit",
    "tracking_code": "EZ2...",
    "public_url": "https://..."
}

This endpoint retrieves a tracker.

HTTP Request

GET https://www.vanlo.com/api/v1/trackers/:id

Webhooks

Webhook Object

Parameter	Type	Specification
id	string	Unique identifier, begins with "hook_"
object	string	"Webhook"
url	string	The URL that webhook notifications are sent to
disabled_at	datetime	The time the webhook was disabled, or null if enabled

Create a Webhook

curl -X POST https://www.vanlo.com/api/v1/webhooks \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'webhook[url]=https://example.com'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Webhook.create(url: 'https://example.com')

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Webhook.create(url='https://example.com')

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$webhook = \Vanlo\Webhook::create(array('url' => 'https://example.com'));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Webhook webhook = Webhook.Create(
    new Dictionary<string, object>() {
        { "url", "example.com" }
    }
);

The above command returns JSON structured like this:

{
   "id":"hook_...",
   "object":"Webhook",
   "url":"http://example.com",
   "disabled_at":null
}

To create a Webhook, you simply need to provide a url parameter that you wish to receive notifications to.

HTTP Request

POST https://www.vanlo.com/api/v1/webhooks

Create Webhook Request Parameters

Parameter	Type	Specification
url	string	The URL to receive webhook notifications

Retrieve a list of Webhooks

curl -X GET https://www.vanlo.com/api/v1/webhooks \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Webhook.all

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

webhooks = vanlo.Webhook.all()

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$webhooks = \Vanlo\Webhook::all();

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

List<Webhook> webhooks = Webhook.List();

Retrieve an unpaginated list of all Webhooks available to the authenticated account.

The above command returns JSON structured like this:

{
   "webhooks":[
      {
         "id":"hook_...",
         "object":"Webhook",
         "url":"https://webhooks.example.com",
         "disabled_at":null
      },
      {
         "id":"hook_...",
         "object":"Webhook",
         "url":"http://example.com",
         "disabled_at":null
      }
   ]
}

HTTP Request

GET https://www.vanlo.com/api/v1/webhooks

Retrieve a Webhook

curl -X GET https://www.vanlo.com/api/v1/webhooks/hook_... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Webhook.retrieve('hook_...')

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Webhook.retrieve('hook...')

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$webhook = \Vanlo\Webhook::retrieve("hook_...");

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Webhook webhook = Webhook.Retrieve("hook_...");

The above command returns JSON structured like this:

{
   "id":"hook_...",
   "object":"Webhook",
   "url":"http://example.com",
   "disabled_at":null
}

Retrieve a Webhook by id.

HTTP Request

GET https://www.vanlo.com/api/v1/webhooks/:id

Retrieve Webhook Request Parameters

Parameter	Type	Specification
id	string	Unique identifier of the webhook

Update a Webhook

curl -X PUT https://www.vanlo.com/api/v1/webhooks/hook_... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

webhook = Vanlo::Webhook.retrieve('hook_...')
webhook.update

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

webhook = vanlo.Webhook.retrieve('hook_...')
webhook.update()

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$webhook = \Vanlo\Webhook::retrieve("hook_...");
$webhook->update();

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Webhook webhook = Webhook.Retrieve("hook_...");
webhook.Update();

The above command returns JSON structured like this:

{
   "id":"hook_...",
   "object":"Webhook",
   "url":"http://example.com",
   "disabled_at":null
}

Enables a Webhook that has been disabled.

HTTP Request

PUT https://www.vanlo.com/api/v1/webhooks/:id

Delete a Webhook

curl -X DELETE https://www.vanlo.com/api/v1/webhooks/hook_... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

webhook = Vanlo::Webhook.retrieve('hook_...')
webhook.delete

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

webhook = vanlo.Webhook.retrieve('hook_...')
webhook.delete()

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$webhook->delete();

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Webhook webhook = Webhook.Retrieve("hook_...");
webhook.Destroy();

Delete a Webhook by id.

The above command returns JSON structured like this:

{}

HTTP Request

DELETE https://www.vanlo.com/api/v1/webhooks/:id

Delete Webhook Request Parameters

Parameter	Type	Specification
id	string	Unique identifier of the webhook

Handling Webhooks

When a webhook is triggered an event will be sent to the webhook endpoint via a POST request.

Webhook Event Parameters

Parameter	Type	Specification
id	string	Unique identifier, begins with "evt_"
object	string	"Event"
description	string	Event type descriptor, e.g. "tracker.updated" or "batch.updated"
pending_urls	[string...]	Array of webhook URLs that have not yet received this event
completed_urls	[string...]	Array of webhook URLs that have successfully received this event
failed_urls	[string...]	Array of webhook URLs that failed to receive this event
result	<Result>	The event payload, varies by event type
created_at	datetime	When the event was created
updated_at	datetime	When the event was last updated

Event Object

Parameter	Type	Specification
id	string	Unique identifier, begins with "evt_"
object	string	"Event"
description	string	Event type descriptor, e.g. "tracker.updated" or "batch.updated"
pending_urls	[string...]	Array of webhook URLs that have not yet received this event
completed_urls	[string...]	Array of webhook URLs that have successfully received this event
failed_urls	[string...]	Array of webhook URLs that failed to receive this event
result	object	The event payload, varies by event type (see below)
created_at	datetime	When the event was created
updated_at	datetime	When the event was last updated

Example webhook event payload:

{
  "id": "evt_...",
  "object": "Event",
  "description": "tracker.updated",
  "pending_urls": ["https://example.com/webhooks"],
  "completed_urls": [],
  "failed_urls": [],
  "result": {
    "id": "trk_...",
    "object": "Tracker",
    "status": "in_transit",
    "carrier": "USPS",
    "tracking_code": "9405500205903028777744",
    "shipment_id": "shp_...",
    "tracking_details": [
      {
        "object": "TrackingDetail",
        "status": "in_transit",
        "message": "Arrived at Sort Facility",
        "datetime": "2020-04-13T13:58:52Z",
        "source": "USPS",
        "tracking_location": {
          "zip": "60290",
          "city": "Chicago",
          "state": "IL",
          "country": "US"
        }
      }
    ],
    "created_at": "2020-04-13T13:55:52Z",
    "updated_at": "2020-04-13T13:58:52Z",
    "public_url": "https://..."
  },
  "created_at": "2020-04-13T14:00:27Z",
  "updated_at": "2020-04-13T14:00:27Z"
}

Webhook Event Result

Each event type will return a specific set of data in the result field of the webhook event.

tracker.updated

Parameter	Type	Specification
id	string	Unique identifier of the tracker, begins with "trk_"
object	string	"Tracker"
status	string	Current tracking status: "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "return_to_sender", "failure", or "error"
carrier	string	Name of the carrier handling the shipment
tracking_code	string	The tracking code provided by the carrier
shipment_id	string	Identifier of the associated shipment, if any
tracking_details	[<TrackingDetails>...]	Array of TrackingDetail objects
carrier_detail	<CarrierDetail>	Associated CarrierDetail object
public_url	string	URL to a publicly-accessible tracking page
est_delivery_date	datetime	Estimated delivery date, if available
signed_by	string	Name of the person who signed for the package, if available
weight	float	Weight of the package, if available
created_at	datetime	When the tracker was created
updated_at	datetime	When the tracker was last updated

batch.updated

Parameter	Type	Specification
id	string	Unique identifier of the batch, begins with "batch_"
object	string	"Batch"
state	string	Current state of the batch: "creating", "created", "purchasing", "purchased", "purchase_failed", "label_generating", or "label_generated"
status	<BatchStatus>	Counts of shipments in each processing state
num_shipments	integer	Total number of shipments in the batch
label_url	string	URL of the consolidated label, if generated
scan_form	<ScanForm>	Associated ScanForm object, if generated
shipments	[<BatchShipment>...]	Array of BatchShipment objects
created_at	datetime	When the batch was created
updated_at	datetime	When the batch was last updated

Errors

Here's an example of a 400 error response body:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid parameters were passed ...",
    "errors": [...]
  }
}

The Vanlo API uses the following error codes:

Error Code	Meaning
200 OK	The request was successful
201 Created	The request was successful and one or more resources was created
400 Bad Request	Request not processed due to client error
401 Unauthorized	Authentication is required and has failed
404 Not Found	The requested resource could not be found
422 Unprocessable Entity	The request was well-formed but unable to process the contained instructions
500 Application Error	Internal error

Please contact support@vanlo.com for assistance with errors.