Create Shipment

Creating a shipment, requires the sender's address, recipient's address, and a parcel (one or more items and their related information). Find below more details on how you can create a shipment

Create Shipment

POST https://api-sandbox.shiplemon.com/v1/shipments

Request Body

NameTypeDescription

related_order_id

string

You can use this to store your internal reference id

cash_on_delivery

number

Cash on Delivery (Αντικαταβολή) will be allowed only if you have provided your own credentials when using the rated carrier

rate_id*

string

This is the selected rate (the id of the rate selected in the /rates request) This string is not a string that you have to create. 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

items*

array

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. Each item in this array is an object in the following format (all the dimensions are in cm and the weight in grams) The value and currency fields are optional { "weight":1000, "height":20, "width":20, "length":20, "notes":"nike air max", "value":20, "currency": "EUR" }

address_from*

object

This object describes where the pickup of the item will happen. This is the starting point (point A) of the shipment. company, address2, notes and zip are optional and can accept null This object looks like this: { "country":"GR", "zip":"14451", "name": "Kostas Papadopoulos", "company": "Papadopoulou IKE", "address": "Papadopoulou 23", "address2": "Floor 2", "city": "Athens", "phone": "+306945723940", "email": "example@gmail.com", "country": "GR", "notes": "call me" } In the country parameter we accept the ALPHA-2 code format. You can find more here: https://www.iban.com/country-codes)

address_to*

object

The same format as the address_from in order to define the destination of the shipment (point B)

incoming_order_id

string

Use this parameter to link this shipment as a child of an incoming order

extras

object

See request example for object properties

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 

{
    "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

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
        }
    }'

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"
}
PreviousShipmentsNextCreate Shipment for Locker

Last updated