GIGALOGISTICS

Create a Shipping Label

GIGALOGISTICS is a REST API that allows you to manage almost every facet possible for shipping. This tutorial will show you how to create a label.

Before you begin:

  • You'll need a pair of AK/SK which will work for this tutorial.
  • You'll need a tool to make an API call, like curl or Postman.

Creating a shipping label requires the following steps:

  1. Prepare Your Request
  2. Send the Request
  3. Download the Label

In the example below, you'll request a label using the GLS account that's included with your GIGALOGISTICS account. The general steps are the same. regardless of which carrier you use.

Step 1: Prepare Your Request

API Endpoint

To create a label, you'll need to send an HTTP POST request to https://apis.gigacloudlogistics.com/cloud-ship-service/v1/shipment. From now on we'll refer to this as the /cloud-ship-service/v1/shipment API endpoint to keep things short.

Headers

There are two HTTP headers that you need to set in your request:

HTTP Header Desription
Content-Type The Content-Type header specifies the media type of your API request. GIGALOGISTICS requires all requests to be in JSON format,so this header should always be set to application/json
Authorization Use your AK/SK to obtain authorization token for the request,refer to API Authorization documentation.
transactionId A unique identifier to your transaction.This element is also returned in the reply and helps you match the request to the reply.

Note: transactionId is restricted from repeating for 24 hours.

Request Body

The body of your HTTP request is where you'll specify all the information about the shipping label that you want to create,such as the "from" and "to" addresses, the package weight and dimensions, etc.

For this tutorial, we'll create a label with the following criteria:

Field Value
Shipper
Carlo plus

Große Ulrichstraße 17

Halle,Saxony-Anhalt

66816,DE
Recipient
Peter

Friesenweg 33

Leverkusen, Saxony-Anhalt

94072,DE
Item Weight 15 KG
Item Dimension 12 x 24 x 6 IN

As we mentioned above, GIGALOGISTICS requires all requests to be in JSON format. Here's what our label request body will look like. Notice that it contains all of the information listed above:

{
  "carrierId": "GCL-*********",
  "serviceType": "GLS_STANDARD",
  "shipper": {
    "address": {
      "countryCode": "DE",
      "stateOrProvinceCode": "Saxony-Anhalt",
      "city": "Halle",
      "zipCode": "66816",
      "streetLine1": "Große Ulrichstraße 17"
    },
    "contact": {
      "personName": "Carlo plus"
    }
  },
  "recipient": {
    "address": {
      "zipCode": "94072",
      "streetLine1": "Friesenweg 33",
      "city": "Leverkusen",
      "stateOrProvinceCode": "Saxony-Anhalt",
      "countryCode": "DE"
    },
    "contact": {
      "personName": "Peter"
    }
  },
  "itemLines": [
    {
      "itemTransactionId": "ITEM91f55857-fe8e-4308-bf16-be5d6a9d4e43",
      "itemCode": "this is itemCode",
      "weight": {
        "units": "KG",
        "value": 15
      },
      "dimensions": {
        "units": "IN",
        "length": 12,
        "width": 24,
        "height": 6
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

Step 2: Sending the Request

Now we'll take everything we talked about in Step 1 and put it all together using curl. Notice the example below uses everything we talked about in Step 1:

  • Makes a POST call to https://apis.gigacloudlogistics.com/cloud-ship-service/v1/shipment
  • Sets the content type header to application/json
  • Sets Authorization header to the access token
  • Sets transactionId header to a unique identifier

Paste the following curl example into your Terminal :

curl -iX POST https://apis.gigacloudlogistics.com/cloud-ship-service/v1/shipment \
-H 'Content-Type: application/json' \
-H 'Authorization: __YOUR_ACCESS_TOKEN__' \
-H 'transactionId: __UUID__' \
-d '{
  "carrierId": "GCL-*********",
  "serviceType": "GLS_STANDARD",
  "shipper": {
    "address": {
      "countryCode": "DE",
      "stateOrProvinceCode": "Saxony-Anhalt",
      "city": "Halle",
      "zipCode": "66816",
      "streetLine1": "Große Ulrichstraße 17"
    },
    "contact": {
      "personName": "Carlo plus"
    }
  },
  "recipient": {
    "address": {
      "zipCode": "94072",
      "streetLine1": "Friesenweg 33",
      "city": "Leverkusen",
      "stateOrProvinceCode": "Saxony-Anhalt",
      "countryCode": "DE"
    },
    "contact": {
      "personName": "Peter"
    }
  },
  "itemLines": [
    {
      "itemTransactionId": "ITEM91f55857-fe8e-4308-bf16-be5d6a9d4e43",
      "itemCode": "this is itemCode",
      "weight": {
        "units": "KG",
        "value": 15
      },
      "dimensions": {
        "units": "IN",
        "length": 12,
        "width": 24,
        "height": 6
      }
    }
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

If your request was successful, you'll receive an HTTP 200 response that looks similar to this:

{
    "success": true,
    "data": {
        "transactionId": "transactionId",
        "carrierId": "GCL-*********",
        "carrierCode": "GLS",
        "serviceType": "GLS_STANDARD",
        "paymentOption": {
            "paymentType": null,
            "paymentTerms": null,
            "payor": null
        },
        "signatureOption": {
            "signatureOptionType": null
        },
        "labelSpecification": {
            "imageType": null,
            "labelStockType": null
        },
        "taxIndentifiers": null,
        "transactionShipments": [
            {
                "itemTransactionId": "ITEM91f55857-fe8e-4308-bf16-be5d6a9d4e43",
                "gigaTrackingNumber": "GCL1933469400013",
                "trackingNumber": "251946492667",
                "masterTrackingNumber": null,
                "declaredInfo": null,
                "specialService": null,
                "customerReference": null,
                "packageDocuments": [
                    {
                        "fileBase64": null,
                        "imageType": "pdf",
                        "fileUrl": "https://oss.com/temp/GLS/20221216/7240686711761-251946492667.pdf",
                        "contentType": "LABEL"
                    }
                ]
            }
        ]
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

Notice that this response includes the following:

  • TransactionId
  • ItemTransactionId
  • PackageDocuments

Step 3: Download the Label

At the end of Step 2, you received an HTTP response that included the label details. The label is returned as a URL or base64. You can paste the fileUrl into your browser to download the label, or get the label file by parsing the fileBase64.

{"packageDocuments": [
    {
        "fileBase64": null,
        "imageType": "pdf",
        "fileUrl": "https://oss.com/temp/GLS/20221216/7240686711761-25194992667.pdf",
        "contentType": "LABEL"
    }
]}
1
2
3
4
5
6
7
8

Advanced Options

Review the options below for ways to improve your label flow.

Add Message to the Labels

Show your customers an additional level of care and detail by adding a personal or customized message. Custom Label Messages article.

← Customer Reference →