Shipper Logistics API Documentation (3.0.0)

Shipper API is an exclusive way to connect with the Shipper platform. It is an HTTP-based API that applications can interact with our location, pricing, and shipment features, and many more. Users can customize their data freely with this API.

Shipper Shipping Service

Getting Started Using Shipper Postman Collection

1. Install Postman.
2. Download the Shipper Logistic API Postman Collection.
3. Import the collection into your Postman App.
4. Use your Shipper API Key to authenticate (see How to Get Shipper API Key below).
5. Update the api_key value on the Postman collection with the API key generated for you.

1. Go to the Sandbox Dashboard and register for a Sandbox account.
2. Complete your registration and verify your account.
3. Inform our sales team via email at cs@shipper.id so they can grant you access to an API key.

X-API-Key_Header

To authenticate your request to Shipper API v3 you need to provide your API Key in the HTTP request header X-API-Key.

1. After discussing commercials with our Sales team, our Legal Team will accompany you to sign the Letter of Agreement.
2. After signing the Agreement, you can start integrating with our API using your Sandbox API Key.
3. If you have not registered on our Sandbox Dashboard yet, register at https://bos.sandbox.shipper.id/register. You can find the Sandbox API Key on the API menu.
4. Shipper Team will support you during the integration process via Sales representative or Contact Center (https://faq.shipper.id/#contact-us).
5. Once integration is complete, fill in the UAT form and send it to partnership.api@shipper.id or your Sales representative for review.
6. If your UAT form passes, we schedule a UAT Session with you. If it fails, revise and resend it.
7. Before the UAT Session, settle administration/payment requirements (e.g. setup fee) with your Sales representative.
8. During the UAT Session you will simulate order creation and pickup requests for two scenarios: item value above IDR 1,000,000 and item value below IDR 1,000,000.
9. If you pass the UAT Session, an Onboarding Call is scheduled to walk through operational flow, pickup schedule/confirmation, delivery PIC, and how to use the Shipper Dashboard.
10. After the Onboarding Call you get access to the Shipper Production Dashboard, where you can obtain your Production API Key from the API menu.

What's the difference between Sandbox and Production? Sandbox is a free testing environment. Production is the live environment used once the User Acceptance Test, Onboarding Call, and Agreement have been completed with our dedicated team.

Sandbox base URL:

https://merchant-api-sandbox.shipper.id

Production base URL:

https://merchant-api.shipper.id

You'll obtain the area_id of the desired location for pricing and order creation before proceeding to the Pricing API. There are two ways to obtain the area_id of a location:

1. Search Location by Keyword
2. Search Location Complete Step (Country -> Province -> City -> Suburb -> Area)

This step is required to obtain the pricing rates and available services on Shipper. There are two ways to obtain domestic pricing rates: Get Pricing Domestic (all logistics available on that route) and Get Pricing Domestic by Rate Type (only logistics matching a specific rate type).

This is the next step required after obtaining the shipment rates. With the Order API you are able to create an order, get order details (by order id or by external id), get the shipping label/receipt, and cancel an order.

This is the last step of the integration process. It is required to make a pickup request call for a driver to collect the order; otherwise the order stays idle in an inactive state.

You can access Shipper Dashboards at the Production Dashboard and the Sandbox Dashboard. On the Dashboard you can monitor your orders and manually create orders in the respective environment. The Sandbox environment does not trigger any real shipping process.

Sandbox: bos.sandbox.shipper.id  |  Production: dashboard.shipper.id

There are two types of cancellation that might occur during delivery: Cancel Order by 3PL and Cancel Order by Merchant. In both cases the Shipper status moves to 999 (Cancelled) and you need to recreate a new order with a new Order ID and a new pickup request — the existing order id can no longer be used for a new pickup request.

To avoid cancellation, ensure the order(s) are ready for pickup before the driver arrives.

Shipper Logistic API team regularly updates the API with new features, bug fixes, and performance improvements. Subscribe to the Shipper Logistic API Notify Group for updates.

3.0.2 — 9 May 2023

• Hotfix for an instant order cancellation issue where the 3PL's driver still arrived to pick up an order after it was cancelled.
• Location service now keeps precision data. You must use the correct area_id from the Location API together with lat/lng when getting pricing and creating orders. For Get Pricing you may now remove area_id from the request entirely and rely on lat/lng.

3.0.1 — 15 March 2023

• POST /v3/order: the origin.direction and destination.direction parameters are now limited to a maximum of 100 characters (only the first 100 characters are printed on the order label).

The final weight of an order is the heavier of actual weight and volumetric weight. Every logistic and service has its own volumetric weight formula (volume divided by 4000, 5000, or 6000).

The final weight must be calculated from items that have been packed — if there are multiple items, assume they are all packed into a single package.

Dimension Calculation with Multiple Items

If you do not have a standardized package for multiple items, estimate length/width/height with:

(P x L x T) + (P x L x T) = Z
a = cube root of Z
P = L = T = a

Where P = Length, L = Width, T = Height, Z = Total Dimension. Use the resulting a value for length, width and height in the Pricing API and Create Order API.

rate_id uniquely identifies the service rate you use when creating an order. min_kg/max_kg describe the weight range accepted by the 3PL (empty response outside this range). See also the full partner list.

Shipper gets insurance prices from each logistic partner, each of which has its own insurance calculation rules. There are compulsory insurance rules: if the item price of the order exceeds a 3PL's insurance threshold, insurance is required on that order (use_insurance must be true).

Insurance Threshold

Example: if your item value is Rp 1.500.000 and you choose JNE, must_use_insurance will be true on the Get Pricing response, so use_insurance must be true on Create Order.

Compulsory Insurance Flow

• If must_use_insurance is true on Get Pricing, use_insurance must be true on Create Order, otherwise order creation fails with "This order must use insurance."
• If must_use_insurance is false, use_insurance is optional (true or false).
• Always use insurance when sending fragile goods or important documents.
• Always set use_insurance = false when using a 3PL whose insurance is automatically covered (GoSend & Grab Express).

Lalamove Vehicle Insurance Coverage

For inquiries, email support@shipper.id.

Questions — Subject: CompanyName_API_Questions. Body: company name, list of questions and reasonings.

Troubleshooting — Subject: CompanyName_API_troubleshooting. Body: company name, company BOS account phone number, Order ID or External ID, environment (Sandbox/Production), issue explanation, request/response payload, and screenshots if any.

For shipment issues, contact Control Tower on +62 8033 2160 215 or support@shipper.id.

Origin Coverage refers to the origin coverage served by the 3PLs already integrated with Shipper.

Lalamove orders follow a different flow than the usual create-order flow:

1. Get the city id via GET Cities by Province ID.
2. Get the vehicle id via GET Vehicle ID for Lalamove (GET /v3/vehicle/city/{city_id}).
3. The vehicle id response also lists the special instructions available for that vehicle in that city.
4. Get pricing using the desired vehicle_id, optionally adding special_instructions and a schedule_at date/time — this returns the actual price including any additional charges.
5. Create the order with the rate_id obtained from pricing, optionally adding courier.special_instructions and courier.schedule_at.

(Reference only — this operation is not exposed as a published endpoint.)

(Reference only — this operation is not exposed as a published endpoint.)

(Reference only — internal validation codes that may surface on order-related endpoints.)

These statuses represent the order status shown in Get Order Details as shipper_status/ shipment_status, on the Shipper Dashboard as "Shipper Status", and inside the webhook callback payload as external_status.

Shipper Webhook lets Shipper clients receive the latest order and delivery status data in real-time. To use it you need to provide a stateless, open API endpoint to receive requests from the Shipper server.

Integration steps

1. Provide one endpoint, stateless and open, to receive requests from the Shipper server.
2. Set the webhook URL on the Shipper Dashboard.
3. Simulate orders in Sandbox to receive status updates on your endpoint.

Shipper sends a POST request with Content-Type: application/json:

{
  "auth": "7984d7039821972c27dbaa9a0f9f3b29",
  "order_id": "60af69a2d48465d30e2b5b85",
  "tracking_id": "2CQJADENEAU",
  "order_tracking_id": "60af69b98f62b9082bdfebf9",
  "external_id": "SHIP-001",
  "status_date": "2021-05-27T09:43:21+00:00",
  "internal": {
    "id": 3,
    "name": "Dijemput Driver",
    "description": "Paket Anda sudah dijemput oleh Shipper Driver"
  },
  "external": {
    "id": 99,
    "name": "Dijemput Driver",
    "description": "Paket Anda sudah dijemput oleh Shipper Driver"
  },
  "internal_status": {
    "code": 1001,
    "name": "Valid",
    "description": "Valid"
  },
  "external_status": {
    "code": 1000,
    "name": "Paket sedang dipersiapkan",
    "description": "Paket sedang dipersiapkan"
  },
  "awb": "010116222971811"
}

The awb property is only sent once an AWB number is attached to the order.

auth is generated by the Shipper system as:

auth = crypto.createHash("md5").update(<api_key> + <endpoint_url> + <response_format>).digest("hex");

where response_format is the literal lowercase string json.

Parameter mapping to Get Order Details

No response is expected from your endpoint — the Shipper webhook engine does not act on the response received.

Sandbox: visit the Sandbox Dashboard → API menu → Set Webhook → input your endpoint URL → choose type JSON → Submit.

Production: visit the Production Dashboard → API menu → Set Webhook → input your endpoint URL → choose type JSON → Submit.

Simulation is only available on the Sandbox environment, and currently only for Gosend, Grab, and JNE.

1. Create an order via API (JNE, Grab, or Gosend only).
2. Request pickup for the order via API.
3. Set the webhook URL (see above).
4. Visit the Sandbox Dashboard.
5. Go to API menu → Simulasi Order.
6. Fill in the order id.
7. Click "Simulasi" on the status you want to simulate.
8. See "riwayat status" to view the status change.
9. Check your endpoint for the webhook payload received.

Location API — obtain the area_id of a location for pricing and order creation

Pricing API — obtain shipping rates and Lalamove vehicle information