Upload an order
Sendcloud’s basic order API offers an intuitive and flexible way of getting your orders ready for delivery. Are you willing to put your shipping processes on autopilot? Learn how to create your first order with Sendcloud’s order API.
This guide will cover the basics of uploading a new order via the API. Once the order is uploaded, you can update the necessary information and prepare your order for shipping.
Before you begin
- Make sure you’ve completed setting up an account.
- Get your API keys to authenticate with our API.
- Get access to a tool that allows you to make API calls. Learn the examples of Postman and Insomnia.
API endpoint
To create an order, send a POST request to the Create an order endpoint: https://panel.sendcloud.sc/api/v3/orders/.
Headers
Headers provide context and additional metadata to the server to help it process requests.
Authorization header
Every time you make an API call, you need to authenticate your connection with Sendcloud by including your API keys through an HTTP header.
Step 1: Prepare your request
The body of your request contains the required order information. Refer to the example of creating an order in your Sendcloud account below.
Request example
1[
2 {
3 "order_id": "555413",
4 "order_number": "OXSDFGHTD-12",
5 "order_details": {
6 "integration": {
7 "id": 7
8 },
9 "status": {
10 "code": "fulfilled",
11 "message": "Fulfilled"
12 },
13 "order_created_at": "2018-02-27T10:00:00.555Z",
14 "order_updated_at": "2018-02-28T11:05:15.634Z",
15 "order_items": [
16 {
17 "name": "Orange",
18 "quantity": 1,
19 "total_price": {
20 "value": 3.5,
21 "currency": "EUR"
22 }
23 }
24 ]
25 },
26 "payment_details": {
27 "total_price": {
28 "value": 3.5,
29 "currency": "EUR"
30 },
31 "status": {
32 "code": "paid",
33 "message": "Paid"
34 }
35 },
36 "shipping_address": {
37 "name": "John Doe",
38 "address_line_1": "Stadhuisplein",
39 "house_number": "15",
40 "postal_code": "5341AB",
41 "city": "Oss",
42 "country_code": "NL",
43 "phone_number": "0612345678"
44 }
45 }
46]
Order fields
There are other additional fields, that you can specify when creating an order, for example customs_details for international orders.
Step 2: Send your request
Use the example to make a POST request to http://panel.sendcloud.sc/api/v3/orders/.
1curl --location -g --request POST 'https://panel.sendcloud.sc/api/v3/orders/' \
2--header 'Authorization: Basic <credentials>' \
3--data-raw '
4[
5 {
6 "order_id": "555413",
7 "order_number": "OXSDFGHTD-12",
8 "order_details": {
9 "integration": {
10 "id": 7
11 },
12 "status": {
13 "code": "fulfilled",
14 "message": "Fulfilled"
15 },
16 "order_created_at": "2018-02-27T10:00:00.555Z",
17 "order_updated_at": "2018-02-28T11:05:15.634Z",
18 "order_items": [
19 {
20 "name": "Orange",
21 "quantity": 1,
22 "total_price": {
23 "value": 3.5,
24 "currency": "EUR"
25 }
26 }
27 ]
28 },
29 "payment_details": {
30 "total_price": {
31 "value": 3.5,
32 "currency": "EUR"
33 },
34 "status": {
35 "code": "paid",
36 "message": "Paid"
37 }
38 },
39 "shipping_address": {
40 "name": "John Doe",
41 "address_line_1": "Stadhuisplein",
42 "house_number": "15",
43 "postal_code": "5341AB",
44 "city": "Oss",
45 "country_code": "NL",
46 "phone_number": "0612345678"
47 }
48 }
49]'
If the validation is successful, you will receive the HTTP 201 status code** and the following response.
Response example
1{
2 "data": [
3 {
4 "id": "664",
5 "order_id": "555413",
6 "order_number": "OXSDFGHTD-12"
7 }
8 ]
9}
Note that the response contains minimum identifiable information to locate it in Sendcloud’s system.
The newly created order has the "id": 664", which is the unique identifier for updating an order via the API.
Edit the uploaded order
To update an existing order, use POST and PATCH requests.
You can also use the POST request to keep your orders up to date because it uses order_id in combination with integration.id to distinguish between new and existing orders and avoid duplicating.
You can take advantage of this functionality and update your orders just like you create a new order.
Request example
1[
2 {
3 "order_id": "555413",
4 "order_number": "OXSDFGHTD-12",
5 "order_details": {
6 "integration": {
7 "id": 7
8 },
9 "status": {
10 "code": "fulfilled",
11 "message": "Fulfilled"
12 },
13 "order_date": "2018-02-27T10:00:00.555Z",
14 "order_items": [
15 {
16 "name": "Orange",
17 "quantity": 1,
18 "total_price": {
19 "value": 3.5,
20 "currency": "EUR"
21 }
22 }
23 ]
24 },
25 "payment_details": {
26 "total_price": {
27 "value": 3.5,
28 "currency": "EUR"
29 },
30 "status": {
31 "code": "paid",
32 "message": "Paid"
33 }
34 },
35 "shipping_address": {
36 "name": "John Doe",
37 "address_line_1": "Stadhuisplein",
38 "house_number": "10",
39 "postal_code": "5611EM",
40 "city": "Eindhoven",
41 "country_code": "NL",
42 "phone_number": "0612345678"
43 }
44 }
45]
Note that the order_id and order_number refer to the same order we created in Step 1.
Instead of creating a new order in Sendcloud, the previous order will be updated with the new shipping_address that was in the request.
Response example
1{
2 "data": [
3 {
4 "id": "664",
5 "order_id": "555413",
6 "order_number": "OXSDFGHTD-12"
7 }
8 ]
9}
In the response, the order identifier hasn’t changed, meaning all the changes were applied to the existing order.
Congrats! You just created your first order and updated its shipping_address.
Find the order
To get a list of orders containing the newly created order, make a GET request with desirable filters. The example below uses the integration filter to get all orders for a certain integration.
Request example
1curl --location -g --request GET 'https://panel.sendcloud.sc/api/v3/orders/?integration=7' \
2--header 'Authorization: Basic <credentials>'
Response example
1{
2 "data": [
3 {
4 "id": "664",
5 "order_id": "555413",
6 "order_number": "OXSDFGHTD-12",
7 "created_at": "2018-02-27T10:00:00.555Z",
8 "modified_at": "2018-02-27T10:00:00.555Z",
9 "order_details": {
10 "integration": {
11 "id": 7
12 },
13 "status": {
14 "code": "fulfilled",
15 "message": "Fulfilled"
16 },
17 "order_date": "2018-02-27T10:00:00.555Z",
18 "order_items": [
19 {
20 "name": "Orange",
21 "quantity": 1,
22 "total_price": {
23 "value": 3.5,
24 "currency": "EUR"
25 }
26 }
27 ]
28 },
29 "payment_details": {
30 "total_price": {
31 "value": 3.5,
32 "currency": "EUR"
33 },
34 "status": {
35 "code": "paid",
36 "message": "Paid"
37 }
38 },
39 "shipping_address": {
40 "name": "John Doe",
41 "address_line_1": "Stadhuisplein",
42 "house_number": "10",
43 "postal_code": "5611EM",
44 "city": "Eindhoven",
45 "country_code": "NL",
46 "phone_number": "0612345677"
47 }
48 }
49 ]
50}
What’s next?
You can explore more tutorials or dive directly into our API reference.
- Choose a shipping method and learn how to make the full list of shipping services available to you via Sendcloud.
- Create a parcel and deliver your order.
- Include Sendcloud service points in your data flow.
