Parcels App API

https://parcelsapp.com/api-docs
Admin
Parcels App API is a REST API service that provides endpoints for managing and tracking parcel...
Tokens:4,739
Snippets:19
Trust Score:10
Update:9 months ago
Show doc for...
Tokens:
Raw
### Webhook Example for Real-time Updates

Source: https://parcelsapp.com/api-docs/index

Demonstrates how to set up a webhook endpoint to receive real-time tracking updates from the Parcels API, eliminating the need for polling.

```APIDOC
## Webhook Example (Node.js)

### Description
This example shows how to set up an Express.js server to receive webhook notifications from the Parcels API. When a tracking update is ready, the API will send a POST request to your specified `webhookUrl`.

### Setup
1. **Create a webhook endpoint**: Define a POST route in your server (e.g., `/webhook`) to handle incoming tracking update data.
2. **Initiate tracking with `webhookUrl`**: When calling `POST /shipments/tracking`, include the `webhookUrl` parameter pointing to your endpoint.

### Server Code (Node.js with Express)
```javascript
const express = require('express');
const app = express();

// Enable JSON parsing for webhook requests
app.use(express.json());

// 1. Set up your webhook endpoint
app.post('/webhook', (req, res) => {
  const trackingUpdate = req.body;
  console.log('Tracking completed:', trackingUpdate.done);
  console.log('Shipments:', trackingUpdate.shipments);
  // Process the tracking update data here
  res.status(200).send('OK'); // Respond to the API to acknowledge receipt
});

// For local testing, you can use services like webhook.site or ngrok to expose your local server
// Example using ngrok: webhookUrl: 'https://abc123.ngrok.io/webhook'

// 2. Initiate tracking request (example)
// const trackingData = {
//   apiKey: 'your_api_key',
//   shipments: [{ trackingId: 'UPS123456', destinationCountry: 'United States' }],
//   language: 'en',
//   webhookUrl: 'https://your-domain.com/webhook' // Your webhook endpoint
// };

// axios.post('https://parcelsapp.com/api/v3/shipments/tracking', trackingData)
//   .then(response => {
//     console.log('Tracking initiated, webhook will be called when complete');
//   })
//   .catch(error => {
//     console.error('Error initiating tracking:', error.response?.data || error.message);
//   });

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Webhook server listening on port ${PORT}`);
});
```

### Incoming Webhook Payload Example
```json
{
  "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "done": true,
  "shipments": [
    {
      "trackingId": "EE10021942088880001030003D0N",
      "status": "Delivered",
      "location": {
        "city": "Vancouver",
        "country": "Canada"
      },
      "deliveredAt": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

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

### Get Account Information (Python)

Source: https://parcelsapp.com/api-docs/index

Retrieves account details from the ParcelsApp API using the requests library. Prints plan, limit, current usage, and reset date.

```python
import requests

response = requests.get(
    'https://parcelsapp.com/api/v3/account',
    params={'apiKey': 'your_api_key_here'}
)

if response.status_code == 200:
    data = response.json()
    print(f"Plan: {data['plan']}")
    print(f"Limit: {data['limit']}")
    print(f"Current: {data['current']}")
    print(f"Reset Date: {data['resetDate']}")
else:
    print(response.text)


```

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

### Get Account Information (cURL)

Source: https://parcelsapp.com/api-docs/index

Retrieves account details including plan, limits, and usage via a GET request to the ParcelsApp API. Uses cURL for the request.

```bash
curl --location --request GET 'https://parcelsapp.com/api/v3/account?apiKey=<YOUR API KEY>'
--header 'Accept: application/json'


```

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

### Get Account Information (Node.js with Axios)

Source: https://parcelsapp.com/api-docs/index

Fetches account information from the ParcelsApp API using Axios. Displays plan, limit, current usage, and reset date.

```javascript
const axios = require('axios');
axios.get('https://parcelsapp.com/api/v3/account', {
  params: { apiKey: 'your_api_key_here' }
})
.then(response => {
  console.log('Plan:', response.data.plan);
  console.log('Limit:', response.data.limit);
  console.log('Current:', response.data.current);
  console.log('Reset Date:', response.data.resetDate);
})
.catch(error => {
  console.error('Error:', error.response?.data || error.message);
});


```

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

### Retrieve Tracking Results (Node.js with Axios)

Source: https://parcelsapp.com/api-docs/index

Retrieves tracking results for a shipment using its UUID with Node.js and Axios. This code makes a GET request to the Parcels API using a UUID obtained from the initial tracking request.

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

var config = {
  method: 'get',
  url: 'https://parcelsapp.com/api/v3/shipments/tracking?uuid=<UUID from Step 1>&apiKey=<YOUR API KEY>',
  headers: { 
    'Accept': 'application/json'
  }
};

axios(config)
  .then(function (response) {
    console.log(JSON.stringify(response.data));
  })
  .catch(function (error) {
    console.log(error);
  });



```

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

### GET /shipments/tracking - Read Tracking Result

Source: https://parcelsapp.com/api-docs/index

Retrieves the tracking status and updates for a given tracking request UUID. This endpoint should be called repeatedly until the tracking is complete or an error is received.

```APIDOC
## GET /shipments/tracking

### Description
Retrieves the tracking status and updates for a given tracking request UUID. This endpoint should be called repeatedly until the tracking is complete or an error is received. The `.done` flag in the response indicates completion.

### Method
GET

### Endpoint
`https://parcelsapp.com/api/v3/shipments/tracking`

### Parameters
#### Query Parameters
- **uuid** (string) - Required - The UUID obtained from the POST /shipments/tracking request.
- **apiKey** (string) - Required - Your API key for authentication.

### Request Example
```
curl --location --request GET 'https://parcelsapp.com/api/v3/shipments/tracking?uuid=<UUID from Step 1>&apiKey=<YOUR API KEY>'
```

### Response
#### Success Response (200)
- **uuid** (string) - The tracking request identifier.
- **done** (boolean) - Indicates if the tracking process is complete.
- **shipments** (array) - An array of shipment status objects, containing details like weight, origin, destination, etc., if available.

#### Response Example
```json
{
  "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "done": false,
  "shipments": [
    {
      "trackingId": "EE10021942088880001030003D0N",
      "status": "In Transit",
      "location": {
        "country": "Canada"
      }
    }
  ]
}
```
```

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

### Real-time Tracking Updates with Webhook (Node.js)

Source: https://parcelsapp.com/api-docs/index

Sets up a webhook endpoint using Node.js and Express to receive real-time tracking updates. It also demonstrates how to initiate a tracking request, providing a webhook URL for the API to send notifications upon completion.

```javascript
const express = require('express');
const axios = require('axios');
const app = express();

// Enable JSON parsing for webhook requests
app.use(express.json());

// 1. Set up your webhook endpoint
app.post('/webhook', (req, res) => {
  const trackingUpdate = req.body;
  console.log('Tracking completed:', trackingUpdate.done);
  console.log('Shipments:', trackingUpdate.shipments);
  res.status(200).send('OK');
});

// 2. Create tracking request with webhook URL
const trackingData = {
  apiKey: 'your_api_key',
  shipments: [{ trackingId: 'UPS123456', destinationCountry: 'United States' }],
  language: 'en',
  webhookUrl: 'https://your-domain.com/webhook' // Your webhook endpoint
};

// For local testing, use webhook.site or ngrok:
// webhookUrl: 'https://webhook.site/your-unique-id'
// webhookUrl: 'https://abc123.ngrok.io/webhook'

axios.post('https://parcelsapp.com/api/v3/shipments/tracking', trackingData)
  .then(response => {
    console.log('Tracking initiated, webhook will be called when complete');
    console.log('UUID:', response.data.uuid);
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});


```

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

### Initiate Package Tracking Request (Node.js with Axios)

Source: https://parcelsapp.com/api-docs/index

Initiates a tracking request for a package using Node.js and the Axios library. This code sends shipment details and an API key to the Parcels API to create a tracking request and receive a unique UUID.

```javascript
var axios = require('axios');
var data = JSON.stringify({
"shipments": [
{
  "trackingId": "EE10021942088880001030003D0N",
  "destinationCountry": "Canada"
}
],
"language": "en",
"apiKey": "<YOUR API KEY>"
});

var config = {
  method: 'post',
  url: 'https://parcelsapp.com/api/v3/shipments/tracking',
  headers: { 
   'Content-Type': 'application/json'
  },
  data : data
};
axios(config)
  .then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});


```

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

### Initiate Package Tracking Request (cURL)

Source: https://parcelsapp.com/api-docs/index

Initiates a tracking request for a package. This cURL command sends shipment details and an API key to the Parcels API to create a tracking request and receive a unique UUID.

```bash
curl --location --request POST 'https://parcelsapp.com/api/v3/shipments/tracking' \
--header 'Content-Type: application/json' \
--data-raw '{
 "shipments": [
 {
  "trackingId": "EE10021942088880001030003D0N",
  "destinationCountry": "Canada"
 }
],
"language": "en",
"apiKey": "<YOUR API KEY>" 
}'

```

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

### POST /shipments/tracking - Initiate Tracking Request

Source: https://parcelsapp.com/api-docs/index

Initiates a tracking request for one or more shipments. Returns a unique identifier (UUID) for the tracking request.

```APIDOC
## POST /shipments/tracking

### Description
Initiates a tracking request for one or more shipments. Returns a unique identifier (UUID) for the tracking request, which is used to retrieve tracking results later. You can also optionally receive cached tracking results in the response if available.

### Method
POST

### Endpoint
`https://parcelsapp.com/api/v3/shipments/tracking`

### Parameters
#### Request Body
- **shipments** (array) - Required - An array of shipment objects, each containing `trackingId` and `destinationCountry`.
  - **trackingId** (string) - Required - The tracking number for the shipment.
  - **destinationCountry** (string) - Required - The destination country of the shipment.
- **language** (string) - Optional - The language for the tracking results (e.g., 'en'). Defaults to 'en'.
- **apiKey** (string) - Required - Your API key for authentication.
- **webhookUrl** (string) - Optional - A URL to receive real-time tracking updates.

### Request Example
```json
{
  "shipments": [
    {
      "trackingId": "EE10021942088880001030003D0N",
      "destinationCountry": "Canada"
    }
  ],
  "language": "en",
  "apiKey": "<YOUR API KEY>"
}
```

### Response
#### Success Response (200)
- **uuid** (string) - The unique identifier for the tracking request.
- **fromCache** (boolean) - Indicates if the tracking results were returned from cache.
- **shipments** (array) - Tracking results if available in cache.

#### Response Example
```json
{
  "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "fromCache": false,
  "shipments": []
}
```
```

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

### Track Shipments (Python)

Source: https://parcelsapp.com/api-docs/index

Initiates a shipment tracking request and periodically checks its status using the ParcelsApp API. Requires the 'requests' and 'time' libraries.

```python
import requests
import json
import time

apiKey = 'your_api_key_here'
trackingUrl = 'https://parcelsapp.com/api/v3/shipments/tracking'
shipments = [{'trackingId': 'tracking_number_1', 'language': 'en', 'country': 'United States'},
             {'trackingId': 'tracking_number_2', 'language': 'en', 'country': 'United States'},
             ...]

# Initiate tracking request
response = requests.post(trackingUrl, json={'apiKey': apiKey, 'shipments': shipments})

if response.status_code == 200:
    # Get UUID from response
    uuid = response.json()['uuid']
    # Function to check tracking status with UUID
    def check_tracking_status():
        response = requests.get(trackingUrl, params={'apiKey': apiKey, 'uuid': uuid})
        if response.status_code == 200:
            if response.json()['done']:
                print('Tracking complete')
            else:
                print('Tracking in progress...')
                time.sleep(N) # sleep for N sec
                check_tracking_status()
        else:
            print(response.text)
    check_tracking_status()
else:
    print(response.text)


```

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

### Account Information API

Source: https://parcelsapp.com/api-docs/index

Retrieve your account details, including active plan, shipment limits, current usage, and reset date. This endpoint is useful for displaying account status on internal dashboards.

```APIDOC
## GET /account

### Description
Retrieves account information including subscription plan, shipment limits, current usage, and reset date.

### Method
GET

### Endpoint
`/api/v3/account`

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - Your API key for authentication.

### Request Example
```
GET /api/v3/account?apiKey=<YOUR API KEY>
```

### Response
#### Success Response (200)
- **plan** (string) - The current subscription plan.
- **limit** (integer) - The shipment limit for the current plan.
- **current** (integer) - The current number of shipments used.
- **resetDate** (string) - The date when the shipment count resets.

#### Response Example
```json
{
  "plan": "free",
  "limit": 100,
  "current": 50,
  "resetDate": "2024-12-31T23:59:59.000Z"
}
```
```

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

### Track Shipments (Node.js)

Source: https://parcelsapp.com/api-docs/index

Initiates a shipment tracking request and periodically checks its status using the ParcelsApp API. Requires the 'request' library.

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

const apiKey = 'your_api_key_here';
const trackingUrl = 'https://parcelsapp.com/api/v3/shipments/tracking';
const shipments = [{ trackingId: 'tracking_number_1', language: 'en', country: 'United States' },
                   { trackingId: 'tracking_number_2', language: 'en', country: 'Canada' },
                   ...];

// Initiate tracking request
request.post({
    url: trackingUrl,
    json: { apiKey: apiKey, shipments: shipments }
}, (err, res, body) => {
    if (err) {
        console.error(err);
    } else {
        // Get UUID from response
        const uuid = body.uuid;
        // Function to check tracking status with UUID
        const checkTrackingStatus = () => {
            request.get({
                url: `${trackingUrl}?apiKey=${apiKey}&uuid=${uuid}`
            }, (err, res, body) => {
                if (err) {
                    console.error(err);
                } else {
                    if (body.done) {
                        console.log('Tracking complete');
                    } else {
                        console.log('Tracking in progress...');
                        setTimeout(checkTrackingStatus, 1000);
                    }
                }
            });
        }
        checkTrackingStatus();
    }
});

```

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

### Shipment Tracking API

Source: https://parcelsapp.com/api-docs/index

Initiate shipment tracking requests and retrieve tracking results using a provided UUID. The API allows for tracking multiple shipments simultaneously.

```APIDOC
## POST /shipments/tracking

### Description
Initiates a tracking request for one or more shipments. Returns a UUID to poll for tracking results.

### Method
POST

### Endpoint
`/api/v3/shipments/tracking`

### Parameters
#### Request Body
- **apiKey** (string) - Required - Your API key for authentication.
- **shipments** (array of objects) - Required - An array of shipment objects to track.
  - **trackingId** (string) - Required - The tracking number for the shipment.
  - **language** (string) - Optional - The language for tracking updates (e.g., 'en').
  - **country** (string) - Optional - The country code for the shipment.

### Request Example
```json
{
  "apiKey": "your_api_key_here",
  "shipments": [
    { "trackingId": "tracking_number_1", "language": "en", "country": "United States" },
    { "trackingId": "tracking_number_2", "language": "en", "country": "Canada" }
  ]
}
```

### Response
#### Success Response (200)
- **uuid** (string) - A unique identifier for the tracking request. Use this UUID to poll for tracking status.

#### Response Example
```json
{
  "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```
```

```APIDOC
## GET /shipments/tracking

### Description
Retrieves the tracking status for a shipment request using the UUID obtained from a POST /shipments/tracking request.

### Method
GET

### Endpoint
`/api/v3/shipments/tracking`

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - Your API key for authentication.
- **uuid** (string) - Required - The UUID of the tracking request.

### Request Example
```
GET /api/v3/shipments/tracking?apiKey=your_api_key_here&uuid=a1b2c3d4-e5f6-7890-1234-567890abcdef
```

### Response
#### Success Response (200)
- **done** (boolean) - Indicates if the tracking is complete.
- **results** (array of objects) - An array containing tracking results for each shipment (if available).
  - **trackingId** (string) - The tracking number.
  - **status** (string) - The current status of the shipment.
  - **events** (array of objects) - A list of tracking events.

#### Response Example
```json
{
  "done": false,
  "results": [
    {
      "trackingId": "tracking_number_1",
      "status": "In transit",
      "events": [
        {
          "timestamp": "2024-07-27T10:00:00Z",
          "location": "Origin Facility",
          "description": "Package has left the facility."
        }
      ]
    }
  ]
}
```
```

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

### Retrieve Tracking Results (cURL)

Source: https://parcelsapp.com/api-docs/index

Retrieves the tracking results for a specific shipment using its UUID. This cURL command queries the Parcels API with a UUID obtained from the initial tracking request.

```bash
curl --location --request GET 'https://parcelsapp.com/api/v3/shipments/tracking?uuid=<UUID from Step 1>&apiKey=<YOUR API KEY>' --header 'Accept: application/json'    

```
Tokens:
Raw