# Shipments

## User actions

### Get Shipments

## Get all shipments

<mark style="color:blue;">`GET`</mark> `https://api.shipitor.com/shipments/usa`

View all your shipments in the USA.&#x20;

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key<mark style="color:red;">\*</mark> | string | API Key     |

{% tabs %}
{% tab title="200 Successfully Listed Shipments " %}

```json
{
	"success": true,
	"shipments": [
		{
			"sender": "XXXXX",
			"recipient": "XXXXX",
			"sender_phone": "XXXXX",
			"recipient_phone": "XXXXX",
			"country": "US",
			"service_speed": "UPS Next Day Air Early",
			"package_weight": "120",
			"description": "Goods",
			"tracking": "XXXXX",
			"labelPdfUrl": "XXXXX",
			"_id": "XXXXX"
		}
	]
}
```

{% endtab %}

{% tab title="401: Unauthorized Authentication or Server error" %}

```
{
	"success": false,
	"error": "Invalid token"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Server error and there was some other error." %}

{% endtab %}
{% endtabs %}

### Create Shipment

To create a shipment, you must have the senders, recipient, and package information ready.&#x20;

{% hint style="warning" %}
Notices:&#x20;

Length (in inches), must be under 30 inches.&#x20;

Width (in inches), must be under 40 inches.&#x20;

Height (in inches), must be under 32 inches.

Weight (in pounds), must be under 120 lbs.
{% endhint %}

{% hint style="danger" %}
For Saturday delivery, the shipment cannot be UPS Next Day Early or UPS Next Day Early Signature
{% endhint %}

## Create a shipment

<mark style="color:green;">`POST`</mark> `api.shipitor.com/shipment/usa/create`

Create a shipment, requires shipment and package information.&#x20;

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key<mark style="color:red;">\*</mark> | string | API Key     |

#### Request Body

| Name                                                 | Type    | Description                                                   |
| ---------------------------------------------------- | ------- | ------------------------------------------------------------- |
| speed<mark style="color:red;">\*</mark>              | String  | Shipping speed and type.                                      |
| sender<mark style="color:red;">\*</mark>             | Object  | Sender or return information                                  |
| address2                                             | String  | Secondary Address (Apartment, Room, Floor, Box, Suite number) |
| state<mark style="color:red;">\*</mark>              | String  | State of Address (USA only)                                   |
| zipcode<mark style="color:red;">\*</mark>            | String  | Sender's zipcode (five digits)                                |
| address<mark style="color:red;">\*</mark>            | String  | Sender's Primary Address                                      |
| company                                              | String  | Company of sender (either company or name is required)        |
| name                                                 | String  | Name of sender (either company or name is required)           |
| phone<mark style="color:red;">\*</mark>              | String  | 10 digit phone number (no spaces or dashes)                   |
| recipient                                            | Object  | Recipient information                                         |
| name                                                 | String  | Name of recipient (either company or name is required)        |
| company                                              | String  | Company of recipient (either company or name is required)     |
| address<mark style="color:red;">\*</mark>            | String  | Recipient's Primary Address                                   |
| address2                                             | String  | Secondary Address (Apartment, Room, Floor, Box, Suite number) |
| city<mark style="color:red;">\*</mark>               | String  | Recipient's City                                              |
| state<mark style="color:red;">\*</mark>              | String  | State of Address (USA only)                                   |
| zipcode<mark style="color:red;">\*</mark>            | String  | Recipient's zipcode (five digits)                             |
| phone<mark style="color:red;">\*</mark>              | String  | 10 digit phone number (no spaces or dashes)                   |
| city<mark style="color:red;">\*</mark>               | String  | Sender's City                                                 |
| package<mark style="color:red;">\*</mark>            | Object  | Package Information                                           |
| length<mark style="color:red;">\*</mark>             | String  | Length (in inches), must be under 30 inches.                  |
| width<mark style="color:red;">\*</mark>              | String  | Width (in inches), must be under 40 inches.                   |
| height<mark style="color:red;">\*</mark>             | String  | Height (in inches), must be under 32 inches.                  |
| weight<mark style="color:red;">\*</mark>             | String  | Weight (in pounds), must be under 120 lbs.                    |
| description<mark style="color:red;">\*</mark>        | String  | Description of item or order information                      |
| references<mark style="color:red;">\*</mark>         | String  | Leave as is \[], or contact for more information.             |
| saturday\_delivery<mark style="color:red;">\*</mark> | Boolean | True or False (allow Saturday delievery at the address).      |

{% tabs %}
{% tab title="200 Shipment Created" %}

```json
{
    "success": true,
    "tracking": "XXXX",
    "labelPdfUrl": "XXX.pdf",
    "payload": {
        "country": "US",
        "service_speed": "UPS Next Day Air Early",
        "sender": {
            "name": "XXX",
            "company": "XXX LLC",
            "address1": "XXX Road",
            "address2": "",
            "city": "XXXX",
            "state": "XX",
            "postal_code": "XXXXX",
            "phone": "XXXXXXXXX"
        },
        "recipient": {
            "name": "XXX",
            "company": "XXX LLC",
            "address1": "XXX Road",
            "address2": "",
            "city": "XXXX",
            "state": "XX",
            "postal_code": "XXXXX",
            "phone": "XXXXXXXXX"
        },
        "package": {
            "length": "30",
            "width": "40",
            "height": "32",
            "weight": "120",
            "description": "XXXX",
            "references": [],
            "saturday_delivery": false
        }
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized Authentication or Server error" %}

```
{
	"success": false,
	"error": "Invalid API Key"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Server error and there was some other error." %}

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="curl" %}

```url
curl --request POST \
  --url http://api.shipitor.com/shipment/usa/create \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR API KEY' \
  --data '{
  "speed": "UPS Next Day Air Early",
  "sender": {
    "name": "XXX",
    "company": "XXX",
    "address": "XXX",
    "address2": "",
    "city": "XXX",
    "state": "XX",
    "zipcode": "XXX",
    "phone": "XXX"
  },
  "recipient": {
    "name": "XXX",
    "company": "XXX",
    "address": "XXX",
    "address2": "",
    "city": "XXX",
    "state": "XXX",
    "zipcode": "XXX",
    "phone": "XXX"
  },
  "package": {
    "length": "30",
    "width": "40",
    "height": "32",
    "weight": "120",
    "description": "XXX",
    "references": [],
    "saturday_delivery": false
  }
}'
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
import axios from "axios";

const options = {
  method: 'POST',
  url: 'http://api.shipitor.com/shipment/usa/create',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR API KEY'
  },
  data: {
    speed: 'UPS Next Day Air Early',
    sender: {
      name: 'XXX',
      company: 'XXX',
      address: 'XXX',
      address2: '',
      city: 'XXX',
      state: 'XXX',
      zipcode: 'XXX',
      phone: 'XXX'
    },
    recipient: {
      name: 'XXX',
      company: 'XXX',
      address: 'XXX',
      address2: '',
      city: 'XXX',
      state: 'XXX',
      zipcode: 'XXX',
      phone: 'XXX'
    },
    package: {
      length: '30',
      width: '40',
      height: '32',
      weight: '120',
      description: 'XXX',
      references: [],
      saturday_delivery: false
    }
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "http://api.shipitor.com/shipment/usa/create"

payload = {
    "speed": "UPS Next Day Air Early",
    "sender": {
        "name": "XXX",
        "company": "XXX",
        "address": "XXX",
        "address2": "",
        "city": "XXX",
        "state": "XX",
        "zipcode": "XXX",
        "phone": "XXX"
    },
    "recipient": {
        "name": "XXXX",
        "company": "XXXX",
        "address": "XXXX Road",
        "address2": "",
        "city": "XXXX",
        "state": "XXXX",
        "zipcode": "XXXX",
        "phone": "XXXX"
    },
    "package": {
        "length": "30",
        "width": "40",
        "height": "32",
        "weight": "XXX",
        "description": "XXXX",
        "references": [],
        "saturday_delivery": False
    }
}
headers = {
    "Content-Type": "application/json",
    "x-api-key": "YOUR API KEY"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
```

{% endtab %}
{% endtabs %}

Your shipment will be created and the tracking number provided, as well as a link to download/view your label in PDF format. You can see your shipments with the **/shipments/usa** API endpoint as long as you provide your API key.&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.shipitor.com/reference/api-reference/shipments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.