Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usedroptrail.com/llms.txt

Use this file to discover all available pages before exploring further.

​
E-commerce Integration Guide

This guide demonstrates how to integrate UseDropTrail’s delivery system with your e-commerce platform. You’ll learn how to automatically create delivery requests when orders are placed and track deliveries in real-time.

​
Overview

When integrating UseDropTrail with your e-commerce platform, you’ll typically want to:
  1. Create delivery requests automatically when orders are placed
  2. Track delivery status and update order status accordingly
  3. Provide real-time tracking information to customers
  4. Handle delivery notifications

​
Prerequisites

  • UseDropTrail API key
  • Organization account
  • E-commerce platform with webhook support

​
Implementation Steps

​
1. Initialize the SDK

const UseDropTrail = require('usedroptrail');
const usedroptrail = new UseDropTrail({
  apiKey: 'YOUR_API_KEY'
});

​
2. Create a Delivery Request

const deliveryRequest = await usedroptrail.deliveryRequests.create({
  orderId: '123456',
  pickupAddress: '123 Main St, Anytown, USA',
  deliveryAddress: '456 Elm St, Anytown, USA',
  pickupTime: '2024-01-01T10:00:00Z',
  deliveryTime: '2024-01-01T12:00:00Z'
});

​
3. Track Delivery Status

const deliveryStatus = await usedroptrail.deliveryRequests.get(deliveryRequest.id);
console.log(deliveryStatus);

​
4. Handle Delivery Notifications

const deliveryNotification = await usedroptrail.deliveryRequests.update(deliveryRequest.id, {
  status: 'delivered'
});
console.log(deliveryNotification);

​
4. Handle Webhooks

app.post('/webhooks/usedroptrail', async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'delivery.accepted':
      await handleDeliveryAccepted(event.data);
      break;
    case 'delivery.in_transit':
      await handleDeliveryInTransit(event.data);
      break;
    case 'delivery.completed':
      await handleDeliveryCompleted(event.data);
      break;
    case 'delivery.cancelled':
      await handleDeliveryCancelled(event.data);
      break;
  }

  res.status(200).send('Webhook received');
});
This example demonstrates how to create a delivery request, track its status, and handle delivery notifications. You can customize this implementation based on your specific requirements and e-commerce platform.

​
Best Practices

  1. Error Handling
    • Always implement proper error handling
    • Have fallback delivery options
    • Store delivery request IDs for reference
  2. Customer Communication
    • Send tracking information immediately after delivery request creation
    • Provide real-time status updates
    • Set up automated notifications for important status changes
  3. Order Management
    • Keep order and delivery status synchronized
    • Store all tracking information
    • Implement retry logic for failed delivery requests
  4. Testing
    • Use sandbox environment for testing
    • Test with various order scenarios
    • Simulate different delivery statuses

​
Common Issues and Solutions

​
Issue: Delivery Request Creation Fails

try {
  const deliveryRequest = await createDeliveryFromOrder(order);
} catch (error) {
  if (error.code === 'INVALID_ADDRESS') {
    // Validate and clean up address
    const correctedAddress = await validateAddress(order.shipping_address);
    // Retry with corrected address
    return createDeliveryFromOrder({ ...order, shipping_address: correctedAddress });
  }
  // Handle other errors
}

​
Issue: Tracking Updates Not Received

function setupDeliveryTrackingWithRetry(deliveryRequestId, maxRetries = 3) {
  let retries = 0;
  
  function connect() {
    const ws = droptrail.tracking.connect(deliveryRequestId);
    
    ws.on('error', (error) => {
      console.error('Tracking connection error:', error);
      if (retries < maxRetries) {
        retries++;
        setTimeout(connect, 5000 * retries);
      }
    });
    
    return ws;
  }
  
  return connect();
}

​
Conclusion

By following these steps, you can integrate UseDropTrail’s delivery system with your e-commerce platform. This integration allows you to automatically create delivery requests, track delivery status, and provide real-time tracking information to customers. For more detailed information, you can refer to the API Reference.