# Overview Shiplemon provides an API to programmatically get parcel rates, create shipments and automate the process of sending packages ## Why do you need an API? ![Sending a package from point A to point B](/files/-MR08PD04bnwdurxJO9z) If you own a marketplace, an e-shop, a website, or any other kind of platform that sends packages, gifts, or any type of products, every time that a new order comes in, you have to find a way to send it to the client. If you want to do that automatically by connecting your system with a general API, Shiplemon can help you automate the full process. Using the Shiplemon API, you can send requests in order to get the rates of sending a package from a pick up point (point A) to a final destination of a shipment (point B), create a shipment and get the related documents that will help you (or your clients) send a package between point A and point B Once a shipment is created, the select carrier (selected either by user in your web app or mobile app, or selected by you based on specific criteria) will come in the senders address (pick up address), will pick up one or more items/packages and will deliver them in the final destination Some of the carriers require printing of the label The label should be placed in the package before the pickup of the item takes place. ## What can you do with the Shiplemon API? * Ask for a price (rate) for a shipment between two points A and B * Create a shipment voucher for a specific shipment * Print the pdf of the voucher (the voucher contains the barcode needs to be scanned by the carrier during the pickup) * Schedule a pickup for a given date and time (so that the carrier comes and picks up the package) ## How can I start? 1. Create an account here: 2. Read important first steps: [/pages/-MVLpRFtVOR0eC-F\_z4V#1.-starting-the-integration](https://docs.shiplemon.com/pages/-MVLpRFtVOR0eC-F_z4V#1.-starting-the-integration "mention") 3. Find your API key under **Settings > Profile** 4. Start sending requests to the API ([Get Rates](/endpoints/rates/get-rates#get-rates) is a good starting point) # Authentication In order to use the API of Shiplemon.com, you should contact us in order to create an API key for you. Start by sending an email at info\@shiplemon.com Each request you make to the API must include the following HTTP header in order to authenticate with the Shiplemon API ``` 'x-api-key': 'YOUR_API_KEY' ``` Replace the `YOUR_API_KEY` with your own API key. All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. API requests without the above `x-api-key` header will also fail. {% hint style="warning" %} **Keep Your API Keys Secure** Your API keys carry many privileges, so be sure to keep them secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, and so forth. Make sure to familiarize yourself with security best practices around storing and using API keys. Never ever hard-code the API key into source control systems like Git, but extract this information into environment variables instead. In the event, your API key is compromised, immediately revoke it from your account dashboard and create a new API key. {% endhint %} # Errors In the section we provide more details about the errors and the standardisation we use The API of Shiplemon uses standard HTTP error and status codes to communicate errors. There are multiple HTTP status codes for different types of errors: * `200 Ok` — The request was performed successfully. * `400 Bad Request` — The request was unacceptable, often due to missing a required parameter (for example user input error) * `401 Unauthorized` — No valid access token provided. The access token was either missing or expired. * `403 Forbidden` — The access token doesn't have permission to perform the request. * `404 Not Found` — The requested resource doesn't exist. * `422 Unprocessable Entity` — The request was malformed. * `500 Internal Server Error` — An unexpected error occurred on our server. In most cases, such an error represents a bug or issue on our side. We automatically log such errors and fix them quickly. If anything like this persists, feel free to directly contact us at ## Example validation error The API follows this format for errors and validation issues. If you have any specific issue that you can't solve please contact our support: ``` { "error": { "code": "NOT_FOUND", "message": "Shipment does not exist", "metadata": null } } ``` # Testing (important) This section provides more details on how you should test the integration before going live ## 1. Starting the integration When starting a new integration it is important to not start directly creating shipments and pickups in the LIVE environment. You should first test your integration in the staging environment of Shiplemon.com and then move to the production environment. To start with, each request provided in this documentation should be made to the following url ``` https://api-sandbox.shiplemon.com ``` {% hint style="info" %} Before moving to a production environment ensure that you can see all the shipments in the Shiplemon partners dashboard (see below). After having everything in place you can change the url above by removing the "-sandbox" {% endhint %} ## 2. For every request you make you can see the result in the partners dashboard Every shipment that is created through the API is also available in our brand new partners dashboard. In the dashboard you can also create shipments, cancel shipments etc. An example image shows how your dashboard should look like after creating your first shipments. In the first tests in order to see the dashboard your can open your browser and navigate to the following url. To login you can provide your API key. ``` https://app-sandbox.shiplemon.com ```
## 3. Going to production Once the integration is ready and you have everything in place you can move to the live environments ``` https://app.shiplemon.com (Dashboard) https://api.shiplemon.com (Production/Live API) ``` # Validation & Data A few data lists that you may find handy while integrating with us We **strongly recommend you use these directly** as we update them often and make sure their data is as correct as possible according to our customer support knowledgebase.\ (don't worry about uptime on these links, it's pretty reliable) Visit this page every once in a while because we keep adding more. \ \ \ \ \ \ \ \ \ \ \ \ \ \ # Rates If you want to send a packages from a point A to a point B, you would probably want to know first what is the cost of it, and what are the different options in order to send your package. Check the Get Rates and Get a Rate pages # Get Rates Generate rates for all enabled carriers by providing a route (A to B) ## Get Rates `POST` `https://api-sandbox.shiplemon.com/v1/rates` This method returns all the rates available in order to create a shipment #### Request Body | Name | Type | Description | | ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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)

For domestic and EU shipments the value parameter is optional.

{"weight":1000,
"height":20,
"width":20,
"length":20,
"value":20,
"notes":"nike air max"}

| | address\_from | object |

This object describes where the pickup of the item will happen. This is the starting point (point A) of the shipment.

This object requires the following details:
{"country": "GR","zip": "14451"}
OR
{"country": "AE","city": "Dubai"}

In cases where zip is available, zip is required. If country doesn't support zip code or postal code, then the city parameter is required.

Here's a list that we adhere to for zip rules per country:


In the country parameter we accept the ALPHA-2 code format. You can find more here:
)

| | address\_to | object | The same format as the address\_from in order to define the destination of the shipment (point B) | {% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% endtabs %} ## Specific examples per language {% tabs %} {% tab title="cURL" %} ``` curl --location --request POST 'https://api-sandbox.shiplemon.com/v1/rates' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "address_from": { "country": "GR", "zip": "14451" }, "address_to": { "country": "DE", "zip": "81667" }, "items": [ { "weight": 2000, "height": 10, "width": 10, "length": 10, "notes": "", "value": 20 } ] }' ``` {% endtab %} {% endtabs %} ## Example data for request * Weight : Weight of package in grams (int) * Height : Height of package in cm (int) * Width : Widht of package in cm (int) * Lenght : Length of package in cm (int) * Value : Value of package in designated currency (int) * Currency : Designated currency. Supports all of ISO currency strings. Default is EUR ``` { "items": [ { "weight": 3000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" } ], "address_from": { "country": "GR", "zip": "11111", "name": "John Doe", "state": "I", "city": "Athens", "address": "Jane Street 1", "email": "john@mail.com", "phone": "+3000000000", "notes": "" }, "address_to": { "name": "SG2", "country": "GR", "state": "I", "city": "Athens", "zip": "11111", "address": "Jane Street 2", "email": "mary@mail.com", "phone": "+3000000000" } } ``` ## Example response Returns an array of rates for each carrier. ``` { "id": "dhl_N_eea60867-02d5-4795-b27d-87f85685465c", "friendly_name": null, "driver": "dhl", "provider": { "name": "DHL Express", "image": "https://static.shiplemon.com/providers/dhl.svg" }, "service": { "code": "dhl_express_domestic", "name": "Domestic Express", "estimated_delivery_in_days": 4 }, "total_amount": 11.47, "total_without_tax_amount": 9.25, "tax_amount": 2.22, "currency": "EUR", "has_cash_on_delivery": false, "has_custom_credentials": false, "has_shipment_pickup_combined": false, "has_pickup": true, "transportation": "road", "has_mass_printing": true, "has_customs_invoice_upload": true, "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": [ { "weight": 3000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" } ], "address_from": { "country": "GR", "zip": "11111", "name": "John Doe", "state": "I", "city": "Athens", "address": "Jane Street 1", "email": "john@mail.com", "phone": "+3000000000", "notes": "" }, "address_to": { "name": "SG2", "country": "GR", "state": "I", "city": "Athens", "zip": "11111", "address": "Jane Street 2", "email": "mary@mail.com", "phone": "+3000000000" } } } ``` # Get Rate This request returns the information of a single rate ## Get Rate `GET` `https://api-sandbox.shiplemon.com/v1/rates/:id` This endpoint allows you to get the rate by id #### Path Parameters | Name | Type | Description | | ---- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string |

Id of the rate
To be able to get a rate by id you should first get rates

An example id of a rate is:
acs\_2.48\_0c4abcce-4546-48c7-a82c-56190628a734

| {% tabs %} {% tab title="200 Cake successfully retrieved." %} ``` { "status": "ok", "data": { "id": "dhl_dhlexpress-domesticexpressdoc_20531b76ce4943bb95c51509fc6e945d", "driver": "dhl", "provider": { "name": "DHL Express", "image": "https://shippo-static.s3.amazonaws.com/providers/200/DHL.png" }, "service": { "name": "DOMESTIC EXPRESS DOC", "estimated_delivery_in_days": 1 }, "total_amount": 26.34, "currency": "EUR", "printing_required": true, "transportation": "road", "metadata": { "items": [ { "weight": 2000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" }, { "weight": 2000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" } ], "address_from": { "country": "GR", "zip": "14451" }, "address_to": { "country": "GR", "zip": "14121" } } } } ``` {% endtab %} {% endtabs %} ## Specific examples per language {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://api-sandbox.shiplemon.com/v1/rates/' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' ``` {% endtab %} {% endtabs %} ## Example response ``` { "status": "ok", "data": { "id": "ups_65_4e64eb17-222a-22ca-2218-ac228c5cb3da", "driver": "ups", "provider": { "name": "UPS", "image": "https://static.shiplemon.com/providers/ups.png" }, "service": { "code": "ups_saver", "name": "UPS Saver", "estimated_delivery_in_days": 2 }, "total_amount": 13.61, "total_without_tax_amount": 10.98, "tax_amount": 2.63, "currency": "EUR", "printing_required": true, "has_cash_on_delivery": false, "has_custom_credentials": false, "has_shipment_pickup_combined": false, "has_tracking_code_on_pickup": false, "has_pickup": true, "has_mass_printing": false, "is_inaccessible": false, "has_customs_invoice_upload": true "has_saturday_delivery": true, "has_insurance_ability": true, "has_same_day_pickup": false, "pickup_slot_length_in_hours": 2, "pickup_same_day_latest_at": "16:00", "pickup_earliest_at": "12:00", "pickup_latest_at": "18:00", "transportation": "road", "metadata": { "items": [ { "weight": 3000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" } ], "address_from": { "country": "GR", "zip": "11111", "name": "John Doe", "state": "I", "city": "Athens", "address": "Jane Street 1", "email": "john@mail.com", "phone": "+3000000000", "notes": "" }, "address_to": { "name": "SG2", "country": "GR", "state": "I", "city": "Athens", "zip": "11111", "address": "Jane Street 2", "email": "mary@mail.com", "phone": "+3000000000" } } } } ``` # Shipments [Create shipment](/endpoints/shipments/create-shipment) Create shipment for Locker [Cancel shipment](/endpoints/shipments/cancel-shipment) [List shipments](/endpoints/shipments/get-shipments) [List one shipment](/endpoints/shipments/get-shipment) # 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_idstringYou can use this to store your internal reference id
cash_on_deliverynumberCash on Delivery (Αντικαταβολή) will be allowed only if you have provided your own credentials when using the rated carrier
rate_id*stringThis 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*arrayThis 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*objectThis 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*objectThe same format as the address_from in order to define the destination of the shipment (point B)
incoming_order_idstringUse this parameter to link this shipment as a child of an incoming order
extrasobjectSee request example for object properties
label_print_formatstringSee available options for each carrier here
{% 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 ``` { "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: " \ -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" } ``` # Create Shipment for Locker 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_idstring

You can use this to store your internal reference id.

For example the related order to be matched for this shipment from the ecommerce platform

cash_on_deliverynumber

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

The amount for cash on delivery. If shipment does not use cash on delivery, set null

rate_id*stringThis 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",

"compartment_size": 1
}

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:

{

"loacation_id": "123",

"country":"GR",

"zip":"14451",

"name": "Kostas Papadopoulos",

"company": "Papadopoulou IKE",

"address": "Papadopoulou 23",

"address2": "Floor 2",

"city": "Athens",

"phone": "+306900000000",

"email":"example@email.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*objectThe same format as the address_from in order to define the destination of the shipment (point B)
incoming_order_idstringUse this parameter to link this shipment as a child of an incoming order
extrasobjectSee request example for object properties
{% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% endtabs %} ## Example data for request (eg. Boxnow) * *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":{ "location_id":"12345", "country":"GR", "company":"", "name":"John Doe", "phone":"+306912345678", "email":"john@mail.com", "address":"Jane Street 1", "state":"I", "city":"Athens", "zip":"11111", }, "address_to":{ "location_id":"67890", "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":[], "compartment_size": 1, }], "rate_id": "boxnow_next-day_40b892de-02ea-47f7-85d9-f9dccef1144f", "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: " \ -H "Content-Type: application/json" \ -d '{ "address_from": { "location_id": "12345", "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": { "location_id": "67890", "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", "compartment_size": 1, "invoice_lines":[ { "country_of_origin": "GR", "description": "glasses-RETURN TO ORIGIN", "commodity_code": "9004.90.10", "quantity": "1", "value": 10, "weight": 500 } ], } ], "rate_id": "boxnow_next-day_40b892de-02ea-47f7-85d9-f9dccef1144f", "cash_on_delivery":10, "related_order_id":"23", "extras": { "insurance_amount": 100, "is_customs_invoice_document": false, "is_saturday_delivery": false } }' ``` {% endtab %} {% endtabs %} ## Response Returns the created shipment ``` { "invoice_id": null, "partner_credentials_used": true, "related_order_id": null, "incoming_order_id": null, "return_request_id": null, "payment_ref": "ownaccount", "payment_amount": 9.72, "state": "created", "driver": "boxnow", "pickup_ref": null, "pickup_list_ref": null, "tracking_ref": "2338891501", "tracking_url": null, "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/boxnow/2338891501.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": { // if date not provided pickup is null "date": "2023-11-22", "time": "11:00-17:00" }, "pickup_at": null, "delivered_at": null, "refunded_at": null, "rate": { "id": "boxnow_next-day_40b892de-02ea-47f7-85d9-f9dccef1144f", "friendly_name": "BoxNow", "driver": "boxnow", "provider": { "name": "BOXNOW", "image": "https://static.shiplemon.com/providers/boxnow.svg" }, "service": { "code": "next-day", "name": "Next Day", "estimated_delivery_in_days": 2 }, "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": false, "pickup_slot_length_in_hours": 2, "pickup_same_day_latest_at": null, "pickup_earliest_at": null, "pickup_latest_at": null, "metadata": { "items": [ { "width": 20, "height": 20, "length": 20, "weight": 1600, "label": "Box", "notes": "Box", "compartment_size": 1, "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" } ``` # Import Shipment Importing 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 import a shipment ## Import Shipment `POST` `https://api-sandbox.shiplemon.com/v1/shipments/import` #### Request Body | Name | Type | Description | | ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | related\_order\_id | string |

You can use this to store your internal reference id.

For example the related order to be matched for this shipment from the ecommerce platform

| | cash\_on\_delivery | number |

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

The amount for cash on delivery. If shipment does not use cash on delivery, set null

| | driver | string |

This string is an optional string that you have to provide and indicates the carrier of the shipment

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

"compartment\_size": 1
}

| | 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:

{

"loacation\_id": "123",

"country":"GR",

"zip":"14451",

"name": "Kostas Papadopoulos",

"company": "Papadopoulou IKE",

"address": "Papadopoulou 23",

"address2": "Floor 2",

"city": "Athens",

"phone": "+306900000000",

"email":"",

"country": "GR",

"notes": "call me"
}

In the country parameter we accept the ALPHA-2 code format. You can find more here:
)

| | 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 | | tracking\_ref | string | This is the tracking reference provided from the carrier | | tracking\_url | string | The tracking URL for the shipment | | label\_url | string | The URL for the shipment label | | extras | object | See request example for object properties | {% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% endtabs %} ## Example data for request * *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":{ "location_id":"12345", "country":"GR", "company":"", "name":"John Doe", "phone":"+306912345678", "email":"john@mail.com", "address":"Jane Street 1", "state":"I", "city":"Athens", "zip":"11111", }, "address_to":{ "location_id":"67890", "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":[], "compartment_size": 1, }], "rate_id": "boxnow_next-day_40b892de-02ea-47f7-85d9-f9dccef1144f", "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: " \ -H "Content-Type: application/json" \ -d '{ "address_from": { "location_id": "12345", "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": { "location_id": "67890", "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", "compartment_size": 1, "invoice_lines":[ { "country_of_origin": "GR", "description": "glasses-RETURN TO ORIGIN", "commodity_code": "9004.90.10", "quantity": "1", "value": 10, "weight": 500 } ], } ], "rate_id": "boxnow_next-day_40b892de-02ea-47f7-85d9-f9dccef1144f", "cash_on_delivery":10, "related_order_id":"23", "extras": { "insurance_amount": 100, "is_customs_invoice_document": false, "is_saturday_delivery": false } }' ``` {% endtab %} {% endtabs %} ## Response Returns the created shipment ``` { "invoice_id": null, "partner_credentials_used": true, "related_order_id": null, "incoming_order_id": null, "return_request_id": null, "payment_ref": "ownaccount", "payment_amount": 9.72, "state": "created", "driver": "boxnow", "pickup_ref": null, "pickup_list_ref": null, "tracking_ref": "2338891501", "tracking_url": null, "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/boxnow/2338891501.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": { // if date not provided pickup is null "date": "2023-11-22", "time": "11:00-17:00" }, "pickup_at": null, "delivered_at": null, "refunded_at": null, "rate": { "id": "boxnow_next-day_40b892de-02ea-47f7-85d9-f9dccef1144f", "friendly_name": "BoxNow", "driver": "boxnow", "provider": { "name": "BOXNOW", "image": "https://static.shiplemon.com/providers/boxnow.svg" }, "service": { "code": "next-day", "name": "Next Day", "estimated_delivery_in_days": 2 }, "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": false, "pickup_slot_length_in_hours": 2, "pickup_same_day_latest_at": null, "pickup_earliest_at": null, "pickup_latest_at": null, "metadata": { "items": [ { "width": 20, "height": 20, "length": 20, "weight": 1600, "label": "Box", "notes": "Box", "compartment_size": 1, "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" } ``` # Update Shipment Find below more details on how you can update a shipment ## Update Shipment `PATCH` `https://api-sandbox.shiplemon.com/v1/shipments/:id` #### Request Body | Name | Type | Description | | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `metadata` | `object` | You can update the metadata object with any key value pair. Accepted values are `string`, `number` and `boolean` | Important! you should include always the entire object that you want to update ## Request Example request body {% tabs %} {% tab title="cURL" %} ```erlang curl -x POST https://api-sandbox.shiplemon.com/v1/shipments/:id \ -H "x-api-key: " \ -H "Content-Type: application/json" \ -d '{ "metadata": { "some_key_1": true, "some_key_2": "some value", "some_key_3": 3 } }' ``` {% endtab %} {% endtabs %} ## Response Returns the updated shipment ``` { "invoice_id": null, "partner_credentials_used": true, "related_order_id": null, "incoming_order_id": null, "return_request_id": null, "payment_ref": "ownaccount", "payment_amount": 9.72, "state": "created", "driver": "boxnow", "pickup_ref": null, "pickup_list_ref": null, "tracking_ref": "2338891501", "tracking_url": null, "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/boxnow/2338891501.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": { // if date not provided pickup is null "date": "2023-11-22", "time": "11:00-17:00" }, "pickup_at": null, "delivered_at": null, "refunded_at": null, "rate": { "id": "boxnow_next-day_40b892de-02ea-47f7-85d9-f9dccef1144f", "friendly_name": "BoxNow", "driver": "boxnow", "provider": { "name": "BOXNOW", "image": "https://static.shiplemon.com/providers/boxnow.svg" }, "service": { "code": "next-day", "name": "Next Day", "estimated_delivery_in_days": 2 }, "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": false, "pickup_slot_length_in_hours": 2, "pickup_same_day_latest_at": null, "pickup_earliest_at": null, "pickup_latest_at": null, "metadata": { "items": [ { "width": 20, "height": 20, "length": 20, "weight": 1600, "label": "Box", "notes": "Box", "compartment_size": 1, "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 }, "metadata" { "some_key_1": "some value", "some_key_2": true }, "created_at": "2023-11-21T12:51:51.422Z", "updated_at": "2023-11-21T12:51:51.422Z" } ``` # Get shipments Get all the shipments created by your API key ## Get Shipments `GET` `https://api-sandbox.shiplemon.com/v1/shipments` This endpoint allows you to get all shipments
{% tabs %} {% tab title="200 Returns a list with all the shipments." %} ``` { "status": "ok", "data": [ {},{}, { "id": "60476d7500e47cb69693a202", "driver": "dhl", "pickup_ref": null, "tracking_ref": "1190953890", "tracking_url": "http://www.dhl-usa.com/content/us/en/express/tracking.shtml?brand=DHL&AWB=1190953890", "tracking_status": "PRE_TRANSIT", "tracking_history": [], "label_url": "https://deliver.goshippo.com/2519d201e88b4be8a3500a84c1608374.pdf?Expires=1646829812&Signature=qjByvemk0FAA7fnKPpCtd~Almiz96cFGmKyGseVNSBD~sYu4b4Q5EdG~WEhjFRefknu5HQnA76P3YTEh2NGRYL~fRGeueyjPEEpqW~V1E5WIHkJBnpVDJFKutwevlryOPBDy0x3Px-KY7iFUgagDdofg4lPIoD-PZnWffPapgT1xZUZS~9esQOEcAqdrBPuSO1i3ufdBCJLRIoM7XALD2-VmWcQWi2qS5YokKDEcEuRj88lcBIxiY9V9Wp~cNukLidrJlEVmvsFPhBzY6Y5M5xwIrTKFZSyeTs-B7rZQUgE5jSvA7YNcm0raw-N2t72om47BXKp0uVKEtinQ6TUnOQ__&Key-Pair-Id=APKAJRICFXQ2S4YUQRSQ", "invoice_url": null, "address_from": { "country": "GR", "zip": "14451", "name": "SG1", "state": "I", "city": "Athens", "address": "Ermou 3", "email": "giouldasis.stratos+sg1@gmail.com", "phone": "+306933000000", "notes": "" }, "address_to": { "name": "SG2", "country": "GR", "state": "I", "city": "Athens", "zip": "14451", "address": "Dimosthenous 45", "email": "example@gmail.com", "phone": "+306933000000" }, "items": [ { "weight": 2000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" }, { "weight": 2000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" } ], "pickup": null, "rate": { "id": "dhl_dhlexpress-domesticexpressdoc_20531b76ce4943bb95c51509fc6e945d", "driver": "dhl", "provider": { "name": "DHL Express", "image": "https://shippo-static.s3.amazonaws.com/providers/200/DHL.png" }, "service": { "name": "DOMESTIC EXPRESS DOC", "estimated_delivery_in_days": 1 }, "total_amount": 26.34, "currency": "EUR", "printing_required": true, "transportation": "road", "metadata": { "items": [ { "weight": 2000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" }, { "weight": 2000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" } ], "address_from": { "country": "GR", "zip": "14451" }, "address_to": { "country": "GR", "zip": "14121" } } } } ] } ``` {% endtab %} {% endtabs %} ## Specific examples per language {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://api-sandbox.shiplemon.com/v1/shipments' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ }' ``` {% endtab %} {% endtabs %} ## Example response ``` { "status":"ok", "data":[{ "id":"be96511d-ba23-4268-bd8b-48c9cf930222", "partner_id":"6130aa18c713254a3719e222", "invoice_id":null, "partner_credentials_used":true, "related_order_id":null, "payment_ref":null, "payment_amount":null, "state":"created", "driver":"elta", "pickup_ref":null, "tracking_ref":"ZU500011420GR", "tracking_url":"https://www.elta-courier.gr/search?br=ZU500011420GR", "tracking_status":"PRE_TRANSIT", "tracking_history":[], "label_url":"https://static.shiplemon.com/labels/elta/ZU500011420GR.pdf", "address_from":{ "_id":"61a15f9cfb38f514bd732222", "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":[] }], "pickup":null, "pickup_at":null, "delivered_at":null, "rate":{ "id":"elta_1_790db74a-2b6f-4eaa-8918-60de9f192222", "driver":"elta", "provider":{ "name":"ELTA Courier", "image":"https://static.shiplemon.com/providers/eltacourier.svg" }, "service":{ "code":"elta_courier_porta_porta", "name":"Porta-Porta", "estimated_delivery_in_days":3 }, "total_amount":0, "total_without_tax_amount":0, "tax_amount":0, "currency":"EUR", "printing_required":true, "has_cash_on_delivery":true, "has_custom_credentials":true, "has_shipment_pickup_combined":false, "has_tracking_code_on_pickup":false, "has_pickup":false, "transportation":"road", "metadata":{ "address_from":{ "_id":"61a15f9cfb38f514bd732222", "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":[] }] }, "cash_on_delivery":0, "logs":[], "tags":[], "notifications":[], "created_at":"2022-01-03T08:30:23.065Z", "updated_at":"2022-01-03T08:30:23.081Z" }] } ``` ## Pagination Response ``` { "hasMore": false, "hasNextPage": false, "hasPrevPage": false, "limit": 10, "page": 1, "pagingCounter": 1, "totalDocs": 1, "totalPages": 1 } ``` Request (url params) ``` https://api-sandbox.shiplemon.com/v1/shipments?search=test&limit=10&page=1&tracking_status[]=PRE_TRANSIT&tracking_status[]=TRANSIT&tracking_status[]=DELIVERED&tracking_status[]=EXCEPTION&printed_status[]=printed&printed_status[]=pending ``` # Get shipment Returns a single shipment's information ## Get shipment `GET` `https://api-sandbox.shiplemon.com/v1/shipments/:id` Returns the shipment's information #### Path Parameters | Name | Type | Description | | ---- | ------ | ---------------------- | | id | string | The id of the shipment | {% tabs %} {% tab title="200 Returns a unique shipment by id" %} ``` { "data": { "id": "6033fea86358650f6f2d9f06", "driver": "ups", "pickup_ref": null, "tracking_ref": "1Z7810V10433677098", "tracking_url": "https://www.ups.com/track?tracknum=1Z7810V10433677098", "tracking_status": "PRE_TRANSIT", "tracking_history": [], "label_url": "https://static.weship.gr/labels/ups/1Z7810V10433677098.png", "invoice_url": null, "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" } ], "pickup": null, "rate": { "id": "ups_65_f77b5a8f-f66f-42b6-b84a-f0a18f82cfe8", "driver": "ups", "provider": { "name": "UPS", "image": "https://static.deliverback.gr/providers/ups.png" }, "service": { "name": "UPS Express Saver", "estimated_delivery_in_days": 1 }, "total_amount": 14.28, "currency": "EUR", "printing_required": true, "transportation": "road", "metadata": { "items": [ { "weight": 2000, "height": 10, "width": 10, "length": 10, "notes": "Nike air max", "value": 20 } ], "address_from": { "country": "GR", "zip": "14451" }, "address_to": { "country": "GR", "zip": "14121" } } } } } ``` {% endtab %} {% endtabs %} ## Example Request {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://api-sandbox.shiplemon.com/v1/shipments/' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ }' ``` {% endtab %} {% endtabs %} ## Example response ``` { "status":"ok", "data":{ "id":"be96511d-ba23-4268-bd8b-48c9cf930222", "partner_id":"6130aa18c713254a3719e222", "invoice_id":null, "partner_credentials_used":true, "related_order_id":null, "payment_ref":null, "payment_amount":null, "state":"created", "driver":"elta", "pickup_ref":null, "tracking_ref":"ZU500011420GR", "tracking_url":"https://www.elta-courier.gr/search?br=ZU500011420GR", "tracking_status":"PRE_TRANSIT", "tracking_history":[], "label_url":"https://static.shiplemon.com/labels/elta/ZU500011420GR.pdf", "address_from":{ "_id":"61a15f9cfb38f514bd732222", "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":[] }], "pickup":null, "pickup_at":null, "delivered_at":null, "rate":{ "id":"elta_1_790db74a-2b6f-4eaa-8918-60de9f192222", "driver":"elta", "provider":{ "name":"ELTA Courier", "image":"https://static.shiplemon.com/providers/eltacourier.svg" }, "service":{ "code":"elta_courier_porta_porta", "name":"Porta-Porta", "estimated_delivery_in_days":3 }, "total_amount":0, "total_without_tax_amount":0, "tax_amount":0, "currency":"EUR", "printing_required":true, "has_cash_on_delivery":true, "has_custom_credentials":true, "has_shipment_pickup_combined":false, "has_tracking_code_on_pickup":false, "has_pickup":false, "transportation":"road", "metadata":{ "address_from":{ "_id":"61a15f9cfb38f514bd732222", "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":[] }] }, "cash_on_delivery":0, "logs":[], "tags":[], "notifications":[], "created_at":"2022-01-03T08:30:23.065Z", "updated_at":"2022-01-03T08:30:23.081Z" } } ``` # Cancel Shipment This endpoint can be used to cancel a shipment. In order to cancel a shipment you have to provide as path variable the id of the shipment that needs to be cancelled ## Cancel Shipment `DELETE` `https://api-sandbox.shiplemon.com/v1/shipments/:id` This endpoint allows you to cancel the shipment with the given id #### Path Parameters | Name | Type | Description | | ---- | ------ | ------------------------------------------------------------------------------------------------------------------------------ | | id | string |

The `id` of the shipment that needs to be cancelled.
Cancelling a shipment also cancels the pickup.

| {% tabs %} {% tab title="200 shipment successfully canceled." %} ``` { "status": "ok", "data": { "id": "60476d7500e47cb69693a202", "driver": "dhl", "pickup_ref": "CBJ180121002626", "tracking_ref": "1190953890", "tracking_url": "http://www.dhl-usa.com/content/us/en/express/tracking.shtml?brand=DHL&AWB=1190953890", "tracking_status": "PRE_TRANSIT", "tracking_history": [], "label_url": "https://deliver.goshippo.com/2519d201e88b4be8a3500a84c1608374.pdf?Expires=1646829812&Signature=qjByvemk0FAA7fnKPpCtd~Almiz96cFGmKyGseVNSBD~sYu4b4Q5EdG~WEhjFRefknu5HQnA76P3YTEh2NGRYL~fRGeueyjPEEpqW~V1E5WIHkJBnpVDJFKutwevlryOPBDy0x3Px-KY7iFUgagDdofg4lPIoD-PZnWffPapgT1xZUZS~9esQOEcAqdrBPuSO1i3ufdBCJLRIoM7XALD2-VmWcQWi2qS5YokKDEcEuRj88lcBIxiY9V9Wp~cNukLidrJlEVmvsFPhBzY6Y5M5xwIrTKFZSyeTs-B7rZQUgE5jSvA7YNcm0raw-N2t72om47BXKp0uVKEtinQ6TUnOQ__&Key-Pair-Id=APKAJRICFXQ2S4YUQRSQ", "invoice_url": null, "address_from": { "country": "GR", "zip": "14451", "name": "SG1", "state": "I", "city": "Athens", "address": "Ermou 3", "email": "example@gmail.com", "phone": "+306933000000", "notes": "" }, "address_to": { "name": "SG2", "country": "GR", "state": "I", "city": "Athens", "zip": "14451", "address": "Dimosthenous 45", "email": "example@gmail.com", "phone": "+306933000000" }, "items": [ { "weight": 2000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" }, { "weight": 2000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" } ], "pickup": { "date": "2021-03-12", "time": "09:00-18:00" }, "rate": { "id": "dhl_dhlexpress-domesticexpressdoc_20531b76ce4943bb95c51509fc6e945d", "driver": "dhl", "provider": { "name": "DHL Express", "image": "https://shippo-static.s3.amazonaws.com/providers/200/DHL.png" }, "service": { "name": "DOMESTIC EXPRESS DOC", "estimated_delivery_in_days": 1 }, "total_amount": 26.34, "currency": "EUR", "printing_required": true, "transportation": "road", "metadata": { "items": [ { "weight": 2000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" }, { "weight": 2000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" } ], "address_from": { "country": "GR", "zip": "14451" }, "address_to": { "country": "GR", "zip": "14121" } } } } } ``` {% endtab %} {% endtabs %} ## Example Request {% tabs %} {% tab title="cURL" %} ``` curl --location --request DELETE 'https://api-sandbox.shiplemon.com/v1/shipments/' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' ``` {% endtab %} {% endtabs %} ## Example response ``` { "status":"ok", "data":{ "id":"be96511d-ba23-4268-bd8b-48c9cf930222", "partner_id":"6130aa18c713254a3719e222", "invoice_id":null, "partner_credentials_used":true, "related_order_id":null, "payment_ref":null, "payment_amount":null, "state":"created", "driver":"elta", "pickup_ref":null, "tracking_ref":"ZU500011420GR", "tracking_url":"https://www.elta-courier.gr/search?br=ZU500011420GR", "tracking_status":"PRE_TRANSIT", "tracking_history":[], "label_url":"https://static.shiplemon.com/labels/elta/ZU500011420GR.pdf", "address_from":{ "_id":"61a15f9cfb38f514bd732222", "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":[] }], "pickup":null, "pickup_at":null, "delivered_at":null, "rate":{ "id":"elta_1_790db74a-2b6f-4eaa-8918-60de9f192222", "driver":"elta", "provider":{ "name":"ELTA Courier", "image":"https://static.shiplemon.com/providers/eltacourier.svg" }, "service":{ "code":"elta_courier_porta_porta", "name":"Porta-Porta", "estimated_delivery_in_days":3 }, "total_amount":0, "total_without_tax_amount":0, "tax_amount":0, "currency":"EUR", "printing_required":true, "has_cash_on_delivery":true, "has_custom_credentials":true, "has_shipment_pickup_combined":false, "has_tracking_code_on_pickup":false, "has_pickup":false, "transportation":"road", "metadata":{ "address_from":{ "_id":"61a15f9cfb38f514bd732222", "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":[] }] }, "cash_on_delivery":0, "logs":[], "tags":[], "notifications":[], "created_at":"2022-01-03T08:30:23.065Z", "updated_at":"2022-01-03T08:30:23.081Z" } } ``` # Tracking These endpoints can be used to get and update the shipment tracking information ## Get Shipment Tracking `GET` `https://api-sandbox.shiplemon.com/public/v1/shipments/:id/tracking` This endpoint allows you to retrieve the shipment tracking information for a given `shipmentId`. #### Update interval: Call this endpoint every hour at **:05** and **:35**. {% tabs %} {% tab title="200 tracking info retrieved" %} ```json { "status": "ok", "data": { "partner_id": "partner_id", "driver": "elta", "carrier": { "code": "elta", "name": "ELTA Courier", "image": "https://static.shiplemon.com/providers/eltacourier.svg" }, "service": { "code": "elta_courier_porta_porta", "name": "Porta-Porta", "estimated_delivery_in_days": 6 }, "tracking_status": "DELIVERED", "tracking_history": [ { "status": "DELIVERED", "status_exact": null, "status_date": "2024-07-15T10:02:00.000Z", "status_details": "ΠΑΡΑΛΑΒΗ ΑΠΟ ΣΤΑΘΜΟ ΜΕ ΔΗΛΩΣΗ ΠΑΡΑΛΗΠΤΗ" }, { "status": "TRANSIT", "status_exact": "WITH_COURIER", "status_date": "2024-07-15T09:45:00.000Z", "status_details": "ΠΡΟΣ ΠΑΡΑΔΟΣΗ" }, { "status": "PRE_TRANSIT", "status_exact": null, "status_date": "2024-07-12T14:17:00.000Z", "status_details": "ΔΗΜΙΟΥΡΓΙΑ ΣΥ.ΔΕ.ΤΑ. ΑΠΟ ΠΕΛΑΤΗ" } ], "tracking_ref": "tracking_ref", "tracking_url": "tracking_url", "country_from": "GR", "country_to": "GR" } } ``` {% endtab %} {% endtabs %} ## Update Shipment Tracking `PUT` `https://api-sandbox.shiplemon.com/v1/shipments/:id/tracking` This endpoint allows you to update the shipment tracking with the given `shipmentId` #### Path Parameters
NameTypeDescription
idstringThe `id` of the shipment that needs to be updated.
tracking_historyarray

The payload should always include the entire tracking history.

  status: string;
  status_date: string;
  status_details: string;
  status_exact: string | null;
#### Accepted values The `status` and `status_date` have specific format as shown below: `status`: DELIVERED, TRANSIT, PRE\_TRANSIT, EXCEPTION (case sensitive)\ `status_date`: must be in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.sssZ) {% tabs %} {% tab title="200 shipment successfully updated." %} ```json { "status": "ok", "data": { "id": "60476d7500e47cb69693a202", "driver": "dhl", "pickup_ref": "CBJ180121002626", "tracking_ref": "1190953890", "tracking_url": "http://www.dhl-usa.com/content/us/en/express/tracking.shtml?brand=DHL&AWB=1190953890", "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" } ], "label_url": "https://deliver.goshippo.com/2519d201e88b4be8a3500a84c1608374.pdf?Expires=1646829812&Signature=qjByvemk0FAA7fnKPpCtd~Almiz96cFGmKyGseVNSBD~sYu4b4Q5EdG~WEhjFRefknu5HQnA76P3YTEh2NGRYL~fRGeueyjPEEpqW~V1E5WIHkJBnpVDJFKutwevlryOPBDy0x3Px-KY7iFUgagDdofg4lPIoD-PZnWffPapgT1xZUZS~9esQOEcAqdrBPuSO1i3ufdBCJLRIoM7XALD2-VmWcQWi2qS5YokKDEcEuRj88lcBIxiY9V9Wp~cNukLidrJlEVmvsFPhBzY6Y5M5xwIrTKFZSyeTs-B7rZQUgE5jSvA7YNcm0raw-N2t72om47BXKp0uVKEtinQ6TUnOQ__&Key-Pair-Id=APKAJRICFXQ2S4YUQRSQ", "invoice_url": null, "address_from": { "country": "GR", "zip": "14451", "name": "SG1", "state": "I", "city": "Athens", "address": "Ermou 3", "email": "example@gmail.com", "phone": "+306933000000", "notes": "" }, "address_to": { "name": "SG2", "country": "GR", "state": "I", "city": "Athens", "zip": "14451", "address": "Dimosthenous 45", "email": "example@gmail.com", "phone": "+306933000000" }, "items": [ { "weight": 2000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" }, { "weight": 2000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" } ], "pickup": { "date": "2021-03-12", "time": "09:00-18:00" }, "rate": { "id": "dhl_dhlexpress-domesticexpressdoc_20531b76ce4943bb95c51509fc6e945d", "driver": "dhl", "provider": { "name": "DHL Express", "image": "https://shippo-static.s3.amazonaws.com/providers/200/DHL.png" }, "service": { "name": "DOMESTIC EXPRESS DOC", "estimated_delivery_in_days": 1 }, "total_amount": 26.34, "currency": "EUR", "printing_required": true, "transportation": "road", "metadata": { "items": [ { "weight": 2000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" }, { "weight": 2000, "height": 10, "width": 30, "length": 20, "notes": "Nike air max", "value": 10, "currency": "EUR" } ], "address_from": { "country": "GR", "zip": "14451" }, "address_to": { "country": "GR", "zip": "14121" } } } } } ``` {% endtab %} {% endtabs %} ## Example Request {% tabs %} {% tab title="cURL" %} ``` curl --location --request PUT 'https://api-sandbox.shiplemon.com/v1/shipments//tracking' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' ``` {% endtab %} {% endtabs %} ## Example response ```json { "status":"ok", "data":{ "id":"be96511d-ba23-4268-bd8b-48c9cf930222", "partner_id":"partner_id", "invoice_id":null, "partner_credentials_used":true, "related_order_id":null, "payment_ref":null, "payment_amount":null, "state":"created", "driver":"elta", "pickup_ref":null, "tracking_ref":"tracking_ref", "tracking_url":"https://www.elta-courier.gr/search?br=ZU500011420GR", "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": "tracking_ref", "tracking_url": "", "label_url": "https://static.shiplemon.com/sandbox/labels/boxnow/2338891501.pdf" } ], "label_url":"https://static.shiplemon.com/labels/elta/ZU500011420GR.pdf", "address_from":{ "_id":"61a15f9cfb38f514bd732222", "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":[] }], "pickup":null, "pickup_at":null, "delivered_at":null, "rate":{ "id":"elta_1_790db74a-2b6f-4eaa-8918-60de9f192222", "driver":"elta", "provider":{ "name":"ELTA Courier", "image":"https://static.shiplemon.com/providers/eltacourier.svg" }, "service":{ "code":"elta_courier_porta_porta", "name":"Porta-Porta", "estimated_delivery_in_days":3 }, "total_amount":0, "total_without_tax_amount":0, "tax_amount":0, "currency":"EUR", "printing_required":true, "has_cash_on_delivery":true, "has_custom_credentials":true, "has_shipment_pickup_combined":false, "has_tracking_code_on_pickup":false, "has_pickup":false, "transportation":"road", "metadata":{ "address_from":{ "_id":"61a15f9cfb38f514bd732222", "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":[] }] }, "cash_on_delivery":0, "logs":[], "tags":[], "notifications":[], "created_at":"2022-01-03T08:30:23.065Z", "updated_at":"2022-01-03T08:30:23.081Z" } } ``` # Label Print Format This page provides an overview of the different supported label options for each courier and specifies the accepted values for the create shipment parameter \`label\_print\_format\`.
CourierAccepted Values
Courier Center"a4_3_vouchers_per_page", "a4_preprinted_3_vouchers_per_page", "100x205_1_voucher_per_page", "100x205_preprinted_1_voucher_per_page", "100x170_1_voucher_per_page", "100x170_preprinted_1_voucher_per_page", "100x150_1_voucher_per_page", "100x150_preprinted_1_voucher_per_page"
# Incoming Orders Every time that one of your customers creates a new order in your e-commerce store or marketplace, shiplemon allows you to relate your orders with your shipments and manage your workflows. ## How the orders management works With the Orders API endpoint, you will be able to push your orders in the Shiplemon backend and additionally be able to manage them through the Shiplemon dashboard in order to: * Create a shipment for a given order * Mark an order as completed ![List of orders ("Παραγγελίες") ](/files/1iNKljpgrEEKbhq1XUJS) ## # Create Incoming Order Creating an incoming order ## Create Incoming order `POST` `https://api-sandbox.shiplemon.com/v1/incoming-orders/generic` Adds an incoming order in our system #### Request Body | Name | Type | Description | | ------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | store\_id | string |

The unique store url to avoid overwrites when orders from multiple stores have the same id. For link compatibility, also add the url protocol.
Eg. value:

| | shipment\_id | string | The id of the related shipment from [Create Shipment](/endpoints/shipments/create-shipment#create-shipment) | | status | string |

The status of the order:
One of: processing, completed

| | items\* | array |

{

id: number;

name: string;
quantity: string;

price: number;

sku?: string;

width: string;

length: string;

height: string;

weight: string;

image\_url: string;

}

| | shipping\* | object |

{

"first\_name": "First Name",

"last\_name": "Last Name",

"company": "Company",

"address\_1": "Address 1",

"address\_2": "2nd floor",

"city": "city",

"state": "state",

"postcode": "postcode",

"country": "GR",

"phone": "phone",

"email": "",

"notes: "Beware of the dog"
}


company, address\_2, and state are optional and can accept null

Country is a 2 letter ISO code

Phone is either local phone or for non GR destination prefix with country code:

| | total\* | number | The total amount of the order | | currency\* | string |

Accepts the code of the currency based on the iso 4217

Check more here:

| | shipping\_total | number |

The shipping amount of the order

Default to 0

| | billing\* | object |

{

"first\_name": "First Name",

"last\_name": "Last Name",

"company": "Company",

"address\_1": "Address 1",

"address\_2": "2nd floor",

"city": "city",

"state": "state",

"postcode": "postcode",

"country": "GR",

"phone": "phone",

"email": ""
}


company, address\_2, and state are optional and can accept null

Country is a 2 letter ISO code

Phone is either local phone or for non GR destination prefix with country code:

| | id | string | The order id (could be a string or number) | | payment\_method | string | [#payment-methods](#payment-methods "mention") | | payment\_status | string | [#payment-statuses](#payment-statuses "mention") | | created\_at | Date | eg. 2022-02-20T18:14:00.000Z | | discount\_total | number |

The discount amount of the order.
Default to 0

| {% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% endtabs %} ## Example Request {% tabs %} {% tab title="cURL" %} ```erlang curl --location --request POST 'http://api-sandbox.shiplemon.com/v1/incoming-orders/generic' \ --header 'x-api-key: {{API_KEY}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "id": 1, "store_id": "https://test-store.gr", "shipment_id": null, "currency": "eur", "shipping_total": 3, "total": 22, "billing": { "first_name": "first_name", "last_name": "last_name", "company": "company", "address_1": "address_1", "address_2": "address_2", "city": "city", "state": null, "postcode": "12345", "country": "GR", "phone": "+306900000000", "email": "email@domain.com" }, "shipping": { "first_name": "first_name", "last_name": "last_name", "company": "company", "address_1": "address_1", "address_2": "address_2", "city": "Athens", "state": "Attica", "postcode": "12345", "country": "GR", "phone": "+306900000000", "email": "email@domain.com" }, "payment_method": "cash_on_delivery", "payment_status": "pending", "created_at": "2022-02-20T18:14:00.000Z", "items": [ { "id": "product_id", "name": "name", "quantity": 2, "price": 11, "width": 0, "length": 0, "height": 0, "weight": 0, "image_url": null } ] }' ``` {% endtab %} {% endtabs %} ### Payment methods Inside an order `payment_method` listed above should be one of the following fields: * cash\_on\_delivery * bank\_transfer * paypal * card * free * unknown ### Payment Statuses Inside an order `payment_status` listed above should be one of the following fields: * pending * paid ## Example response ``` { "status": "ok", "data": { "id": "820b648b-2d06-4786-8b13-73a6dc8b4aec", "state": "new", "store_id": "https://test-store.gr", "source_id": "1", "shipment_id": null, "total": 22, "currency": "eur", "payment_method": "cash_on_delivery", "payment_status": "pending", "billing_address": { "company": "string", "first_name": "string", "last_name": "string", "address_1": "string", "address_2": "string", "country": "string", "state": "string", "postcode": "string", "city": "string", "phone": "string", "email": "string" }, "shipping_address": { "company": "string", "first_name": "string", "last_name": "string", "address_1": "string", "address_2": "string", "country": "string", "state": "string", "postcode": "string", "city": "string", "phone": "string", "email": "string", "notes": null }, "shipping_option": { "driver": null, "service": null }, "ecommerce_token": null, "ecommerce_id": "1", "ecartapi_id": null, "has_shipment_draft": false, "items": [ { "id": "product_id", "name": "name", "quantity": 2, "price": 11, "width": 0, "height": 0, "length": 0, "weight": 0, "image_url": null } ], "completed": false, "deleted_at": null, "created_at": "2022-02-20T18:14:00.000Z", "updated_at": "2022-10-10T16:02:43.825Z" } } ``` # Get incoming order ## Get an incoming order object using it's unique identifier key `GET` `https://api-sandbox.shiplemon.com/v1/incoming-orders/:incomingOrderId` #### Path Parameters | Name | Type | Description | | ------------------------------------------------- | ------ | ----------- | | incomingOrderId\* | String | | {% tabs %} {% tab title="200: OK " %} ```javascript { // Response } ``` {% endtab %} {% tab title="404: Not Found " %} ```javascript { // Response } ``` {% endtab %} {% endtabs %} # Set incoming order state Each order has a state. There are several state that categorise an order based on the state of it (New, Processing, Completed, Cancelled) ## Incoming order states An incoming order will always have one of the following state that define the order: * New (There is a new incoming order that requires a shipping action) * Processing (Someone started creating a shipment but it is still pending) * Completed (A shipment was created for this order) * Cancelled (The order was cancelled) # Help Center For more questions about the restricted items, and the limitations please have a look ## Item restrictions Not all the types of items can be sent. Each courier or transportation company has a separate set of rules and restrictions and can be found on their websites or part of your agreement contract.
Your contract may support items that other contracts might not, so what can be carried is subject to your specific agreement with each carrier. ## Maximum dimensions and weight For more information about the maximum dimensions and weight, the type of items we allow, international shipments, cancellation policy etc In the FAQ page we list various questions. If you have a question that you can't find there, please send as a message at **Some basic rules:** Max dimension: 175 cm (applies both the width, height, length) Max weight: 35 kg per item and in total not more than 70kg for a single shipment ##