B2C Shipment Lifecycle

This guide walks through the full B2C (Business to Consumer) shipment lifecycle using the Bigship SDK v4.0.0+.

Imports

import {
  BigshipClient,
  isSuccessResponse,
  isFailedResponse,
} from '@agamya/bigship-sdk';

1. Check Wallet Balance

   Verify your wallet has sufficient funds before creating shipments.

   const profile = await client.getProfile();
   if (isSuccessResponse(profile)) {
     console.log('Balance:', profile.data?.userWallet?.Balance);
   }

2. Calculate Shipping Rates

   Estimate shipping costs before creating an order.

   const rates = await client.calculateRate({
     segment_type: 'domestic_b2c',
     sourcePincode: '110001',
     destPincode: '400001',
     invoiceValue: 2500,
     paymentModeId: 1, // 1: Prepaid, 2: COD, 3: ToPay
     riskTypeId: 2,    // 1: Third Party Insurance, 2: Owner Risk, 3: Carrier Risk
     boxes: [{
       box_length: 20,
       box_width: 15,
       box_height: 10,
       box_dead_weight: 0.5,
       no_of_box: 1,
     }],
   });
   
   if (isSuccessResponse(rates)) {
     const cheapest = rates.data.sort((a, b) => a.totalCharge - b.totalCharge)[0];
     console.log(`Best rate: ${cheapest.courierName} — ₹${cheapest.totalCharge}`);
   }

3. Create Order (Draft)

   Create a B2C order in draft mode.

   const order = await client.createOrder({
     segment_type: 'domestic_b2c',
     MasterOrderPickUpLocation: 123456,  // Your warehouse ID
     MasterOrderReturnLocation: 123456,  // Return warehouse ID
     MasterOrderDate: new Date().toISOString().replace('T', ' ').substring(0, 19),
     MasterOrderPaymentMode: 1,           // 1: Prepaid, 2: COD, 3: ToPay
     OrderInvoiceNo: `INV-${Date.now()}`, // Must be unique
     MasterOrderInvoiceAmount: 2500,
     MasterOrderShippingName: 'Rahul Sharma',
     MasterOrderShippingMobileNo: '9876543210',
     MasterOrderShippingEmail: 'rahul@example.com',
     MasterOrderShippingAddress: '42 MG Road Koramangala',
     MasterOrderShippingZipCode: '560034',
     MasterOrderShippingCity: 'BANGALORE',
     MasterOrderShippingState: 'KARNATAKA',
     MasterOrderShippingCountry: 'India',
     totalNumOfBoxes: 1,
     boxes: [{
       weight_unit: 'kg',
       dimension_unit: 'cm',
       noOfBoxes: 1,
       dimensions: [{
         length: 20,
         breadth: 15,
         height: 10,
         weight: 0.5,
       }],
       products: [{
         productName: 'Wireless Earbuds',
         hsn: '85182900', // Optional HSN code
         qty: '1',
         amount: '2500',
         totalAmount: 2500,
         collectableAmount: 0,
         categoryId: '4', // Electronics
       }],
     }],
   });
   
   if (isFailedResponse(order)) {
     console.error('Failed:', order.message);
     process.exit(1);
   }
   
   const orderId = order.data!.CustomGlobalOrderId;
   console.log('Draft order created:', orderId);
   // → "311276742"

4. Get Serviceable Couriers

   Retrieve available couriers and rates for the draft order.

   const couriers = await client.getServiceableCouriers(orderId);
   if (isSuccessResponse(couriers)) {
     for (const rate of couriers.data.calculatedRates) {
       console.log(`Courier: ${rate.courierName} — ₹${rate.total} (${rate.tat} days)`);
     }
   }

5. Place Order (Manifest)

   Place the order with a selected courier.

   const courierId = couriers.data!.calculatedRates[0].courierId;
   const placeResult = await client.placeOrder({
     MasterCustomOrderId: orderId,
     courierId: typeof courierId === 'string' ? parseInt(courierId, 10) : courierId,
     riskTypeId: '2', // Owner Risk
   });
   
   if (isSuccessResponse(placeResult) && placeResult.data) {
     console.log('AWB:', placeResult.data.awb_assigned);
   }

6. Track Shipment

   Track the order using CustomGlobalOrderId.

   const tracking = await client.trackOrder(orderId);
   if (isSuccessResponse(tracking)) {
     console.log('Status:', tracking.data.order_status);
     console.log('Tracking #: ', tracking.data.tracking_number);
     console.log('Courier:', tracking.data.courier_name);
   }

7. Get Order Details

   Retrieve complete order information.

   const details = await client.getOrderDetail(orderId);
   if (isSuccessResponse(details)) {
     const orderDetails = details.data.getOrderDetails;
     console.log('Status:', orderDetails.status);
     console.log('AWB:', orderDetails.AwbNumber);
     console.log('Payment:', orderDetails.PaymentMode);
   }

8. Download Documents

   Download shipping labels, invoices, or manifests.

   const label = await client.downloadDocument(orderId, 'label');
   if (isSuccessResponse(label) && label.data) {
     console.log('Label URL:', label.data.AttachmentData);
     console.log('File type:', label.data.File_extention);
   }

9. Cancel if Needed

   Cancel an order (only before rider is assigned).

   const cancel = await client.cancelOrder(orderId);
   console.log('Cancelled:', cancel.status);

Workflow Builder

For a cleaner API, use the workflow builder:

const result = await new ShipmentWorkflow(client)
  .create({
    segment_type: 'domestic_b2c',
    MasterOrderPickUpLocation: 123456,
    MasterOrderReturnLocation: 123456,
    MasterOrderDate: new Date().toISOString().replace('T', ' ').substring(0, 19),
    MasterOrderPaymentMode: 1,
    OrderInvoiceNo: `INV-${Date.now()}`,
    MasterOrderInvoiceAmount: 2500,
    MasterOrderShippingName: 'Rahul Sharma',
    MasterOrderShippingMobileNo: '9876543210',
    MasterOrderShippingAddress: '42 MG Road',
    MasterOrderShippingZipCode: '560034',
    MasterOrderShippingCity: 'BANGALORE',
    MasterOrderShippingState: 'KARNATAKA',
    MasterOrderShippingCountry: 'India',
    totalNumOfBoxes: 1,
    boxes: [{
      weight_unit: 'kg',
      dimension_unit: 'cm',
      noOfBoxes: 1,
      dimensions: [{ length: 20, breadth: 15, height: 10, weight: 0.5 }],
      products: [{
        productName: 'Wireless Earbuds',
        qty: '1',
        amount: '2500',
        totalAmount: 2500,
        collectableAmount: 0,
        categoryId: '4',
      }],
    }],
  })
  .withServiceableCourier(0) // Auto-select first courier
  .place()
  .finalize();

console.log('Order ID:', result.orderId);