> For the complete documentation index, see [llms.txt](https://apidocs.gsped.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.gsped.com/gsped-api-english-version/spedizioni-e-dintorni/shipment/corrieri/ups.md).

# UPS

## Gsped code list

<table data-full-width="true"><thead><tr><th>Service</th><th data-type="number">Courier code</th><th data-type="number">Service code</th><th>Notes</th></tr></thead><tbody><tr><td>Domestic Express Saver</td><td>103</td><td>0</td><td>Domestic</td></tr><tr><td>Domestic Express</td><td>103</td><td>1</td><td>Domestic</td></tr><tr><td>Domestic Express Plus</td><td>103</td><td>2</td><td>Domestic</td></tr><tr><td>Domestic Standard</td><td>103</td><td>3</td><td>Domestic</td></tr><tr><td>International Express</td><td>103</td><td>6</td><td>International</td></tr><tr><td>International Express Plus</td><td>103</td><td>7</td><td>International</td></tr><tr><td>International Standard</td><td>103</td><td>8</td><td>International</td></tr><tr><td>International Saver</td><td>103</td><td>9</td><td>International</td></tr><tr><td>Expedited</td><td>103</td><td>10</td><td>International</td></tr></tbody></table>

## Trade documents

Available in POST and PATCH calls

```json
"trade_documents":[
    {
        "nome":"COMMERCIAL_INVOICE_TESTRIF1234_1.pdf",
        "contenuto":""
    }
]
```

Specific documentation for trade documents: [https://apidocs.gsped.com/gsped-api-english-version/spedizioni-e-dintorni/shipment/shipment-objects/trade\_documents](https://apidocs.gsped.com/gsped-api-english-version/spedizioni-e-dintorni/shipment/shipment-objects/trade_documents "mention")

## Customs duties and shipping costs

With UPS you can give a third party's client codes to charge them the shipping costs and/or the customs duties.

Below are some example payloads to use in the various cases:

**Shipping costs and customs duties to a third party:**

```json
"parties": {
        "freightPayer": {
            "zipcode": "15121",
            "country": "IT",
            "clientCode": "abcdef"
        },
        "customsPayer": {
            "zipcode": "15121",
            "country": "IT",
            "clientCode": "ghjki"
        }
    }
```

**Shipping costs to a third party and customs duties to the sender:**

```json
"parties": {
        "freightPayer": {
            "zipcode": "15121",
            "country": "IT",
            "clientCode": "abcdef"
        }
    }
```

**Shipping costs to the sender and customs duties to a third party:**

```json
"parties": {
        "customsPayer": {
            "zipcode": "15121",
            "country": "IT",
            "clientCode": "ghjki"
        }
    }
```

## Direct Delivery

To use UPS direct delivery, add the following field to the shipment creation call:

```json
"ups": {
        "directDelivery": true
    }
```

## Delivery to an address in a residential area

To tell the courier that the delivery location is in a residential area, add the following field to the shipment creation call:

```json
"ups": {
        "residentialLocation": true
    }
```

## Shipment containing restricted articles

To tell the courier that the shipment consists of restricted articles, add the following field to the shipment creation call:

```json
"ups": {
        "restrictedArticle": "RESTRICTED_ARTICLE"
    }
```

Where **RESTRICTED\_ARTICLE** can take one of the following values:

* alcoholic
* diagnosticSpeciments
* perishables
* plants
* seeds
* specialExceptions
* tobacco

## Return shipments

There are several ways to create a return shipment. The modes we currently handle are the following:

| Return type                                            | Code to use | Description                                                                                                                                         |
| ------------------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Standard return                                        | 1           |                                                                                                                                                     |
| Return with 1 pickup attempt                           | 2           |                                                                                                                                                     |
| Return with 3 pickup attempts                          | 3           |                                                                                                                                                     |
| Return with electronic label (Electronic Return Label) | 4           | In this case the courier does NOT return the label in the response when creating the shipment. The label is sent directly to the shipment's sender. |

These return codes can be used through the **flag\_reso** field when creating the shipment