# Create Shipment

## Create Shipment

<mark style="color:green;">`POST`</mark> `https://api-sandbox.shiplemon.com/v1/shipments`

#### Request Body

<table><thead><tr><th width="248">Name</th><th width="143">Type</th><th>Description</th></tr></thead><tbody><tr><td>related_order_id</td><td>string</td><td>You can use this to store your internal reference id</td></tr><tr><td>cash_on_delivery</td><td>number</td><td><strong>Cash on Delivery (Αντικαταβολή) will be allowed only if you have provided your own credentials when using the rated carrier</strong></td></tr><tr><td>rate_id<mark style="color:red;">*</mark></td><td>string</td><td>This is the selected rate (the id of the rate selected in the /rates request)<br><br>This string is not a string that you have to create. <br><br>It will be provided and you have to include it in the shipment request in order for us to know the selected option of the user<br></td></tr><tr><td>items<mark style="color:red;">*</mark></td><td>array</td><td>This is an array that describes more details about the items that will be sent in the shipment and that you want to get rates for.<br><br>Each item in this array is an object in the following format (all the dimensions are in <em><strong>cm</strong></em> and the weight in <em><strong>grams</strong></em>)<br><br>The <strong>value</strong> and <strong>currency</strong> fields are optional<br><br><code>{</code><br>   <code>"weight":1000,</code><br>   <code>"height":20,</code><br>   <code>"width":20,</code><br>   <code>"length":20,</code><br>   <code>"notes":"nike air max",</code>      <br>   <code>"value":20,</code><br>   <code>"currency": "EUR"</code><br><code>}</code></td></tr><tr><td>address_from<mark style="color:red;">*</mark></td><td>object</td><td>This object describes where the pickup of the item will happen. This is the starting point (point A) of the shipment.<br><br><code>company</code>, <code>address2</code>, <code>notes</code> and <code>zip</code> are optional and can accept <strong>null</strong><br><br>This object looks like this:<br><br><code>{</code> <br>    <code>"country":"GR",</code> <br>    <code>"zip":"14451",</code><br>    <code>"name": "Kostas Papadopoulos",</code> <br>    <code>"company": "Papadopoulou IKE",</code> <br>    <code>"address": "Papadopoulou 23",</code><br>    <code>"address2": "Floor 2",</code><br>    <code>"city": "Athens",</code><br>    <code>"phone": "+306945723940",</code><br>    <code>"email": "example@gmail.com",</code><br>    <code>"country": "GR",</code><br>    <code>"notes": "call me"</code>            <br><code>}</code><br><br>In the country parameter we accept the ALPHA-2 code format. You can find more here:<br>https://www.iban.com/country-codes)</td></tr><tr><td>address_to<mark style="color:red;">*</mark></td><td>object</td><td>The same format as the address_from in order to define the destination of the shipment (point B)</td></tr><tr><td>incoming_order_id</td><td>string</td><td>Use this parameter to link this shipment as a child of an incoming order</td></tr><tr><td>extras</td><td>object</td><td>See request example for object properties</td></tr><tr><td>label_print_format</td><td>string</td><td>See available options for each carrier <a href="label-print-format">here</a></td></tr></tbody></table>

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

```
```

{% endtab %}
{% endtabs %}

## Example data for request (eg. DHL)

* *extras*:
  * *insurance\_amount*: the declared amount for the package to be insured
  * *is\_saturday\_delivery*: if the delivery is about to happen on Saturday (if the carrier support it)
  * *is\_customs\_invoice\_document*: boolean flag that indicates if the upload PDF is invoice document to be used for customs&#x20;

```
{
    "address_from":{
        "country":"GR",
        "company":"",
        "name":"John Doe",
        "phone":"+306912345678",
        "email":"john@mail.com",
        "address":"Jane Street 1",
        "state":"I",
        "city":"Athens",
        "zip":"11111",
    },
    "address_to":{
        "country":"GR",
        "country_code":"GR",
        "dial_code":"+30",
        "name":"Mary Doe",
        "zip":"11111",
        "city":"Athns",
        "address":"Jane Street 2",
        "phone":"+306912345678"
    },
    "items":[{
        "width":1,
        "height":1,
        "length":1,
        "weight":5000,
        "label":"Box",
        "notes":"Box",
        "invoice_lines":[],
    }],
    "rate_id":"elta_1_790db74a-2b6f-4eaa-8918-60de9f192bca",
    "cash_on_delivery":null,
    "related_order_id":null,
    "extras": {
        "insurance_amount": 100,
        "is_customs_invoice_document": false,
        "is_saturday_delivery": true
    }
}
```

#### Scheduling a pickup

You can also add the following if you want to schedule courier to PICKUP from address\_from, otherwise set it to `null` or don't provide this property in the JSON completely.\
\
Important! you can set pickup only for rates that support it `"has_pickup": true`

```
    "pickup": {
      "date": "YYYY-MM-DD"
    }
```

## Request

Example request body

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

```erlang
curl -x POST https://api-sandbox.shiplemon.com/v1/shipments/  \
    -H "x-api-key: <YOUR_API_KEY>" \
    -H "Content-Type: application/json"  \
    -d '{
       "address_from": { 
            "country":"GR", 
            "zip":"14451",
            "name": "Kostas Papadopoulos", 
            "company": "Papadopoulou IKE", 
            "address": "Papadopoulou 23",
            "address2": "Floor 2"
            "city": "Athens",
            "phone": "+306900000000",
            "email": "example@gmail.com"
            "country": "GR",
            "notes": "call me"            
        },
        "address_to": {
            "name": "SG2",
            "country": "GR",
            "state": "I",
            "city": "Athens",
            "zip": "14451",
            "address": "Kolokotroni 2",
            "email": "example2@gmail.com",
            "phone": "+306900000000"
        },
        "items": [
            {
                "weight": 2000,
                "height": 10,
                "width": 10,
                "length": 10,
                "notes": "Clothes",
                "invoice_lines":[],
            }
        ],
        "rate_id": "ups_65_f77b5a8f-f66f-42b6-b84a-f0a18f82cfe8",
        "cash_on_delivery":10,
        "related_order_id":"23",
        "extras": {
            "insurance_amount": 100,
            "is_customs_invoice_document": false,
            "is_saturday_delivery": true
        }
    }'

```

{% endtab %}
{% endtabs %}

## Response

Returns the created shipment

```
{
  "invoice_id": null,
  "partner_credentials_used": false,
  "related_order_id": null,
  "incoming_order_id": null,
  "return_request_id": null,
  "payment_ref": "pi_3OEtQXIqzMDoBM8m1O3fe0Uy",
  "payment_amount": 9.72,
  "state": "created",
  "driver": "ups",
  "pickup_ref": "2929602E9CP",
  "pickup_list_ref": null,
  "tracking_ref": "1ZXXXXXXXXXXXXXXXX",
  "tracking_url": "https://www.ups.com/track?tracknum=1ZXXXXXXXXXXXXXXXX",
  "tracking_status": "PRE_TRANSIT",
  "tracking_history": [
    {
      "status": "DELIVERED",
      "status_date": "2023-11-20T00:00:01.992Z",
      "status_details": "ΠΑΡΑΔΟΣΗ ΑΠΟ ΔΙΑΝΟΜΕΑ"
    },
    {
      "status": "EXCEPTION",
      "status_date": "2023-11-20T00:00:02.195Z",
      "status_details": "ΑΚΥΡΩΣΗ ΑΠΟ ΔΙΑΝΟΜΕΑ"
    },
    {
      "status": "TRANSIT",
      "status_date": "2023-11-20T00:00:02.075Z",
      "status_details": "ΕΚΦΟΡΤΩΣΗ ΑΠΟ ΜΕΤΑΦΟΡΙΚΟ ΜΕΣΟ"
    },
    {
      "status": "PRE_TRANSIT",
      "status_date": "2023-11-20T00:00:02.064Z",
      "status_details": "ΔΗΜΙΟΥΡΓΙΑ ΣΥ.ΔΕ.ΤΑ. ΑΠΟ ΠΕΛΑΤΗ"
    }
  ],
  "tracking_history_last_updated_at": "2022-08-08T09:15:00.947Z", 
  "label_url": "https://static.shiplemon.com/sandbox/labels/ups/1ZXXXXXXXXXXXXXXXX.pdf",
  "child_vouchers": [
    {
      "tracking_ref": "2338891501",
      "tracking_url": "",
      "label_url": "https://static.shiplemon.com/sandbox/labels/boxnow/2338891501.pdf"
    }
  ],
  "address_from": { 
    "country":"GR", 
    "zip":"14451",
    "name": "Kostas Papadopoulos", 
    "company": "Papadopoulou IKE", 
    "address": "Papadopoulou 23",
    "address2": "Floor 2"
    "city": "Athens",
    "phone": "+306900000000",
    "email": "example@gmail.com"
    "country": "GR",
    "notes": "call me"            
  },
  "address_to": {
    "name": "SG2",
    "country": "GR",
    "state": "I",
    "city": "Athens",
    "zip": "14451",
    "address": "Kolokotroni 2",
    "email": "example2@gmail.com",
    "phone": "+306900000000"
  },
  "items": [
    {
      "width": 20,
      "height": 20,
      "length": 20,
      "weight": 1600,
      "label": "Box",
      "notes": "Box",
      "invoice_lines": [
        {
          "country_of_origin": "GR",
          "description": "glasses-RETURN TO ORIGIN",
          "commodity_code": "9004.90.10",
          "quantity": "1",
          "value": 10,
          "weight": 500
        }
      ]
    }
  ],
  "pickup": {
    "date": "2023-11-22",
    "time": "11:00-17:00"
  },
  "pickup_at": null,
  "delivered_at": null,
  "refunded_at": null,
  "rate": {
    "id": "dhl_N_eea60867-02d5-4795-b27d-87f85685465c",
    "friendly_name": null,
    "driver": "dhl",
    "provider": {
      "name": "DHL",
      "image": "https://static.shiplemon.com/providers/dhl.svg"
    },
    "service": {
      "code": "dhl_express_domestic",
      "name": "Domestic Express",
      "estimated_delivery_in_days": 4
    }, 
    "total_amount": 9.72,
    "total_without_tax_amount": 7.84,
    "tax_amount": 1.88,
    "currency": "EUR",
    "has_cash_on_delivery": false,
    "has_custom_credentials": false,
    "has_shipment_pickup_combined": false,
    "has_pickup": true,
    "transportation": "road",
    "has_mass_printing": false,
    "has_customs_invoice_upload": false,
    "has_insurance_ability": false,
    "has_saturday_delivery": false,
    "has_same_day_pickup": true,
    "pickup_slot_length_in_hours": 2,
    "pickup_same_day_latest_at": "17:00",
    "pickup_earliest_at": "13:00",
    "pickup_latest_at": "17:00",
    "metadata": {
      "items": [
        {
          "width": 20,
          "height": 20,
          "length": 20,
          "weight": 1600,
          "label": "Box",
          "notes": "Box",
          "invoice_lines": [
            {
              "country_of_origin": "GR",
              "description": "glasses-RETURN TO ORIGIN",
              "commodity_code": "9004.90.10",
              "quantity": "1",
              "value": 10,
              "weight": 500
            }
          ]
        }
      ],
      "address_from": { 
        "country":"GR", 
        "zip":"14451",
        "name": "Kostas Papadopoulos", 
        "company": "Papadopoulou IKE", 
        "address": "Papadopoulou 23",
        "address2": "Floor 2"
        "city": "Athens",
        "phone": "+306900000000",
        "email": "example@gmail.com"
        "country": "GR",
        "notes": "call me"            
      },
      "address_to": {
        "name": "SG2",
        "country": "GR",
        "state": "I",
        "city": "Athens",
        "zip": "14451",
        "address": "Kolokotroni 2",
        "email": "example2@gmail.com",
        "phone": "+306900000000"
      },
    }
  },
  "cash_on_delivery": 0,
  "extras": {
    "insurance_amount": 100, // number or undefined
    "is_customs_invoice_document": false, // boolean or undefined
    "is_saturday_delivery": false // boolean or undefined
  },
  "created_at": "2023-11-21T12:51:51.422Z",
  "updated_at": "2023-11-21T12:51:51.422Z"
}
```