> 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/gestione-ordini/orders.md).

# Orders

Uploading orders to Gsped

This endpoint is used to upload orders and their details to Gsped so that they can be fulfilled via API or via the web interface, with the resulting generation of the shipping labels.

It is very useful when you have to manage several order fulfilment points that use the Gsped web interface but for which a connector for automatic order download cannot be activated.

## Retrieve order list

<mark style="color:blue;">`GET`</mark> `https://api.gsped.it/[INSTANCE]/Orders`

#### Headers

| Name                                        | Type   | Description              |
| ------------------------------------------- | ------ | ------------------------ |
| x-api-key<mark style="color:red;">\*</mark> | String | APIKEY provided by Gsped |

#### Query Parameters

<table><thead><tr><th width="177">Name</th><th width="209">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>int[]</td><td>selects if id IN [id, id, ...]</td></tr><tr><td>client_id</td><td>int[]</td><td>selects if client_id IN [client_id, client_id, ...]<br><br>Any wrong or not permitted client_ids are ignored</td></tr><tr><td>order_ref</td><td>string[]</td><td>selects if order_ref IN [order_ref, order_ref, ...]<br><br>Each string max 50 char</td></tr><tr><td>email</td><td>string</td><td>selects if email = email<br><br>Max 50 char</td></tr><tr><td>data_ordine_da</td><td>Y-m-d</td><td>Selects if data_ordine ≥ data_ordine_da</td></tr><tr><td>data_ordine_a</td><td>Y-m-d</td><td>Selects if data_ordine &#x3C;= data_ordine_a</td></tr><tr><td>status</td><td>string[]</td><td>selects if status IN [status, status, ...]<br><br>Max 3 char</td></tr><tr><td>exclude_status</td><td>string[]</td><td>selects if status NOT IN [status, status, ...]<br><br>Max 3 char</td></tr><tr><td>corriere</td><td>int[]</td><td>selects if corriere IN [corriere, corriere, ...]</td></tr><tr><td>exclude_corriere</td><td>int[]</td><td>selects if corriere NOT IN [corriere, corriere, ...]</td></tr><tr><td>invoice_number</td><td>string[]</td><td>selects if invoice_number IN [invoice_number, invoice_number, ...]</td></tr><tr><td>invoice_date_da</td><td>Y-m-d</td><td>Selects if invoice_date ≥ invoice_date_da</td></tr><tr><td>invoice_date_a</td><td>Y-m-d</td><td>Selects if invoice_date &#x3C;= invoice_date_a</td></tr><tr><td>withDetails</td><td>1 | 0</td><td>If 1, the order details are also returned</td></tr><tr><td>perPage</td><td>1...100</td><td>number of results per page requested</td></tr><tr><td>page</td><td>int</td><td>page number requested</td></tr><tr><td>orderBy</td><td>id | client_id | order_ref | email | data_ordine | status | corriere | invoice_number | invoice_date</td><td>name of the field to sort by (default id)</td></tr><tr><td>order</td><td>ASC | DESC</td><td>sort direction (default DESC)</td></tr></tbody></table>

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "status": 200,
    "errors": [],
    "response": {
        "gType": "list",
        "resource": "ordini",
        "page": "1",
        "totPages": 440,
        "totEntries": 879,
        "entries": 2,
        "ordini": [
            {
                "address": "1 Central Park S, Apartment 507",
                "city": "New York",
                "client_id": "390",
                "contrassegno": "0.00",
                "country_code": "US",
                "corriere": "0",
                "valuta": "EUR",
                "valore_doganale": "150.000",
                "email": "test@test.com",
                "id": "879",
                "assicurazione": "0.00",
                "generic1": null,
                "generic2": null,
                "generic3": null,
                "generic4": null,
                "generic5": null,
                "generic6": null,
                "generic7": null,
                "generic8": null,
                "generic9": null,
                "generic10": null,
                "invoice_date": null,
                "invoice_number": null,
                "name": "Markus Schmid",
                "note": "",
                "order_ref": "TEST_NUOVO_FEDEX",
                "phone": "1123521455",
                "prov": "NY",
                "servizio": "0",
                "tag1": "gsped",
                "totale_lordo": "150.00",
                "vat_code": null,
                "cap": "10019",
                "data_ordine": "2025-02-03 00:00:00",
                "status": "1.0"
            },
            {
                "address": "Rosenweg 6",
                "city": "Feusisberg",
                "client_id": "390",
                "contrassegno": "0.00",
                "country_code": "CH",
                "corriere": "0",
                "valuta": "EUR",
                "valore_doganale": "150.000",
                "email": "test@test.com",
                "id": "878",
                "assicurazione": "0.00",
                "generic1": null,
                "generic2": null,
                "generic3": null,
                "generic4": null,
                "generic5": null,
                "generic6": null,
                "generic7": null,
                "generic8": null,
                "generic9": null,
                "generic10": null,
                "invoice_date": null,
                "invoice_number": null,
                "name": "Markus Schmid",
                "note": "",
                "order_ref": "TEST_NUOVO_FEDEX",
                "phone": "123123123",
                "prov": "FA",
                "servizio": "0",
                "tag1": "gsped",
                "totale_lordo": "150.00",
                "vat_code": null,
                "cap": "8835",
                "data_ordine": "2025-01-31 00:00:00",
                "status": "1.0"
            }
        ],
        "previousPageUrl": null,
        "nextPageUrl": "https://api.gsped.it/testbed/orders?perPage=2&page=2&totEntries=879"
    }
}
```

{% endtab %}

{% tab title="400 Bad request" %}

```json
{
    "status": 400,
    "errors": [
        "The selected order is invalid. (0)"
    ]
}
```

{% endtab %}
{% endtabs %}

#### Example code

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

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gsped.it/sandbox/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: YOUR-API-KEY"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

{% endtab %}

{% tab title="Python" %}

```python
import http.client

conn = http.client.HTTPSConnection("api.gsped.it")

payload = ""

headers = {
    'Content-Type': "application/json",
    'x-api-key': "YOUR-API-KEY"
    }

conn.request("GET", "/sandbox/orders", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
```

{% endtab %}

{% tab title="GO" %}

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://api.gsped.it/sandbox/orders"

	payload := strings.NewReader("")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("x-api-key", "YOUR-API-KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

{% endtab %}

{% tab title="C#" %}

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Get,
    RequestUri = new Uri("https://api.gsped.it/sandbox/orders"),
    Headers =
    {
        { "x-api-key", "YOUR-API-KEY" },
    },
    Content = new StringContent("")
    {
        Headers =
        {
            ContentType = new MediaTypeHeaderValue("application/json")
        }
    }
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url https://api.gsped.it/sandbox/orders \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR-API-KEY'
```

{% endtab %}
{% endtabs %}

## Retrieve an order and its details

<mark style="color:blue;">`GET`</mark> `https://api.gsped.it/[INSTANCE]/Orders/[ID_ORDINE]`

Retrieves an order and its details from Gsped

#### Headers

| Name                                        | Type   | Description              |
| ------------------------------------------- | ------ | ------------------------ |
| x-api-key<mark style="color:red;">\*</mark> | String | APIKEY provided by Gsped |

{% tabs %}
{% tab title="200: OK Order retrieved response" %}

```json
{
    "address": "piazza ambrosoli 13",
    "city": "alessandria",
    "client_id": 390,
    "cod": 123.45,
    "country": "IT",
    "currency": "EUR",
    "customs_value": 123.45,
    "email": "pippo@pippo.it",
    "id": 1,
    "insurance": 123.45,
    "invoice_date": "2023-06-05",
    "invoice_number": 12345678,
    "name": "mario rossi",
    "notes": "testo delle note",
    "order_ref": "ordrif56780",
    "phone": 1311750253,
    "province": "AL",
    "rows": [
        {
            "country_of_origin": "DE",
            "description": "Descrizione riga ordine",
            "qty": 1,
            "sku": "art3",
        }
    ],
    "total": 0,
    "warehouse": "",
    "zip": 15121
}
```

{% endtab %}

{% tab title="403: Forbidden Wrong API key response" %}

```json
{
    "status": false,
    "error": "Invalid API key "
}
```

{% endtab %}

{% tab title="404 Order not found response" %}

```json
{
    "error": "Ordine non trovato",
    "code": 404
}
```

{% endtab %}
{% endtabs %}

The response also contains `rcpt_type`, the shipment fields `vat_seller`, `sender_eori`, `rcpt_eori`, `ddt_num`, `tipo_incasso`, `chi_paga`, `addebito_dogana`, `incoterm` and `parties` (`null` if not set) and, for each detail in `rows`, `id` and `dati_doganali`. The `id` identifies the detail to edit in the PATCH.

#### Example code snippets

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

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gsped.it/sandbox/orders/1",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: YOUR-API-KEY"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

{% endtab %}

{% tab title="PYTHON" %}

```python
import http.client

conn = http.client.HTTPSConnection("api.gsped.it")

payload = ""

headers = {
    'Content-Type': "application/json",
    'x-api-key': "YOUR-API-KEY"
    }

conn.request("GET", "/sandbox/orders/1", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
```

{% endtab %}

{% tab title="GO" %}

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://api.gsped.it/sandbox/orders/1"

	payload := strings.NewReader("")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("x-api-key", "YOUR-API-KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

{% endtab %}

{% tab title="C#" %}

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Get,
    RequestUri = new Uri("https://api.gsped.it/sandbox/orders/1"),
    Headers =
    {
        { "x-api-key", "YOUR-API-KEY" },
    },
    Content = new StringContent("")
    {
        Headers =
        {
            ContentType = new MediaTypeHeaderValue("application/json")
        }
    }
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url https://api.gsped.it/sandbox/orders/1 \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR-API-KEY'
```

{% endtab %}
{% endtabs %}

## Upload orders and details

<mark style="color:green;">`POST`</mark> `https://api.gsped.it/[INSTANCE]/Orders`

Lets you upload orders and their details to Gsped

#### Headers

| Name                                        | Type   | Description              |
| ------------------------------------------- | ------ | ------------------------ |
| x-api-key<mark style="color:red;">\*</mark> | String | APIKEY provided by Gsped |

#### Request Body

<table><thead><tr><th width="226">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>client_id<mark style="color:red;">*</mark></td><td>Int</td><td>Client ID Gsped</td></tr><tr><td>zip<mark style="color:red;">*</mark></td><td>String</td><td>Recipient zip code</td></tr><tr><td>city<mark style="color:red;">*</mark></td><td>String</td><td>Recipient city</td></tr><tr><td>address<mark style="color:red;">*</mark></td><td>String</td><td>Recipient address</td></tr><tr><td>name<mark style="color:red;">*</mark></td><td>String</td><td>Recipient name</td></tr><tr><td>order_ref<mark style="color:red;">*</mark></td><td>String</td><td>Order reference</td></tr><tr><td>email<mark style="color:red;">*</mark></td><td>String</td><td>Recipient email address</td></tr><tr><td>country<mark style="color:red;">*</mark></td><td>String</td><td>Country code iso 2 char</td></tr><tr><td>province<mark style="color:red;">*</mark></td><td>String</td><td>Province or State code</td></tr><tr><td>insurance</td><td>Float</td><td>Insured value</td></tr><tr><td>customs_value</td><td>Float</td><td>Customs value</td></tr><tr><td>cod</td><td>Float</td><td>Cash on delivery (COD) value</td></tr><tr><td>phone<mark style="color:red;">*</mark></td><td>String</td><td>Phone number</td></tr><tr><td>rows.description</td><td>String</td><td>Order detail description</td></tr><tr><td>warehouse</td><td>String</td><td>Warehouse</td></tr><tr><td>notes</td><td>String</td><td>Order notes</td></tr><tr><td>rows.qty</td><td>Int</td><td>Detail quantity</td></tr><tr><td>rows.sku</td><td>String</td><td>Detail SKU</td></tr><tr><td>rows.country_of_origin</td><td>String</td><td>Country code iso 2 char of origin of the goods</td></tr><tr><td>invoice_date</td><td>String</td><td>Date of the order invoice</td></tr><tr><td>invoice_number</td><td>String</td><td>Number of the order invoice</td></tr><tr><td>rows.hs_code</td><td>String</td><td>Detail HS code</td></tr><tr><td>rows.barcode_riga</td><td>String</td><td>Barcode string of the single item</td></tr><tr><td>rows.prezzo_singolo</td><td>String</td><td>Single item price</td></tr><tr><td>rows.peso_riga</td><td>String</td><td>Single item weight</td></tr><tr><td>corriere</td><td>int</td><td>Gsped courier ID</td></tr><tr><td>servizio</td><td>int</td><td>Gsped courier service ID</td></tr><tr><td>rcpt_type</td><td>int</td><td>Recipient type: 0 not specified, 1 private, 2 business</td></tr><tr><td>rows.dati_doganali</td><td>Object</td><td>Customs data of the detail, in <code>dati_doganali.pid</code> the product codes, see <a href="/gsped-api-english-version/spedizioni-e-dintorni/shipment/casi-duso/eu-customs-reform-2026.md">EU customs reform 2026</a></td></tr><tr><td>vat_code</td><td>String</td><td>Recipient VAT number, max 20 char</td></tr><tr><td>vat_seller</td><td>String</td><td>Seller VAT number, max 20 char</td></tr><tr><td>sender_eori</td><td>String</td><td>Sender EORI number, max 20 char</td></tr><tr><td>rcpt_eori</td><td>String</td><td>Recipient EORI number, max 20 char</td></tr><tr><td>ddt_num</td><td>Int</td><td>Number of the shipment's transport document, max 15 digits</td></tr><tr><td>tipo_incasso</td><td>Int</td><td>Cash on delivery collection type, see <a href="/gsped-api-english-version/overview/codici-gsped.md#cash-on-delivery-cod-payment-types">Gsped codes</a></td></tr><tr><td>chi_paga</td><td>Int</td><td>Carriage: 0 paid, 1 forward</td></tr><tr><td>addebito_dogana</td><td>Int</td><td>Who pays duties and customs charges: 0 default, 1 sender, 2 third party. <code>mittente</code>, <code>destinatario</code>, <code>terzo</code> are also accepted</td></tr><tr><td>incoterm</td><td>Object</td><td>Incoterm of the shipment, as in the Shipment, see <a href="/gsped-api-english-version/spedizioni-e-dintorni/shipment/shipment-objects/incoterm.md">incoterm</a></td></tr><tr><td>parties</td><td>Object</td><td>Customs parties of the shipment, as in the Shipment, see <a href="/gsped-api-english-version/spedizioni-e-dintorni/shipment/shipment-objects/parties.md">parties</a></td></tr></tbody></table>

{% hint style="info" %}
`vat_code`, `vat_seller`, `sender_eori`, `rcpt_eori`, `ddt_num`, `tipo_incasso`, `chi_paga` and `addebito_dogana` are shipment fields: they are validated with the same rules as the [Shipment](/gsped-api-english-version/spedizioni-e-dintorni/shipment.md) and are passed to the shipment created with [Order To Shipment](/gsped-api-english-version/gestione-ordini/order-to-shipment.md) only if set. `vat_code` becomes the shipment's `vat_buyer`.

`incoterm` and `parties` are checked only when the shipment is created, because the required data depends on the courier.
{% endhint %}

{% tabs %}
{% tab title="200: OK Order uploaded response" %}

```javascript
{
  "status": "OK",
  "order_id": 572602
}
```

{% endtab %}

{% tab title="403: Forbidden Wrong API key response" %}

```javascript
{
  "status": false,
  "error": "Invalid API key "
}
```

{% endtab %}

{% tab title="400: Bad Request Wrong payload" %}

```javascript
{
  "status": "FAILED",
  "error": "Dati ordine non presenti o in formato sbagliato"
}
```

{% endtab %}
{% endtabs %}

#### Example code snippets

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

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gsped.it/sandbox/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"client_id\": 638,\n  \"order_ref\": \"test-gsped-3\",\n  \"name\": \"mario rossi\",\n  \"address\": \"piazza ambrosoli 13\",\n  \"city\": \"alessandria\",\n  \"zip\": \"15121\",\n  \"province\": \"AL\",\n  \"country\": \"IT\",\n  \"email\": \"pippo@pippo.it\",\n  \"phone\": \"01311750253\",\n  \"cod\": 10,\n  \"insurance\": 0,\n  \"notes\": \"testo delle note\",\n  \"customs_value\": 123.45,\n  \"currency\": \"EUR\",\n  \"warehouse\": \"\",\n  \"tag\" : \"pippo1\",\n  \"rows\": [\n    {\n    \t\"description\" : \"Cosa rossa 1\",\n      \"sku\": \"art3\",\n      \"qty\": 1\n    },\n    {\n    \t\"description\" : \"Cosa rossa 2\",\n      \"sku\": \"art4\",\n      \"qty\": 2\n    }\n  ]\n}",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: YOUR-API-KEY"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

{% endtab %}

{% tab title="PYTHON" %}

```python
import http.client

conn = http.client.HTTPSConnection("api.gsped.it")

payload = "{\n  \"client_id\": 638,\n  \"order_ref\": \"test-gsped-3\",\n  \"name\": \"mario rossi\",\n  \"address\": \"piazza ambrosoli 13\",\n  \"city\": \"alessandria\",\n  \"zip\": \"15121\",\n  \"province\": \"AL\",\n  \"country\": \"IT\",\n  \"email\": \"pippo@pippo.it\",\n  \"phone\": \"01311750253\",\n  \"cod\": 10,\n  \"insurance\": 0,\n  \"notes\": \"testo delle note\",\n  \"customs_value\": 123.45,\n  \"currency\": \"EUR\",\n  \"warehouse\": \"\",\n  \"tag\" : \"pippo1\",\n  \"rows\": [\n    {\n    \t\"description\" : \"Cosa rossa 1\",\n      \"sku\": \"art3\",\n      \"qty\": 1\n    },\n    {\n    \t\"description\" : \"Cosa rossa 2\",\n      \"sku\": \"art4\",\n      \"qty\": 2\n    }\n  ]\n}"

headers = {
    'Content-Type': "application/json",
    'x-api-key': "YOUR-API-KEY"
    }

conn.request("POST", "/sandbox/orders", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
```

{% endtab %}

{% tab title="GO" %}

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://api.gsped.it/sandbox/orders"

	payload := strings.NewReader("{\n  \"client_id\": 638,\n  \"order_ref\": \"test-gsped-3\",\n  \"name\": \"mario rossi\",\n  \"address\": \"piazza ambrosoli 13\",\n  \"city\": \"alessandria\",\n  \"zip\": \"15121\",\n  \"province\": \"AL\",\n  \"country\": \"IT\",\n  \"email\": \"pippo@pippo.it\",\n  \"phone\": \"01311750253\",\n  \"cod\": 10,\n  \"insurance\": 0,\n  \"notes\": \"testo delle note\",\n  \"customs_value\": 123.45,\n  \"currency\": \"EUR\",\n  \"warehouse\": \"\",\n  \"tag\" : \"pippo1\",\n  \"rows\": [\n    {\n    \t\"description\" : \"Cosa rossa 1\",\n      \"sku\": \"art3\",\n      \"qty\": 1\n    },\n    {\n    \t\"description\" : \"Cosa rossa 2\",\n      \"sku\": \"art4\",\n      \"qty\": 2\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("x-api-key", "YOUR-API-KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

{% endtab %}

{% tab title="C#" %}

```c
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Post,
    RequestUri = new Uri("https://api.gsped.it/sandbox/orders"),
    Headers =
    {
        { "x-api-key", "YOUR-API-KEY" },
    },
    Content = new StringContent("{\n  \"client_id\": 638,\n  \"order_ref\": \"test-gsped-3\",\n  \"name\": \"mario rossi\",\n  \"address\": \"piazza ambrosoli 13\",\n  \"city\": \"alessandria\",\n  \"zip\": \"15121\",\n  \"province\": \"AL\",\n  \"country\": \"IT\",\n  \"email\": \"pippo@pippo.it\",\n  \"phone\": \"01311750253\",\n  \"cod\": 10,\n  \"insurance\": 0,\n  \"notes\": \"testo delle note\",\n  \"customs_value\": 123.45,\n  \"currency\": \"EUR\",\n  \"warehouse\": \"\",\n  \"tag\" : \"pippo1\",\n  \"rows\": [\n    {\n    \t\"description\" : \"Cosa rossa 1\",\n      \"sku\": \"art3\",\n      \"qty\": 1\n    },\n    {\n    \t\"description\" : \"Cosa rossa 2\",\n      \"sku\": \"art4\",\n      \"qty\": 2\n    }\n  ]\n}")
    {
        Headers =
        {
            ContentType = new MediaTypeHeaderValue("application/json")
        }
    }
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url https://api.gsped.it/sandbox/orders \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR-API-KEY' \
  --data '{
  "client_id": 638,
  "order_ref": "test-gsped-3",
  "name": "mario rossi",
  "address": "piazza ambrosoli 13",
  "city": "alessandria",
  "zip": "15121",
  "province": "AL",
  "country": "IT",
  "email": "pippo@pippo.it",
  "phone": "01311750253",
  "cod": 10,
  "insurance": 0,
  "notes": "testo delle note",
  "customs_value": 123.45,
  "currency": "EUR",
  "warehouse": "",
  "tag" : "pippo1",
  "rows": [
    {
    	"description" : "Cosa rossa 1",
      "sku": "art3",
      "qty": 1
    },
    {
    	"description" : "Cosa rossa 2",
      "sku": "art4",
      "qty": 2
    }
  ]
}'
```

{% endtab %}
{% endtabs %}

## Edit orders and details of an existing order

<mark style="color:purple;">`PATCH`</mark> `https://api.gsped.it/[INSTANCE]/Orders/[ID_ORDINE]`

Lets you edit an order and its details on Gsped

#### Headers

| Name                                        | Type   | Description              |
| ------------------------------------------- | ------ | ------------------------ |
| x-api-key<mark style="color:red;">\*</mark> | String | APIKEY provided by Gsped |

#### Request Body

| Name                                         | Type   | Description                                                                                                                                                                                       |
| -------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| client\_id<mark style="color:red;">\*</mark> | Int    | Client ID Gsped                                                                                                                                                                                   |
| name<mark style="color:red;">\*</mark>       | String | Recipient name                                                                                                                                                                                    |
| order\_ref<mark style="color:red;">\*</mark> | String | Order reference                                                                                                                                                                                   |
| address<mark style="color:red;">\*</mark>    | String | Recipient address                                                                                                                                                                                 |
| cod                                          | Float  | Cash on delivery (COD) value                                                                                                                                                                      |
| phone<mark style="color:red;">\*</mark>      | String | Phone number                                                                                                                                                                                      |
| email<mark style="color:red;">\*</mark>      | String | Recipient email address                                                                                                                                                                           |
| country<mark style="color:red;">\*</mark>    | String | Country code iso 2 char                                                                                                                                                                           |
| province<mark style="color:red;">\*</mark>   | String | Province or State code                                                                                                                                                                            |
| zip<mark style="color:red;">\*</mark>        | String | Recipient zip code                                                                                                                                                                                |
| city<mark style="color:red;">\*</mark>       | String | Recipient city                                                                                                                                                                                    |
| rows.description                             | String | Order detail description                                                                                                                                                                          |
| warehouse                                    | String | Warehouse                                                                                                                                                                                         |
| notes                                        | String | Order notes                                                                                                                                                                                       |
| invoice\_number                              | String | Number of the order invoice                                                                                                                                                                       |
| invoice\_date                                | String | Date of the order invoice                                                                                                                                                                         |
| insurance                                    | Float  | Insured value                                                                                                                                                                                     |
| customs\_value                               | Float  | Customs value                                                                                                                                                                                     |
| rows.hs\_code                                | String | Detail HS code                                                                                                                                                                                    |
| rows.qty                                     | Int    | Detail quantity                                                                                                                                                                                   |
| rows.sku                                     | String | Detail SKU                                                                                                                                                                                        |
| rows.country\_of\_origin                     | String | Country code iso 2 char of origin of the goods                                                                                                                                                    |
| corriere                                     | Int    | Gsped courier ID                                                                                                                                                                                  |
| servizio                                     | Int    | Gsped courier service ID                                                                                                                                                                          |
| rcpt\_type                                   | Int    | Recipient type: 0 not specified, 1 private, 2 business. If not sent it stays unchanged                                                                                                            |
| rows.id                                      | Int    | ID of the detail to edit, returned when retrieving the order                                                                                                                                      |
| rows.dati\_doganali                          | Object | Customs data of the detail, in `dati_doganali.pid` the product codes, see [EU customs reform 2026](/gsped-api-english-version/spedizioni-e-dintorni/shipment/casi-duso/eu-customs-reform-2026.md) |
| vat\_code                                    | String | Recipient VAT number, max 20 char                                                                                                                                                                 |
| vat\_seller                                  | String | Seller VAT number, max 20 char                                                                                                                                                                    |
| sender\_eori                                 | String | Sender EORI number, max 20 char                                                                                                                                                                   |
| rcpt\_eori                                   | String | Recipient EORI number, max 20 char                                                                                                                                                                |
| ddt\_num                                     | Int    | Number of the shipment's transport document, max 15 digits                                                                                                                                        |
| tipo\_incasso                                | Int    | Cash on delivery collection type, see [Gsped codes](/gsped-api-english-version/overview/codici-gsped.md#cash-on-delivery-cod-payment-types)                                                       |
| chi\_paga                                    | Int    | Carriage: 0 paid, 1 forward                                                                                                                                                                       |
| addebito\_dogana                             | Int    | Who pays duties and customs charges: 0 default, 1 sender, 2 third party. `mittente`, `destinatario`, `terzo` are also accepted                                                                    |
| incoterm                                     | Object | Incoterm of the shipment, as in the Shipment, see [incoterm](/gsped-api-english-version/spedizioni-e-dintorni/shipment/shipment-objects/incoterm.md)                                              |
| parties                                      | Object | Customs parties of the shipment, as in the Shipment, see [parties](/gsped-api-english-version/spedizioni-e-dintorni/shipment/shipment-objects/parties.md)                                         |

{% hint style="info" %}
The details sent in `rows` are matched to the saved ones through `rows.id`:

* detail with `id`: only the fields sent are updated
* detail without `id`: it is added to the order
* saved detail not present in `rows`: it is deleted
* `rows` missing or empty: the details stay unchanged

An `id` that does not belong to the order or is repeated is rejected with a 400 error.\
`dati_doganali` sent replaces the saved one of the detail: codes not sent are deleted, `null` or empty deletes them all. If `dati_doganali` is not sent the codes stay unchanged.
{% endhint %}

{% hint style="info" %}
Shipment fields (`vat_seller`, `sender_eori`, `rcpt_eori`, `ddt_num`, `tipo_incasso`, `chi_paga`, `addebito_dogana`):

* not sent: they stay unchanged
* `null` or empty: they are deleted and the shipment will use the value Gsped derives from the order, see [Order To Shipment](/gsped-api-english-version/gestione-ordini/order-to-shipment.md)

`incoterm` and `parties` sent replace the saved ones; `null` or empty deletes them; if not sent they stay unchanged.
{% endhint %}

{% tabs %}
{% tab title="200: OK Order edited response" %}

```json
{
  "status": "OK",
  "order_id": 572602
}
```

{% endtab %}

{% tab title="400: Bad Request Wrong payload" %}

```json
{
  "status": "FAILED",
  "error": "Dati ordine non presenti o in formato sbagliato"
}
```

{% endtab %}

{% tab title="403: Forbidden Wrong API key response" %}

```json
{
  "status": false,
  "error": "Invalid API key "
}
```

{% endtab %}
{% endtabs %}

#### Example code snippets

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

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gsped.it/sandbox/orders/1",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => "{\n  \"client_id\": 638,\n  \"order_ref\": \"test-gsped-3\",\n  \"name\": \"mario rossi\",\n  \"address\": \"piazza ambrosoli 13\",\n  \"city\": \"alessandria\",\n  \"zip\": \"15121\",\n  \"province\": \"AL\",\n  \"country\": \"IT\",\n  \"email\": \"pippo@pippo.it\",\n  \"phone\": \"01311750253\",\n  \"cod\": 10,\n  \"insurance\": 0,\n  \"notes\": \"testo delle note\",\n  \"customs_value\": 123.45,\n  \"currency\": \"EUR\",\n  \"warehouse\": \"\",\n  \"tag\" : \"pippo1\",\n  \"rows\": [\n    {\n    \t\"description\" : \"Cosa rossa 1\",\n      \"sku\": \"art3\",\n      \"qty\": 1\n    },\n    {\n    \t\"description\" : \"Cosa rossa 2\",\n      \"sku\": \"art4\",\n      \"qty\": 2\n    }\n  ]\n}",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: YOUR-API-KEY"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

{% endtab %}

{% tab title="PYTHON" %}

```python
import http.client

conn = http.client.HTTPSConnection("api.gsped.it")

payload = "{\n  \"client_id\": 638,\n  \"order_ref\": \"test-gsped-3\",\n  \"name\": \"mario rossi\",\n  \"address\": \"piazza ambrosoli 13\",\n  \"city\": \"alessandria\",\n  \"zip\": \"15121\",\n  \"province\": \"AL\",\n  \"country\": \"IT\",\n  \"email\": \"pippo@pippo.it\",\n  \"phone\": \"01311750253\",\n  \"cod\": 10,\n  \"insurance\": 0,\n  \"notes\": \"testo delle note\",\n  \"customs_value\": 123.45,\n  \"currency\": \"EUR\",\n  \"warehouse\": \"\",\n  \"tag\" : \"pippo1\",\n  \"rows\": [\n    {\n    \t\"description\" : \"Cosa rossa 1\",\n      \"sku\": \"art3\",\n      \"qty\": 1\n    },\n    {\n    \t\"description\" : \"Cosa rossa 2\",\n      \"sku\": \"art4\",\n      \"qty\": 2\n    }\n  ]\n}"

headers = {
    'Content-Type': "application/json",
    'x-api-key': "YOUR-API-KEY"
    }

conn.request("PATCH", "/sandbox/orders/1", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
```

{% endtab %}

{% tab title="GO" %}

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://api.gsped.it/sandbox/orders/1"

	payload := strings.NewReader("{\n  \"client_id\": 638,\n  \"order_ref\": \"test-gsped-3\",\n  \"name\": \"mario rossi\",\n  \"address\": \"piazza ambrosoli 13\",\n  \"city\": \"alessandria\",\n  \"zip\": \"15121\",\n  \"province\": \"AL\",\n  \"country\": \"IT\",\n  \"email\": \"pippo@pippo.it\",\n  \"phone\": \"01311750253\",\n  \"cod\": 10,\n  \"insurance\": 0,\n  \"notes\": \"testo delle note\",\n  \"customs_value\": 123.45,\n  \"currency\": \"EUR\",\n  \"warehouse\": \"\",\n  \"tag\" : \"pippo1\",\n  \"rows\": [\n    {\n    \t\"description\" : \"Cosa rossa 1\",\n      \"sku\": \"art3\",\n      \"qty\": 1\n    },\n    {\n    \t\"description\" : \"Cosa rossa 2\",\n      \"sku\": \"art4\",\n      \"qty\": 2\n    }\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("x-api-key", "YOUR-API-KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

{% endtab %}

{% tab title="C#" %}

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Patch,
    RequestUri = new Uri("https://api.gsped.it/sandbox/orders/1"),
    Headers =
    {
        { "x-api-key", "YOUR-API-KEY" },
    },
    Content = new StringContent("{\n  \"client_id\": 638,\n  \"order_ref\": \"test-gsped-3\",\n  \"name\": \"mario rossi\",\n  \"address\": \"piazza ambrosoli 13\",\n  \"city\": \"alessandria\",\n  \"zip\": \"15121\",\n  \"province\": \"AL\",\n  \"country\": \"IT\",\n  \"email\": \"pippo@pippo.it\",\n  \"phone\": \"01311750253\",\n  \"cod\": 10,\n  \"insurance\": 0,\n  \"notes\": \"testo delle note\",\n  \"customs_value\": 123.45,\n  \"currency\": \"EUR\",\n  \"warehouse\": \"\",\n  \"tag\" : \"pippo1\",\n  \"rows\": [\n    {\n    \t\"description\" : \"Cosa rossa 1\",\n      \"sku\": \"art3\",\n      \"qty\": 1\n    },\n    {\n    \t\"description\" : \"Cosa rossa 2\",\n      \"sku\": \"art4\",\n      \"qty\": 2\n    }\n  ]\n}")
    {
        Headers =
        {
            ContentType = new MediaTypeHeaderValue("application/json")
        }
    }
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request PATCH \
  --url https://api.gsped.it/sandbox/orders/1 \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR-API-KEY' \
  --data '{
  "client_id": 638,
  "order_ref": "test-gsped-3",
  "name": "mario rossi",
  "address": "piazza ambrosoli 13",
  "city": "alessandria",
  "zip": "15121",
  "province": "AL",
  "country": "IT",
  "email": "pippo@pippo.it",
  "phone": "01311750253",
  "cod": 10,
  "insurance": 0,
  "notes": "testo delle note",
  "customs_value": 123.45,
  "currency": "EUR",
  "warehouse": "",
  "tag" : "pippo1",
  "rows": [
    {
    	"description" : "Cosa rossa 1",
      "sku": "art3",
      "qty": 1
    },
    {
    	"description" : "Cosa rossa 2",
      "sku": "art4",
      "qty": 2
    }
  ]
}'
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
N.B. You cannot edit an order if it is linked to a shipment that has already been confirmed.
{% endhint %}

Behaviour when the order is linked to a shipment still to be confirmed:\
if the shipment is non-EU and the courier supports CINs, if the courier supports the shipmentPatch of CIN data, the update is performed on the courier; otherwise the shipment is set to error because it must be regenerated with the new order data.