> 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/order-to-shipment.md).

# Order To Shipment

Shipment creation from an order

This endpoint is used to fulfil orders downloaded by Gsped from marketplaces or e-commerce platforms through its own connectors.

The call to this endpoint generates the shipment using the order's shipping address as the recipient.

## Shipment creation from an Order

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

Creates a shipment from an order to get it fulfilled and updated on the e-commerce/marketplace platform

#### 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                                                            |
| packages<mark style="color:red;">\*</mark>   | Int    | Number of parcels                                                          |
| order\_ref<mark style="color:red;">\*</mark> | String | Order reference                                                            |
| weight<mark style="color:red;">\*</mark>     | Float  | Order weight                                                               |
| platform                                     | String | Name of the platform the order originates from                             |
| labelType                                    | Enum   | <p>Possible values are: PDF/ZPL<br>Some couriers may have restrictions</p> |

{% tabs %}
{% tab title="200: OK Shipment created response" %}

```javascript
{
  "status": "OK",
  "order_ref": "FC3926207",
  "label_jpg": [
    "base64 label string"
  ],
  "label_pdf": [
    "base64 label string"
  ],
  "label_zpl": [
    "ZPL label string"
  ]
}
```

{% endtab %}

{% tab title="400: Bad Request Order not found response" %}

```javascript
{
  "status": "ERROR",
  "error_description": "Ordine non trovato",
  "order_ref": "WrongRif"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Generic errors" %}

```javascript
```

{% endtab %}

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

```javascript
{
  "status": "ERROR",
  "error_description": "Dati ordine non presenti o in formato sbagliato",
  "order_ref": ""
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid customs data" %}

```javascript
{
  "status": "ERROR",
  "error_description": "incoterm_code: The incoterm code field must be 3 characters.",
  "order_ref": "FC3926207"
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The response contains the `warnings` field, always present, with the warnings on the created shipment, see [EU customs reform 2026](https://apidocs.gsped.com/gsped-api-english-version/spedizioni-e-dintorni/shipment/casi-duso/eu-customs-reform-2026.md#warnings).
{% endhint %}

#### Example code snippets

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

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gsped.it/sandbox/OrderToShipment",
  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\t\"client_id\": 1,\n\t\"order_ref\": \"14326\",\n\t\"packages\": 2,\n\t\"platform\": \"woocommerce\",\n\t\"weight\": 7.09\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\t\"client_id\": 1,\n\t\"order_ref\": \"14326\",\n\t\"packages\": 2,\n\t\"platform\": \"woocommerce\",\n\t\"weight\": 7.09\n}"

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

conn.request("POST", "/sandbox/OrderToShipment", 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/OrderToShipment"

	payload := strings.NewReader("{\n\t\"client_id\": 1,\n\t\"order_ref\": \"14326\",\n\t\"packages\": 2,\n\t\"platform\": \"woocommerce\",\n\t\"weight\": 7.09\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#" %}

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Post,
    RequestUri = new Uri("https://api.gsped.it/sandbox/OrderToShipment"),
    Headers =
    {
        { "x-api-key", "YOUR-API-KEY" },
    },
    Content = new StringContent("{\n\t\"client_id\": 1,\n\t\"order_ref\": \"14326\",\n\t\"packages\": 2,\n\t\"platform\": \"woocommerce\",\n\t\"weight\": 7.09\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/OrderToShipment \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR-API-KEY' \
  --data '{
	"client_id": 1,
	"order_ref": "14326",
	"packages": 2,
	"platform": "woocommerce",
	"weight": 7.09
}'
```

{% endtab %}
{% endtabs %}

## Data passed from the order to the shipment

The shipment is created with the order's shipping address as the recipient and with this data:

| Shipment field            | Where it comes from                                                                                                                                                           |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ddt_alpha`               | the order's `order_ref`                                                                                                                                                       |
| `ddt_num`                 | the order's `ddt_num` if set; otherwise `order_ref` if numeric and shorter than 12 digits, otherwise the order ID on the e-commerce platform, otherwise the Gsped shipment ID |
| `valore` (insured value)  | the order's `insurance`                                                                                                                                                       |
| `valore_doganale`         | the order's `customs_value`; if missing and the destination is abroad, the order total                                                                                        |
| `tipo_incasso`            | the order's `tipo_incasso` if set; otherwise, if the order has cash on delivery, the client's default collection type                                                         |
| `addebito_dogana`         | the order's `addebito_dogana` if set; otherwise the client and courier defaults                                                                                               |
| `chi_paga`                | the order's `chi_paga` if set; otherwise 0, carriage paid                                                                                                                     |
| `sender_eori`             | the order's `sender_eori` if set; otherwise the EORI configured on the client                                                                                                 |
| `rcpt_eori`, `vat_seller` | the order's values if set; otherwise empty                                                                                                                                    |
| `vat_buyer`               | the order's `vat_code` if set; otherwise empty                                                                                                                                |
| `incoterm`, `parties`     | the order's values if set                                                                                                                                                     |

The order fields are described on the [Orders](https://apidocs.gsped.com/gsped-api-english-version/gestione-ordini/orders.md) page.

{% hint style="warning" %}
The order's `incoterm` and `parties` are validated for the shipment's courier. If they are not valid the call returns 400 with the error, the shipment is not created and the order stays to be fulfilled.

If the courier does not handle customs data, including when the courier is assigned by the rate lists, they are ignored.
{% endhint %}
