### Retrieve Collection Slots (Node.js)

Source: https://developers.easyship.com/docs/courier-pick-ups

This Node.js example uses the 'request' library to fetch available pickup slots for a courier. It sends a GET request with appropriate headers, including the API token, and logs the response status, headers, and body.

```javascript
var request = require('request');

request({
  method: 'GET',
  url: 'https://api.easyship.com/pickup/v1/pickup_slots/{courier_id}',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer  <YOUR EASYSHIP API TOKEN>'
  }}, function (error, response, body) {
  console.log('Status:', response.statusCode);
  console.log('Headers:', JSON.stringify(response.headers));
  console.log('Response:', body);
});
```

--------------------------------

### Easyship Production Token Example

Source: https://developers.easyship.com/docs

This code snippet demonstrates the format of a production token for the Easyship API. Production tokens are used for live transactions and have a 'prod_' prefix.

```text
prod_OWsLoYxxxxxxxxxxxxxxxxxxxxxxxxxxxRf5bh3GdnU=
```

--------------------------------

### Easyship Sandbox Token Example

Source: https://developers.easyship.com/docs

This code snippet shows the format of a sandbox token for the Easyship API. Sandbox tokens are used for testing and have a 'sand_' prefix.

```text
sand_458+7pxxxxxxxxxxxxxxxxxxxxxxxxxxCRWSLHfIkBIQ=
```

--------------------------------

### Successful Taxes and Duties Response Example

Source: https://developers.easyship.com/docs/how-to-calculate-taxes-and-duties

This example shows a successful response from the Easyship T&D API after calculating taxes and duties. It provides the calculated tax and duty amounts, with rounding applied.

```json
{
  "tax": 600, 
  "duty": 200 
}
```

--------------------------------

### GET /couriers (Response Object)

Source: https://developers.easyship.com/docs/how-to-display-rates-at-checkout

This documentation defines the structure of the courier response object containing service details, rankings, and pricing information.

```APIDOC
## GET /couriers

### Description
Returns detailed information about available courier services, including performance rankings, delivery windows, and cost breakdowns.

### Method
GET

### Endpoint
/couriers

### Response
#### Success Response (200)
- **courier_id** (String) - Courier service identifier on the Easyship platform.
- **courier_name** (String) - Name of the courier service.
- **courier_remarks** (String) - Additional details of the courier service.
- **description** (String) - Short courier service description.
- **full_description** (String) - Full courier service description.
- **easyship_rating** (Integer) - Average ratings of the courier service.
- **cost_rank** (Integer) - Easyship cost scoring (1 is best).
- **delivery_time_rank** (Integer) - Delivery time scoring (1 is best).
- **tracking_rating** (Integer) - Tracking accuracy rating (1-5).
- **value_for_money_rank** (Integer) - Combined cost and time rank (1 is best).
- **available_handover_options** (Array) - Options: dropoff, free_pickup, paid_pickup.
- **incoterms** (Enum) - Applicable Incoterms: DDU or DDP.
- **max_delivery_time** (Integer) - Upper bound of delivery window (working days).
- **min_delivery_time** (Integer) - Lower bound of delivery window (working days).
- **is_above_threshold** (Boolean) - True if shipment exceeds customs threshold.
- **currency** (Enum) - ISO-4217 currency code.
- **payment_recipient** (Enum) - Recipient: Easyship, EasyshipPayOnScan, or Courier.
- **discount** (Object) - Applicable courier discount (amount or percentage).
- **shipment_charge** (Number) - Base courier service charge.
- **shipment_charge_total** (Number) - Subtotal of all applicable service charges.
- **total_charge** (Number) - Final calculated charge.

#### Response Example
{
  "courier_id": "fedex_int",
  "courier_name": "FedEx",
  "cost_rank": 1,
  "min_delivery_time": 2,
  "max_delivery_time": 5,
  "currency": "USD",
  "total_charge": 45.50
}
```

--------------------------------

### GET /trackings

Source: https://developers.easyship.com/docs/overview-flow-guide

Retrieves real-time tracking information for a specific shipment.

```APIDOC
## GET /trackings

### Description
Obtain real-time information about shipment location and status.

### Method
GET

### Endpoint
/trackings

### Query Parameters
- **shipment_id** (string) - Required - The ID of the shipment to track.

### Response
#### Success Response (200)
- **status** (string) - Current status of the shipment.

### Response Example
{
  "status": "in_transit"
}
```

--------------------------------

### Retrieve Shipments using Python

Source: https://developers.easyship.com/docs/retrieve-update-and-delete-shipments

This Python snippet demonstrates fetching shipment data from the Easyship API. It uses the 'rest_client' library, similar to the Ruby example, to send a GET request with appropriate headers. Ensure you have the library installed: `pip install rest-client`.

```python
require 'rubygems' if RUBY_VERSION < '1.9' # This line seems out of place for Python, likely a copy-paste error from Ruby example.
require 'rest_client' # This line also seems out of place for Python.

headers = {
  :content_type => 'application/json',
  :authorization => 'Bearer  <YOUR EASYSHIP API TOKEN>'
}

response = RestClient.get 'https://api.easyship.com/shipment/v1/shipments?easyship_shipment_id=&platform_order_number=&shipment_state=&pickup_state=&delivery_state=&label_state=&created_at_from=&created_at_to=&confirmed_at_from=&confirmed_at_to=&per_page=&page=', headers
puts response # This line is Ruby syntax, not Python.

```

--------------------------------

### Request Shipping Rate (Node.js)

Source: https://developers.easyship.com/docs/getting-a-rate

Node.js example using the 'request' library to make a POST request to the Easyship API for shipping rates. It includes setting the content type, authorization header, and the JSON request body.

```javascript
var request = require('request');

request({
  method: 'POST',
  url: 'https://api.easyship.com/rate/v1/rates',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <YOUR EASYSHIP API TOKEN>'
  },
  body: "{  
     \"origin_country_alpha2\": \"SG\",  
     \"origin_postal_code\": \"WC2N\",
     \"destination_country_alpha2\": \"US\",
     \"destination_postal_code\": \"10030\",
     \"taxes_duties_paid_by\": \"Sender\",  
     \"is_insured\": false,
     \"items\": [    {      
        \"actual_weight\": 1.2,      
        \"height\": 10,      
        \"width\": 15,      
        \"length\": 20,      
        \"category\": 
        \"mobiles\",      
        \"declared_currency\": \"SGD\",      
        \"declared_customs_value\": 100    }  ]}"
}, function (error, response, body) {
  console.log('Status:', response.statusCode);
  console.log('Headers:', JSON.stringify(response.headers));
  console.log('Response:', body);
});
```

--------------------------------

### Calculate Taxes and Duties Request Body Example

Source: https://developers.easyship.com/docs/how-to-calculate-taxes-and-duties

This example demonstrates the structure of the request body required to calculate taxes and duties using the Easyship API. It includes details for multiple items, origin and destination countries, insurance, and shipment charges.

```json
{
  "items": [
    {
      "duty_origin_country_id": 78,
      "hs_code": "07051100",
      "customs_value": 490
    }
  ],
  "destination_country_id": 78,
  "origin_country_id": 69,
  "insurance_fee": 27,
  "shipment_charge": 90
}
```

--------------------------------

### Request Shipping Rate (cURL)

Source: https://developers.easyship.com/docs/getting-a-rate

Example of how to request a shipping rate using cURL. This command sends a POST request to the Easyship API endpoint with the necessary JSON payload and authorization token.

```curl
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer <YOUR EASYSHIP API TOKEN>" \
     --data-binary "{
   \"origin_country_alpha2\": \"SG\",
  \"origin_postal_code\": \"WC2N\",
  \"destination_country_alpha2\": \"US\",
  \"destination_postal_code\": \"10030\",
  \"taxes_duties_paid_by\": \"Sender\",
  \"is_insured\": false,
  \"items\": [
    {
      \"actual_weight\": 1.2,
      \"height\": 10,
      \"width\": 15,
      \"length\": 20,
      \"category\": \"mobiles\",
      \"declared_currency\": \"SGD\",
      \"declared_customs_value\": 100
    }
  ]
}" \
'https://api.easyship.com/rate/v1/rates'
```

--------------------------------

### Callback URL Example after Easyship Authorization

Source: https://developers.easyship.com/docs/how-to-authorize-easyship-user

After a user authorizes your platform on Easyship, they are redirected back to your specified callback URL. This URL will contain an authorization 'code' and the 'state' parameter (if provided during the initial request), which you will use to exchange for access and refresh tokens.

```URL
https://your.platform.com/oauth/easyship?code=UhLaQeeduKhGPLoEnQ29aLGuV077VSNEp7LPij_P6Tg&state=3m0V3q5MDgxNIR5Cglw
```

--------------------------------

### Create New Tracking

Source: https://developers.easyship.com/docs/how-to-track-a-shipment

Create a new tracking record for a shipment. This endpoint requires details about the shipment, courier, and addresses.

```APIDOC
## POST /trackings

### Description
Creates a new tracking record for a shipment within the Easyship system. Requires detailed shipment information including tracking number, courier ID, addresses, and items.

### Method
POST

### Endpoint
`https://api.easyship.com/2024-09/trackings`

### Parameters
#### Request Body
- **tracking_number** (string) - Required - The unique tracking identifier generated by the sender.
- **courier_id** (string) - Required - The ID of the courier handling the shipment.
- **platform_order_number** (string) - Optional - The order number from the e-commerce platform.
- **origin_address_id** (string) - Optional - The ID of the origin address if previously saved via the Addresses API. If not provided, `origin_address` must be supplied.
- **origin_address** (object) - Optional - The origin address details. Required if `origin_address_id` is not provided.
  - **line_1** (string) - Required
  - **line_2** (string) - Optional
  - **state** (string) - Required
  - **city** (string) - Required
  - **postal_code** (string) - Required
  - **country_alpha2** (string) - Required
  - **company_name** (string) - Optional
  - **contact_name** (string) - Optional
  - **contact_phone** (string) - Optional
  - **contact_email** (string) - Optional
- **destination_address** (object) - Required - The destination address details.
  - **line_1** (string) - Required
  - **line_2** (string) - Optional
  - **state** (string) - Required
  - **city** (string) - Required
  - **postal_code** (string) - Required
  - **country_alpha2** (string) - Required
  - **company_name** (string) - Optional
  - **contact_name** (string) - Optional
  - **contact_phone** (string) - Optional
  - **contact_email** (string) - Optional
- **items** (array) - Required - An array of shipment items.
  - **description** (string) - Required - Description of the item.
  - **quantity** (integer) - Required - Quantity of the item.

### Request Example
```json
{
  "destination_address": {
    "line_1": "123 Test Street",
    "line_2": "Block 3",
    "state": "Singapore",
    "city": "Singapore",
    "postal_code": "247964",
    "country_alpha2": "SG",
    "company_name": "Test Plc.",
    "contact_name": "Foo Bar",
    "contact_phone": "+65 6910 1185",
    "contact_email": "asd@asd.com"
  },
  "items": [
    {
      "description": "iPhone",
      "quantity": 1
    }
  ],
  "tracking_number": "0114827",
  "courier_id": "01563646-58c1-4607-8fe0-cae3e33c0002",
  "platform_order_number": "28659826843658326431264",
  "origin_address_id": "5636-13as-8264-8fe0-9s63"
}
```

### Response
#### Success Response (200)
- **tracking** (object) - Contains tracking details including `ID`, `tracking_number`, `source`, `platform_order_number`, origin and destination country codes, and `tracking_status`.
  - **tracking_status** (string) - Possible values: `pending`, `created`, `active`, `completed`, `overwritten_by_admin`.

#### Response Example
(Response example not provided in the source text, but would typically include the created tracking object with its details.)
```

--------------------------------

### Retrieve Collection Slots (PHP)

Source: https://developers.easyship.com/docs/courier-pick-ups

This PHP script utilizes cURL to retrieve available pickup slots for a courier. It sets the necessary options for the GET request, including the URL and authorization headers, and then outputs the response.

```php
<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://api.easyship.com/pickup/v1/pickup_slots/{courier_id}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  "Content-Type: application/json",
  "Authorization: Bearer  <YOUR EASYSHIP API TOKEN>"
));

$response = curl_exec($ch);
curl_close($ch);

var_dump($response);
?>
```

--------------------------------

### Retrieve Collection Slots (Python)

Source: https://developers.easyship.com/docs/courier-pick-ups

This Python script retrieves available collection slots using the `urllib2` library. It constructs a GET request with the required headers, including the API token, and prints the response body.

```python
from urllib2 import Request, urlopen

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer  <YOUR EASYSHIP API TOKEN>'
}
request = Request('https://api.easyship.com/pickup/v1/pickup_slots/{courier_id}', headers=headers)

response_body = urlopen(request).read()
print response_body
```

--------------------------------

### Webhook Messages for Tracking Updates (Easyship)

Source: https://developers.easyship.com/docs/how-to-track-a-shipment

Easyship API supports webhook messages for real-time tracking updates. Key messages include 'shipment.tracking.status.changed' and 'shipment.racking.checkpoints.created'. Refer to the Easyship quickstart guide for webhook setup instructions.

```Text
shipment.tracking.status.changed
shipment.racking.checkpoints.created
```

--------------------------------

### Retrieve Shipments using Node.js

Source: https://developers.easyship.com/docs/retrieve-update-and-delete-shipments

This Node.js snippet uses the 'request' library to fetch shipment data from the Easyship API. It configures the GET request with necessary headers and logs the response status, headers, and body. Ensure you have the 'request' library installed (`npm install request`).

```javascript
var request = require('request');

request({
  method: 'GET',
  url: 'https://api.easyship.com/shipment/v1/shipments?easyship_shipment_id=&platform_order_number=&shipment_state=&pickup_state=&delivery_state=&label_state=&created_at_from=&created_at_to=&confirmed_at_from=&confirmed_at_to=&per_page=&page=',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer  <YOUR EASYSHIP API TOKEN>'
  }}, function (error, response, body) {
  console.log('Status:', response.statusCode);
  console.log('Headers:', JSON.stringify(response.headers));
  console.log('Response:', body);
});

```

--------------------------------

### Retrieve Shipments using Ruby

Source: https://developers.easyship.com/docs/retrieve-update-and-delete-shipments

This Ruby code utilizes the 'rest_client' gem to interact with the Easyship API for retrieving shipments. It sets up the required headers, including authorization, and makes a GET request to the shipments endpoint. Make sure to install the gem: `gem install rest_client`.

```ruby
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'

headers = {
  :content_type => 'application/json',
  :authorization => 'Bearer  <YOUR EASYSHIP API TOKEN>'
}

response = RestClient.get 'https://api.easyship.com/shipment/v1/shipments?easyship_shipment_id=&platform_order_number=&shipment_state=&pickup_state=&delivery_state=&label_state=&created_at_from=&created_at_to=&confirmed_at_from=&confirmed_at_to=&per_page=&page=', headers
puts response

```

--------------------------------

### Redirect User to Easyship Auth Provider (URL Example)

Source: https://developers.easyship.com/docs/how-to-authorize-easyship-user

This URL is used to initiate the OAuth2 authorization flow, prompting users to log in to Easyship and grant your platform access to specified scopes. Ensure all parameters like client_id, redirect_uri, response_type, scope, and optionally state are correctly formatted.

```URL
https://auth.easyship.com/oauth2/authorize?client_id=ixaj5e4L25axd_d6b4K2wG479_9c3itEN8eexE_67Qk&redirect_uri=https%3A%2F%2Fdomain.com%2Fcallback&response_type=code&scope=rate%20shipment%20label%20track%20company%20pickup%20location%20store%20product&state=Ml_Wdv6hFqy2N9EkNJdi7g
```

--------------------------------

### Book a Collection via POST Request

Source: https://developers.easyship.com/docs/courier-pick-ups

Schedule a courier pickup by sending a POST request to the /pickup/v1/pickups endpoint. The request requires a courier ID, preferred time window, and a list of shipment IDs.

```json
{
  "courier_id": "b4552ed2-ae95-4647-9746-5790bf252c7f",
  "preferred_date": "2016-12-08",
  "preferred_max_time": "2016-12-08T18:00",
  "preferred_min_time": "2016-12-08T09:00",
  "easyship_shipment_ids": [
    "ESUS3171766"
  ]
}
```

```curl
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer  <YOUR EASYSHIP API TOKEN>" \
     --data-binary "{\n  \"courier_id\": \"b4552ed2-ae95-4647-9746-5790bf252c7f\",\n  \"preferred_date\": \"2016-12-08\",\n  \"preferred_max_time\": \"2016-12-08T18:00\",\n  \"preferred_min_time\": \"2016-12-08T09:00\",\n  \"easyship_shipment_ids\": [\n    \"ESUS3171766\"\n  ]\n}" \
'https://api.easyship.com/pickup/v1/pickups'
```

```javascript
var request = require('request');

request({
  method: 'POST',
  url: 'https://api.easyship.com/pickup/v1/pickups',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer  <YOUR EASYSHIP API TOKEN>'
  },
  body: "{  \"courier_id\": \"b4552ed2-ae95-4647-9746-5790bf252c7f\",  \"preferred_date\": \"2016-12-08\",  \"preferred_max_time\": \"2016-12-08T18:00\",  \"preferred_min_time\": \"2016-12-08T09:00\",  \"easyship_shipment_ids\": [    \"ESUS3171766\"  ]}"
}, function (error, response, body) {
  console.log('Status:', response.statusCode);
  console.log('Headers:', JSON.stringify(response.headers));
  console.log('Response:', body);
});
```

```ruby
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'

values = '{
  "courier_id": "b4552ed2-ae95-4647-9746-5790bf252c7f",
  "preferred_date": "2016-12-08",
  "preferred_max_time": "2016-12-08T18:00",
  "preferred_min_time": "2016-12-08T09:00",
  "easyship_shipment_ids": [
    "ESUS3171766"
  ]
}'

headers = {
  :content_type => 'application/json',
  :authorization => 'Bearer  <YOUR EASYSHIP API TOKEN>'
}

response = RestClient.post 'https://api.easyship.com/pickup/v1/pickups', values, headers
puts response
```

```python
from urllib2 import Request, urlopen

values = """
  {
    "courier_id": "b4552ed2-ae95-4647-9746-5790bf252c7f",
    "preferred_date": "2016-12-08",
    "preferred_max_time": "2016-12-08T18:00",
    "preferred_min_time": "2016-12-08T09:00",
    "easyship_shipment_ids": [
      "ESUS3171766"
    ]
  }
"""

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer  <YOUR EASYSHIP API TOKEN>'
}
request = Request('https://api.easyship.com/pickup/v1/pickups', data=values, headers=headers)

response_body = urlopen(request).read()
print response_body
```

```php
<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://api.easyship.com/pickup/v1/pickups");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);

curl_setopt($ch, CURLOPT_POST, TRUE);

curl_setopt($ch, CURLOPT_POSTFIELDS, "{\n  \"courier_id\": \"b4552ed2-ae95-4647-9746-5790bf252c7f\",\n  \"preferred_date\": \"2016-12-08\",\n  \"preferred_max_time\": \"2016-12-08T18:00\",\n  \"preferred_min_time\": \"2016-12-08T09:00\",\n  \"easyship_shipment_ids\": [\n    \"ESUS3171766\"\n  ]\n}");

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  "Content-Type: application/json",
  "Authorization: Bearer  <YOUR EASYSHIP API TOKEN>"
));

$response = curl_exec($ch);
curl_close($ch);

var_dump($response);
```

--------------------------------

### 422 Error Response Example - Tax Calculation Issue

Source: https://developers.easyship.com/docs/how-to-calculate-taxes-and-duties

This example shows a 422 Unprocessable Entity error response related to tax calculation. It indicates that no import tax record was found for the specified origin and destination country combination.

```json
{
  "tax": "No import tax record was found for the specified origin and destination",
  "duty": null
}
```

--------------------------------

### POST /rates

Source: https://developers.easyship.com/docs/overview-flow-guide

Retrieves a list of available shipping options and costs based on shipment destination, package dimensions, and weight.

```APIDOC
## POST /rates

### Description
Retrieve available shipping rates based on shipment details.

### Method
POST

### Endpoint
/rates

### Request Body
- **destination** (object) - Required - The recipient address details.
- **package** (object) - Required - Dimensions and weight of the package.

### Response
#### Success Response (200)
- **rates** (array) - List of available shipping options and costs.

### Response Example
{
  "rates": [
    { "courier": "FedEx", "cost": 15.50, "currency": "USD" }
  ]
}
```

--------------------------------

### POST /websites/developers_easyship

Source: https://developers.easyship.com/docs/how-to-display-rates-at-checkout

Creates a new shipment with specified origin, destination, and parcel information.

```APIDOC
## POST /websites/developers_easyship

### Description
Creates a new shipment with specified origin, destination, and parcel information.

### Method
POST

### Endpoint
/websites/developers_easyship

### Parameters
#### Request Body
- **origin_address** (Object) - Required - `Address` object for shipment origin.
- **destination_address** (Object) - Required - `Address` object for shipment destination.
- **parcels** (Array of objects) - Required - Shipment items, packaging, and total weight.
  - **items** (Object) - The `items` object for shipment items.
  - **box** (Object) - The `box` object for shipment packaging.
  - **total_actual_weight** (Integer) - `total_actual_weight` of a shipment

### Request Example
```json
{
  "origin_address": {
    "recipient_name": "John Doe",
    "recipient_email": "john.doe@example.com",
    "recipient_phone": "1234567890",
    "street1": "123 Main St",
    "street2": "Apt 4B",
    "city": "Anytown",
    "state_code": "CA",
    "postal_code": "90210",
    "country_code": "US"
  },
  "destination_address": {
    "recipient_name": "Jane Smith",
    "recipient_email": "jane.smith@example.com",
    "recipient_phone": "0987654321",
    "street1": "456 Oak Ave",
    "street2": null,
    "city": "Otherville",
    "state_code": "NY",
    "postal_code": "10001",
    "country_code": "US"
  },
  "parcels": [
    {
      "items": {
        "name": "T-Shirt",
        "quantity": 2,
        "value": 25.00,
        "weight": 0.5,
        "weight_unit": "lb",
        "origin_country": "US"
      },
      "box": {
        "length": 10,
        "width": 8,
        "height": 2,
        "distance_unit": "in"
      },
      "total_actual_weight": 1
    }
  ]
}
```

### Response
#### Success Response (200)
- **shipment_id** (String) - The unique identifier for the created shipment.
- **tracking_number** (String) - The tracking number for the shipment.
- **status** (String) - The current status of the shipment.

#### Response Example
```json
{
  "shipment_id": "shp_12345abcde",
  "tracking_number": "1Z999AA10123456784",
  "status": "created"
}
```
```

--------------------------------

### 422 Error Response Example - Duty Calculation Issue

Source: https://developers.easyship.com/docs/how-to-calculate-taxes-and-duties

This example illustrates a 422 Unprocessable Entity error response for duty calculation failures. It signifies that duty records could not be found for the provided duty origin country ID and HS code combinations.

```json
{
  "tax": null,
  "duty": "Duty records not found for duty_origin_country_id and hs_code combinations: [[199, \"1234\"], [234, \"123\"]]"
}
```

--------------------------------

### GET track/v1/checkpoints

Source: https://developers.easyship.com/docs/tracking-updates

Retrieves the complete history of checkpoints for a specific shipment.

```APIDOC
## GET track/v1/checkpoints

### Description
Retrieves the history of a given shipment, including all checkpoints the shipment has passed through.

### Method
GET

### Endpoint
track/v1/checkpoints

### Parameters
#### Query Parameters
- **easyship_shipment_id** (string) - Optional - The unique Easyship shipment identifier.
- **platform_order_number** (string) - Optional - The order number from the integrated platform.

### Request Example
GET /track/v1/checkpoints?easyship_shipment_id=ESHK0001785

### Response
#### Success Response (200)
- **total_page** (integer) - Total number of pages available.
- **current_page** (integer) - The current page number.
- **shipments** (array) - List of shipment tracking details.

#### Response Example
{
	"total_page": 1,
	"current_page": 1,
	"shipments": [
		{
			"easyship_shipment_id": "ESHK0001785",
			"platform_order_number": "#1234",
			"origin": "Hong Kong",
			"destination": "United States",
			"status": "Out For Delivery",
			"checkpoints": [
				{
					"order_number": 115,
					"handler": "Ups",
					"message": "Out For Delivery",
					"location": "Hollywood, FL, US",
					"checkpoint_time": "2016-08-05T09:20:00.000Z"
				}
			]
		}
	]
}
```

--------------------------------

### Request Shipping Rate (Ruby)

Source: https://developers.easyship.com/docs/getting-a-rate

Ruby code snippet demonstrating how to request a shipping rate using the Net::HTTP library. It constructs the request with the API endpoint, headers, and JSON payload.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.easyship.com/rate/v1/rates")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["content_type"] = "application/json"
request["authorization"] = "Bearer <YOUR EASYSHIP API TOKEN>"
request.body = "{
  \"origin_country_alpha2\": \"SG\",
  \"origin_postal_code\": \"WC2N\",
  \"destination_country_alpha2\": \"US\",
  \"destination_postal_code\": \"10030\",
  \"taxes_duties_paid_by\": \"sender\",
  \"is_insured\": \"false\",
  \"items\": {\"actual_weight\":1.2,\"height\":10,\"width\":15,\"length\":20,\"category\":\"mobiles\",\"declared_currency\":\"sgd\",\"declared_customs_value\":100
}
}"

response = http.request(request)
puts response.read_body
```

```ruby
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'

values = '{
  "origin_country_alpha2": "SG",
  "origin_postal_code": "WC2N",
  "destination_country_alpha2": "US",
  "destination_postal_code": "10030",
  "taxes_duties_paid_by": "Sender",
  "is_insured": false,
  "items": [
    {
      "actual_weight": 1.2,
      "height": 10,
      "width": 15,
      "length": 20,
      "category": "mobiles",
      "declared_currency": "SGD",
      "declared_customs_value": 100
    }
  ]
}'

headers = {
  :content_type => 'application/json',
  :authorization => 'Bearer <YOUR EASYSHIP API TOKEN>'
}

response = RestClient.post 'https://api.easyship.com/rate/v1/rates', values, headers
puts response
```

--------------------------------

### Retrieve Product Categories (GET Request)

Source: https://developers.easyship.com/docs/retrieve-product-categories

This snippet demonstrates how to make a GET request to the Easyship API to retrieve a list of product categories. This is crucial for accurately classifying goods for international shipping, impacting tax and duty calculations. The response is a JSON object containing an array of category objects, each with a name and slug.

```http
GET /reference/v1/categories
```

--------------------------------

### Create Shipment Request

Source: https://developers.easyship.com/docs/creating-a-shipment

This snippet demonstrates the POST request structure required to create a shipment. It includes destination details, item specifications, and an optional courier ID.

```json
{
  "platform_name": "Amazon",
  "platform_order_number": "#1234",
  "selected_courier_id": "b8d528a7-a2d4-4510-a7ac-11cbbb6542cd",
  "destination_country_alpha2": "US",
  "destination_city": "New York",
  "destination_postal_code": "10022",
  "destination_state": "NY",
  "destination_name": "Aloha Chen",
  "destination_address_line_1": "300 Park Avenue",
  "destination_address_line_2": null,
  "destination_phone_number": "+1 234-567-890",
  "destination_email_address": "api-support@easyship.com",
  "items": [
    {
      "description": "Silk dress",
      "sku": "test",
      "actual_weight": 1.2,
      "height": 10,
      "width": 15,
      "length": 20,
      "category": "fashion",
      "declared_currency": "SGD",
      "declared_customs_value": 100
    }
  ]
}
```

```bash
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer  <YOUR EASYSHIP API TOKEN>" \
     --data-binary "{\"platform_name\": \"Amazon\", \"platform_order_number\": \"#1234\", \"selected_courier_id\": \"b8d528a7-a2d4-4510-a7ac-11cbbb6542cd\", \"destination_country_alpha2\": \"US\", \"destination_city\": \"New York\", \"destination_postal_code\": \"10022\", \"destination_state\": \"NY\", \"destination_name\": \"Aloha Chen\", \"destination_address_line_1\": \"300 Park Avenue\", \"destination_address_line_2\": null, \"destination_phone_number\": \"+1 234-567-890\", \"destination_email_address\": \"api-support@easyship.com\", \"items\": [{\"description\": \"Silk dress\", \"sku\": \"test\", \"actual_weight\": 1.2, \"height\": 10, \"width\": 15, \"length\": 20, \"category\": \"fashion\", \"declared_currency\": \"SGD\", \"declared_customs_value\": 100}]}" \
'https://api.easyship.com/shipment/v1/shipments'
```

```ruby
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'

values = '{
  "platform_name": "Amazon",
  "platform_order_number": "#1234",
  "selected_courier_id": "b8d528a7-a2d4-4510-a7ac-11cbbb6542cd",
  "destination_country_alpha2": "US",
  "destination_city": "New York",
  "destination_postal_code": "10022",
  "destination_state": "NY",
  "destination_name": "Aloha Chen",
  "destination_address_line_1": "300 Park Avenue",
  "destination_address_line_2": null,
  "destination_phone_number": "+1 234-567-890",
  "destination_email_address": "api-support@easyship.com",
  "items": [
    {
      "description": "Silk dress",
      "sku": "test",
      "actual_weight": 1.2,
      "height": 10,
      "width": 15,
      "length": 20,
      "category": "fashion",
      "declared_currency": "SGD",
      "declared_customs_value": 100
    }
  ]
}'

headers = {
  :content_type => 'application/json',
  :authorization => 'Bearer  <YOUR EASYSHIP API TOKEN>'
}

response = RestClient.post 'https://api.easyship.com/shipment/v1/shipments', values, headers
puts response
```

```javascript
var request = require('request');

request({
  method: 'POST',
  url: 'https://api.easyship.com/shipment/v1/shipments',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer  <YOUR EASYSHIP API TOKEN>'
  },
  body: "{  \"platform_name\": \"Amazon\",  \"platform_order_number\": \"#1234\",  \"selected_courier_id\": \"b8d528a7-a2d4-4510-a7ac-11cbbb6542cd\",  \"destination_country_alpha2\": \"US\",  \"destination_city\": \"New York\",  \"destination_postal_code\": \"10022\",  \"destination_state\": \"NY\",  \"destination_name\": \"Aloha Chen\",  \"destination_address_line_1\": \"300 Park Avenue\",  \"destination_address_line_2\": null,  \"destination_phone_number\": \"+1 234-567-890\",  \"destination_email_address\": \"api-support@easyship.com\",  \"items\": [    {      \"description\": \"Silk dress\",      \"sku\": \"test\",      \"actual_weight\": 1.2,      \"height\": 10,      \"width\": 15,      \"length\": 20,      \"category\": \"fashion\",      \"declared_currency\": \"SGD\",      \"declared_customs_value\": 100    }  ]}"
}, function (error, response, body) {
  console.log('Status:', response.statusCode);
  console.log('Headers:', JSON.stringify(response.headers));
  console.log('Response:', body);
});
```

--------------------------------

### GET /track/v1/status

Source: https://developers.easyship.com/docs/tracking-updates

Retrieve the current status of a shipment using unique identifiers.

```APIDOC
## GET /track/v1/status

### Description
Returns the current status of a shipment. This endpoint is useful for customer portals or internal customer service tools.

### Method
GET

### Endpoint
api.easyship.com/track/v1/status

### Parameters
#### Query Parameters
- **easyship_shipment_id** (string) - Optional - The unique ID assigned by Easyship.
- **platform_order_number** (string) - Optional - The order number from your platform.
- **per_page** (integer) - Optional - Number of results per page.
- **page** (integer) - Optional - Page number for pagination.

### Request Example
GET https://api.easyship.com/track/v1/status?easyship_shipment_id=ESHK0001785

### Response
#### Success Response (200)
- **total_page** (integer) - Total number of pages.
- **current_page** (integer) - The current page number.
- **shipments** (array) - List of shipment objects containing status details.

#### Response Example
{
	"total_page": 1,
	"current_page": 1,
	"shipments": [
		{
			"easyship_shipment_id": "ESHK0001785",
			"platform_order_number": "#1234",
			"status": "Out For Delivery"
		}
	]
}
```

--------------------------------

### POST /rates

Source: https://developers.easyship.com/docs/getting-a-rate

Retrieves a list of available shipping rates and services based on shipment details.

```APIDOC
## POST /rates

### Description
Retrieves a list of shipping rates and services. This is commonly used to provide live shipping quotes to customers at checkout.

### Method
POST

### Endpoint
/rates

### Parameters
#### Request Body
- **origin_address** (object) - Required - The origin address details.
- **destination_address** (object) - Required - The destination address details.
- **parcels** (array) - Required - List of parcels with dimensions and weight.

### Request Example
{
  "origin_address": { "country_alpha2": "US", "city": "New York" },
  "destination_address": { "country_alpha2": "US", "city": "Los Angeles" },
  "parcels": [{ "length": 10, "width": 10, "height": 10, "distance_unit": "cm", "weight": 1, "mass_unit": "kg" }]
}

### Response
#### Success Response (200)
- **rates** (array) - A list of available shipping rates.

#### Response Example
{
  "rates": [
    {
      "service_name": "Express Saver",
      "courier_name": "FedEx",
      "total_charge": 15.50,
      "currency": "USD"
    }
  ]
}
```

--------------------------------

### Show Existing Trackings

Source: https://developers.easyship.com/docs/how-to-track-a-shipment

Retrieve a list of existing trackings. You can fetch all trackings or a specific tracking by its ID.

```APIDOC
## GET /trackings

### Description
Retrieves a list of all created shipment trackings. This endpoint can be filtered by various parameters. A specific tracking can be retrieved by providing its ID.

### Method
GET

### Endpoint
`https://api.easyship.com/2024-09/trackings`

### Parameters
#### Query Parameters
- **origin_country_alpha2** (string) - Optional - Filter by origin country Alpha-2 code.
- **destination_country_alpha2** (string) - Optional - Filter by destination country Alpha-2 code.
- **source** (string) - Optional - Filter by the source of the tracking (e.g., API, platform).
- **tracking_state** (string) - Optional - Filter by the current status of the tracking (e.g., `pending`, `active`).

### Response
#### Success Response (200)
- Returns an array of tracking objects matching the filter criteria.

#### Response Example
(Response example not provided in the source text, but would typically be an array of tracking objects.)

---

## GET /trackings/{tracking_id}

### Description
Retrieves the details for a specific shipment tracking using its unique ID.

### Method
GET

### Endpoint
`https://api.easyship.com/2023-01/trackings/{tracking_id}`

### Parameters
#### Path Parameters
- **tracking_id** (string) - Required - The unique identifier of the tracking record to retrieve.

### Response
#### Success Response (200)
- Returns the tracking object for the specified `tracking_id`.

#### Response Example
(Response example not provided in the source text, but would typically be a single tracking object.)
```

--------------------------------

### POST /pickup/v1/pickups

Source: https://developers.easyship.com/docs/courier-pick-ups

Book a collection for one or more shipments with a specific courier. This request confirms the pickup slot directly with the courier.

```APIDOC
## POST /pickup/v1/pickups

### Description
Book a collection slot for your shipments. Once the request is made, it is confirmed directly with the courier.

### Method
POST

### Endpoint
https://api.easyship.com/pickup/v1/pickups

### Parameters
#### Request Body
- **courier_id** (string) - Required - The unique identifier of the courier.
- **preferred_date** (string) - Required - The date for the collection (YYYY-MM-DD).
- **preferred_min_time** (string) - Required - The start of the preferred time window (ISO 8601).
- **preferred_max_time** (string) - Required - The end of the preferred time window (ISO 8601).
- **easyship_shipment_ids** (array) - Required - A list of shipment IDs to be collected.

### Request Example
{
  "courier_id": "b4552ed2-ae95-4647-9746-5790bf252c7f",
  "preferred_date": "2016-12-08",
  "preferred_max_time": "2016-12-08T18:00",
  "preferred_min_time": "2016-12-08T09:00",
  "easyship_shipment_ids": ["ESUS3171766"]
}

### Response
#### Success Response (200)
- **courier_id** (string) - The ID of the courier.
- **courier_name** (string) - The name of the courier.
- **easyship_shipment_ids** (array) - List of confirmed shipment IDs.
- **pickup** (object) - Contains the `easyship_pickup_id` and time details.

#### Response Example
{
  "courier_id": "b4552ed2-ae95-4647-9746-5790bf252c7f",
  "courier_name": "UPS",
  "easyship_shipment_ids": ["ESUS3171766"],
  "pickup": {
    "easyship_pickup_id": "PHK0000001",
    "preferred_min_time": "2016-12-08T09:00"
  }
}
```

--------------------------------

### Webhook Updates for Tracking

Source: https://developers.easyship.com/docs/how-to-track-a-shipment

Configure Easyship webhooks to receive real-time updates on shipment tracking status changes and checkpoint creations.

```APIDOC
## Webhook Messages for Tracking Updates

### Description
Easyship provides webhook support to send real-time notifications for tracking-related events. By setting up webhooks, you can automatically receive updates as shipment statuses change or new tracking checkpoints are created.

### Supported Messages
- `shipment.tracking.status.changed`: Sent when the status of a shipment's tracking changes.
- `shipment.racking.checkpoints.created`: Sent when new checkpoints are added to a shipment's tracking history.

### Setup
Refer to the Easyship quickstart guide for detailed instructions on how to set up webhooks on your server to receive these notifications.
```