Adjustment Webhooks

Adjustment webhooks notify you when shipping costs change after a shipment has been processed. These typically occur when carriers weigh or measure packages and find discrepancies from the original quoted dimensions or weight.

Understanding Adjustments

Shipping adjustments happen when the actual package characteristics differ from what was initially provided:

Weight adjustments: Package weighs more or less than declared
Dimension adjustments: Package dimensions differ from quoted size
Service adjustments: Carrier changes service level or routing
Address corrections: Carrier modifies delivery address

Adjustment Event Type

Adjustment webhooks are triggered with the event type:

shipment.invoice.created

The webhook will include the X-SSK-Webhook-Event-Type: shipment.invoice.created header.

Adjustment Webhook Structure

Adjustment webhooks follow the standard ShipSideKick webhook format but contain a ShipmentInvoice object in the result field:

{
  "result": {
    "id": "...",
    "object": "ShipmentInvoice",
    "mode": "production",
    "status": "processed",
    "user_id": "...",
    "order_id": null,
    "shipment_id": "...",
    "tracking_code": "94001...",
    "label_date": "2025-05-10T21:02:42Z",
    "quoted_amount": "4.83",
    "quoted_currency": "USD",
    "initially_paid_amount": "4.83000",
    "initially_paid_currency": "USD",
    "initially_paid_payment_log": "invoice_id...",
    "adjustment_reason": "Weight",
    "adjustment_amount": "1.60000",
    "invoice_date": "2025-05-11T21:02:42Z",
    "invoice_type": "adjustment",
    "invoice_amount": "1.60000",
    "invoice_currency": "USD",
    "invoice_payment_log": "invoice_id...",
    "total_cost": "6.43000",
    "carrier_account": "...",
    "carrier": "USPS",
    "claimed_details": {
      "from_address": {
        "zip": "15017-1590",
        "state": "PA",
        "country": "US"
      },
      "to_address": {
        "zip": "59301-3140",
        "state": "MT",
        "country": "US"
      },
      "parcel": {
        "length": null,
        "width": null,
        "height": null,
        "weight": 10.0,
        "predefined_package": null
      },
      "service": "GroundAdvantage",
      "carrier": "USPS"
    },
    "captured_details": {
      "from_address": {
        "zip": "15017-1590",
        "state": "PA",
        "country": "US"
      },
      "to_address": {
        "zip": "59301-3140",
        "state": "MT",
        "country": "US"
      },
      "parcel": {
        "length": null,
        "width": null,
        "height": null,
        "weight": 12.48,
        "predefined_package": "PARCEL"
      },
      "service": "GroundAdvantage",
      "carrier": "USPS"
    },
    "package_dispute_id": "..."
  },
  "description": "shipment.invoice.created",
  "mode": "production",
  "previous_attributes": null,
  "completed_urls": null,
  "user_id": "...",
  "status": "pending",
  "object": "Event",
  "id": "..."
}

Key Fields Explained

Invoice Information

invoice_type: Always "adjustment" for adjustment webhooks
invoice_date: When the carrier issued the adjustment
adjustment_reason: Why the adjustment occurred (e.g., "Weight", "Dimensions", "Service")
adjustment_amount: The additional amount charged (positive) or credited (negative)

Cost Breakdown

quoted_amount: Original shipping cost estimate
initially_paid_amount: Amount charged when label was created
invoice_amount: Adjustment amount (matches adjustment_amount)
total_cost: Final total cost after adjustment

Package Comparison

claimed_details: What you originally declared
captured_details: What the carrier actually measured/weighed

Common Adjustment Reasons

Weight Adjustments

The most common adjustments occur when actual package weight differs from declared weight:

{
  "adjustment_reason": "Weight",
  "claimed_details": {
    "parcel": { "weight": 10.0 }
  },
  "captured_details": {
    "parcel": { "weight": 12.48 }
  }
}

Dimension Adjustments

Packages that are larger than declared may trigger dimensional weight pricing:

{
  "adjustment_reason": "Dimensions",
  "claimed_details": {
    "parcel": {
      "length": 12,
      "width": 8,
      "height": 6,
      "weight": 5.0
    }
  },
  "captured_details": {
    "parcel": {
      "length": 15,
      "width": 10,
      "height": 8,
      "weight": 5.0
    }
  }
}

Service Adjustments

Carrier may change service level due to routing or delivery requirements:

{
  "adjustment_reason": "Service",
  "claimed_details": {
    "service": "Ground"
  },
  "captured_details": {
    "service": "Priority"
  }
}

Handling Adjustment Webhooks

Basic Processing Example

app.post('/webhook', (req, res) => {
  const event = JSON.parse(req.body);
 
  if (event.description === 'shipment.invoice.created') {
    const invoice = event.result;
 
    // Process the adjustment
    await handleShipmentAdjustment({
      shipmentId: invoice.shipment_id,
      trackingCode: invoice.tracking_code,
      adjustmentReason: invoice.adjustment_reason,
      adjustmentAmount: parseFloat(invoice.adjustment_amount),
      totalCost: parseFloat(invoice.total_cost),
      originalCost: parseFloat(invoice.initially_paid_amount)
    });
  }
 
  res.status(200).send('OK');
});
 
async function handleShipmentAdjustment(adjustment) {
  console.log(`Adjustment for ${adjustment.trackingCode}:`);
  console.log(`Reason: ${adjustment.adjustmentReason}`);
  console.log(`Additional charge: $${adjustment.adjustmentAmount}`);
  console.log(`New total: $${adjustment.totalCost}`);
 
  // Update your internal records
  await updateShipmentCost(adjustment.shipmentId, adjustment.totalCost);
 
  // Notify relevant stakeholders
  await notifyAccountingTeam(adjustment);
 
  // Log for auditing
  await logAdjustment(adjustment);
}

Dispute Process

If you believe an adjustment is incorrect, you can dispute it using the package_dispute_id provided in the webhook. Contact ShipSideKick support with:

The package_dispute_id from the webhook
Supporting documentation (photos, weight receipts, etc.)
Explanation of why you believe the adjustment is incorrect

Main Webhooks Guide for general webhook setup
API Documentation for endpoint management
Billing Documentation for understanding cost calculations

Adjustment Webhooks

On this page