ShiftDocs

Shipments

Book a forward shipment

POST{host}/api/v1/open/forward

Key points to note

  1. It is mandatory to fetch cost estimates before booking any forward shipments.
  2. When cost estimates API is requested, in response you get all possible courier options along with key parameters like shipment price, expected delivery date, etc.
  3. Pick a courier partner of your choice, then note down the carrierCode and requestId from the response for that carrier.
  4. When booking a shipment, use the same carrierCode and requestId to book shipment successfully with your desired courier partner.

Request Example

curl --location '<HOST>/api/v1/open/forward' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic xxxxxxxxxxxxxxxx' \
  --data '{
    "carrier_code": "DE",
    "request_id": "x1/pT7jVcxsEwmPEZZo7kt...",
    "order_number": "TEST00001",
    "seller_details": {
      "registered_name": "TEST LLP",
      "registered_address": "Test Seller Address",
      "state": "Test State",
      "gstin": "36AANNN1111E1E1"
    },
    "pickup_location": {
      "name": "Pickup Addr name here",
      "phone": "9900990099",
      "email": "pickupemail@gmail.com",
      "addressUid": 12345
    },
    "delivery_location": {
      "name": "Customer Name",
      "phone": "9988998899",
      "email": "customeremail@gmail.com",
      "address": {
        "address_line_1": "Customer Address Line 1",
        "address_line_2": "Customer Address Line 2",
        "landmark": "--",
        "city": "Customer City",
        "state": "Customer State",
        "country": "India",
        "pincode": "200033"
      }
    },
    "shipment": {
      "shipment_id": "001",
      "reshipped": true,
      "delivery_instructions": "",
      "weight_grams": 500,
      "product_details": [
        {
          "quantity": "1",
          "description": "L – Test Product Name",
          "hsn_code/sku_code": "ABCD",
          "category_of_goods": "Category",
          "commodity_value": "1000.00",
          "weight_grams": 500,
          "height_cm": 10,
          "length_cm": 10,
          "breadth_cm": 10
        }
      ],
      "payment_details": {
        "amount": 1000,
        "payment_mode": "PPD"
      },
      "dimensions": {
        "length_cm": 10,
        "breadth_cm": 10,
        "height_cm": 10
      }
    },
    "label_preferences": {
      "use_label_printer_dimension": true,
      "use_v2_template": true,
      "show_cod_value": false,
      "show_ppd_value": true,
      "show_sender_mobile": true,
      "show_sender_address": true,
      "hide_company_logo": false,
      "hide_product_name": false,
      "hide_product_sku": false,
      "hide_products": false,
      "hide_receiver_mobile": false,
      "show_support_contact": true,
      "hide_powered_by": false,
      "hide_gst_number": false,
      "use_state_jurisdiction_footer": true,
      "custom_text": "",
      "merge_labels": false,
      "label_size": "4inx6in",
      "labels_per_page": 2
    }
  }'

Payload Parameters Guide

ParameterDescription
carrier_code, request_idObtained from cost estimates API response
order_numberNeeds to be unique for each shipment
seller_detailsProvide your GST details here. Use empty if non-GST client
pickup_locationProvide pickup address and contact details. Use either address or addressUid
delivery_locationProvide drop off (customer) address and contact details. Use either address or addressUid
shipment_idOptional - unique identifier for the shipment. Not mandatory in shipment payload.
payment_modeValid values: PPD (Prepaid) or COD (Cash on Delivery)
reshippedOptional - send as true if order is being reshipped after cancellation
label_preferencesOptional – Configure and customize the shipping label generated for the shipment. Supported label sizes: 4 × 6 A4 3 × 5 A5

Response Example

Success Response

{
  "data": {
    "carrierCode": "DE",
    "trackingNumber": "25338210179723",
    "shippingLabelUrl": "https://carrier-v2-dev-new.s3.ap-south1.amazonaws.com/.../ShippingLabel-115924.pdf",
    "invoiceUrl": "https://carrier-v2-dev-new.s3.ap-south1.amazonaws.com/.../Invoice-115924-1708663858.pdf",
    "manifestUrl": null,
    "success": true,
    "responseMessage": null
  },
  "errorMessage": null
}

The trackingNumber is the AWB number for the booked forward shipment. This can be used to track the shipment status.

Stuck on an integration?

Your account manager can put you in touch with our tech team.

Talk to us