ShipGlobal

Labels API v1 – Client Documentation

Base URL: https://labels.shipglobal.in/api/v1/

This API lets you authenticate and create shipment labels. Order payloads are forwarded to our last‑mile provider as‑is (no address normalization by ShipGlobal).

1) Authentication

Authenticate once, then include the returned bearer token with each request.

POST `/customers.php` – Login

Headers

Content-Type: application/json

Body

{
  "email": "client@example.com",
  "password": "secret123"
}

Response (200 OK)

{
  "token": "64-hex-chars...",
  "expires_at": "2025-08-21 07:00:00",
  "customer": { "id": 1, "name": "Your Name", "email": "client@example.com" }
}

Tokens currently expire ~24h after issuance.

Use the token by adding the header Authorization: Bearer <token> to subsequent requests.

2) Create Label

POST `/addOrder.php`

Creates an order and attempts to generate a label with our last‑mile provider. The request body must follow the structure below. Fields not listed here are ignored but stored.

Headers

Authorization: Bearer <token>
Content-Type: application/json

Required fields

Group	Field	Type / Notes
General	`invoice_no`	string
General	`invoice_date`	string (YYYY-MM-DD)
General	`order_reference`	string (unique per order recommended)
Parcel	`package_weight`	number (kg)
Parcel	`package_length`	number (cm)
Parcel	`package_breadth`	number (cm)
Parcel	`package_height`	number (cm)
Currency	`currency_code`	string (ISO 4217, e.g., EUR)
Flags	`csb5_status`	integer
Seller	`seller_nickname`, `seller_firstname`, `seller_lastname`, `seller_mobile`, `seller_email`, `seller_address`, `seller_city`, `seller_postcode`, `seller_country_code`, `seller_state`	strings; `seller_email` must be valid
Recipient	`customer_shipping_firstname`, `customer_shipping_lastname`, `customer_shipping_mobile`, `customer_shipping_email`, `customer_shipping_address`, `customer_shipping_city`, `customer_shipping_postcode`, `customer_shipping_country_code`, `customer_shipping_state`	strings; `customer_shipping_email` must be valid
Items	`vendor_order_items`	array of item objects (min 1)

Optional fields such as seller_company, seller_tax_id_type, seller_tax_id, ioss_number, etc., are accepted and stored.

Item object (required keys)

Field	Type / Notes
`vendor_order_item_name`	string
`vendor_order_item_quantity`	integer
`vendor_order_item_unit_price`	number
`vendor_order_item_hsn`	string
`vendor_order_item_tax_rate`	number

Note: If you include tracking, it will be forwarded to the carrier as an identification/reference where applicable.

Example request (cURL)

curl --location -X POST 'https://labels.shipglobal.in/api/v1/addOrder.php' \ 
  -H 'Authorization: Bearer <token>' \ 
  -H 'Content-Type: application/json' \ 
  --data-raw '{
  "invoice_no": "INV-123456",
  "invoice_date": "2025-08-20",
  "order_reference": "ORDER-98765",
  "service": "DPD-CLASSIC",
  "package_weight": 2.5,
  "package_length": 30,
  "package_breadth": 20,
  "package_height": 15,
  "currency_code": "EUR",
  "csb5_status": 1,
  "seller_nickname": "ShipGlobalTest",
  "seller_firstname": "John",
  "seller_lastname": "Doe",
  "seller_mobile": "+491234567890",
  "seller_email": "seller@example.com",
  "seller_address": "Fasanenweg 5",
  "seller_city": "Kelsterbach",
  "seller_postcode": "65451",
  "seller_country_code": "DE",
  "seller_state": "Hessen",
  "customer_shipping_firstname": "Alice",
  "customer_shipping_lastname": "Müller",
  "customer_shipping_mobile": "+491112223334",
  "customer_shipping_email": "alice.mueller@example.com",
  "customer_shipping_address": "Berliner Str. 10",
  "customer_shipping_city": "Berlin",
  "customer_shipping_postcode": "10115",
  "customer_shipping_country_code": "DE",
  "customer_shipping_state": "Berlin",
  "vendor_order_items": [
    { "vendor_order_item_name": "Bluetooth Headphones", "vendor_order_item_sku": "SKU-HEAD-123", "vendor_order_item_quantity": 1, "vendor_order_item_unit_price": 59.99, "vendor_order_item_hsn": "85183000", "vendor_order_item_tax_rate": 19 }
  ],
  "tracking": "TESTTRACK123456"
}'

Successful response

{
  "order_id": 12345,
  "dpd": {
    "success": true,
    "label": "generated",
    "waybill_number": "DPD-XXXXXX",
    "file_path": null,
    "error": "",
    "remark": "",
    "raw_response": {
      "pdf_base64": "JVBERi0xLjcKJcTl8uXrp...",
      "tracking_url": "https://tracking.dpd.de/rest/plc/en_US/DPD-XXXXXX"
    }
  }
}

3) Errors

Status	When	Body (example)
400	Malformed / non-JSON body	`{"error":"Invalid JSON"}`
401	Missing/invalid token	`{"error":"Unauthorized"}`
405	Wrong HTTP method	`{"error":"Method Not Allowed"}`
422	Validation errors	`{"error":"Validation failed","details":["Missing/empty field: ..."]}`
500	Unexpected server error	`{"error":"Internal error"}`

4) Behavior Notes

Pass-through: Address and order fields are forwarded to the carrier as provided; ShipGlobal does not modify them.
PDF label: When available, the carrier PDF label is returned as Base64 in dpd.raw_response.pdf_base64. Your system can decode and save it.
Idempotency: Not enforced. Use a unique order_reference and avoid resubmitting the same order.
Time zones: Timestamps are in server local time unless stated otherwise.

5) Support

For credentials, sandbox access, or questions, contact your ShipGlobal representative.