Saudi commerce · Logistics · Zid

Zid shipping weight disputes: build evidence before wallet deductions

Design a reliable Zid shipping-weight workflow with packed measurements, versioned factors, AWB and wallet reconciliation, and per-shipment dispute evidence.

TOPIC HUBE-commerce Engineering
A real parcel on a digital scale, representing shipment weight evidence before carrier billing
J

Zid's logistics guidance updated on November 10, 2026 explains a cost boundary many commerce systems model too late: the carrier charges the greater of actual weight and volumetric weight, and a later measurement difference can become an additional wallet deduction. The reliable response is not a spreadsheet after the charge. It is an evidence workflow that records the final packed parcel, calculation inputs, applicable rate rule, Air Waybill and immutable photos before the order becomes Ready.

Answer first

For a Saudi merchant using Zid Logistics, calculate a provisional chargeable weight before label creation, but treat the carrier's accepted measurement and the wallet transaction as authoritative outcomes. Store an append-only measurement record for every physical parcel. When Zid creates the shipment at the Ready transition, reconcile the declared package with the shipment and transaction records. If a weight-difference charge appears, open one case per shipment with the order number or AWB, actual weight, dimensions and clear measurement evidence. Zid's current guidance says a dispute should be submitted within five days of delivery; acceptance and refund remain subject to verification.

Search intent: practical architecture for preventing, reconciling and disputing Zid additional-weight charges. Primary keyword: Zid shipping weight dispute. Related terms include actual weight, volumetric weight, chargeable weight, AWB, Zid wallet, Ready status, packaging station, rate card, evidence ledger and shipment reconciliation.

What Zid documents

The official additional-weight guide states that chargeable weight is the higher of:

  • actual weight: the packed parcel's physical weight, including products and packaging;
  • volumetric weight: length × width × height divided by the conversion factor used by the carrier.

Zid's examples use a factor of 4,000 for domestic shipments and 5,000 for international shipments. Its shipping-method documentation repeats these examples and warns that carrier factors and pricing conditions can vary. Therefore, 4,000 and 5,000 are documented defaults in the current guide—not constants to hard-code across every provider and service.

For the guide's domestic example, a 40 × 30 × 20 cm parcel produces a volumetric weight of 6 kg. If its actual weight is 4 kg, the chargeable weight is 6 kg, subject to the carrier policy. The calculation is:

volumetric_weight_kg = length_cm × width_cm × height_cm ÷ factor
chargeable_weight_kg = max(actual_weight_kg, volumetric_weight_kg)

The carrier may measure the parcel during sorting, transport or verification. If its chargeable weight is greater than the allowance or declared value, the difference can be deducted from the merchant wallet. Zid also documents that a Zid Logistics shipment is created when an order is marked Ready: the label is issued, the label cost is charged and the shipment appears in the dashboard.

Facts, provider rules and engineering decisions

ItemClassificationHow to use it
Higher of actual and volumetric weight determines chargeable weightDocumented Zid ruleRecompute before label creation and retain inputs
Domestic ÷4,000 and international ÷5,000Current Zid examples, subject to carrier termsVersion the factor by carrier, service and effective date
Additional charges may be deducted from the merchant walletDocumented platform behaviorReconcile wallet transactions, not just order totals
Dispute evidence includes order/AWB, weight, dimensions and photos or videoDocumented support requirementCapture evidence at packing time
One dispute should be filed for each shipmentDocumented support processUse shipment identity, not a batch-level complaint
Submit within five days from deliveryCurrent documented deadlineStart an operational timer from delivered_at
An append-only evidence ledger and automated reconciliationEngineering recommendationImplement as internal control, not as a claimed Zid feature

This separation avoids presenting an internal architecture as a platform capability.

The final packed parcel—not the loose product—is the object the carrier measures and bills.
The final packed parcel—not the loose product—is the object the carrier measures and bills. Open for a larger view

Why catalog weight alone is insufficient

A product's stored weight helps checkout pricing, but the final parcel includes cartons, fillers, inserts, tape and sometimes multiple products or boxes. A catalog can be accurate and the shipment still differ. The inverse also happens: a product record may be stale, while a packing station measures the finished parcel correctly.

Model three distinct values:

  1. catalog weight — used for estimates and customer-facing shipping decisions;
  2. packed measurement — captured after packaging and before label creation;
  3. carrier measurement — used for the final charge or difference.

Never overwrite one with another. Each represents a different moment and authority.

A measurement record that survives a dispute

Create one immutable record per parcel, not only per order:

{
  "measurement_id": "msr_01...",
  "order_id": "zid_order_id",
  "package_id": "pkg_01",
  "awb": null,
  "station_id": "pack_cairo_03",
  "operator_id": "user_42",
  "measured_at": "2026-11-10T17:36:20Z",
  "actual_weight_kg": "4.000",
  "dimensions_cm": {"length": "40.0", "width": "30.0", "height": "20.0"},
  "service_scope": "domestic",
  "volumetric_factor": "4000",
  "volumetric_weight_kg": "6.000",
  "chargeable_weight_kg": "6.000",
  "rate_rule_id": "carrier-service-effective-date",
  "media_sha256": ["..."],
  "device_calibration_id": "scale-03-cal-2026-10"
}

Use decimal types, explicit units and a documented rounding stage. Do not use binary floating point for billable values. Do not infer a factor from domestic/international alone when the chosen carrier service has a more specific contract.

When the label is issued, attach the AWB and shipment identifier as a new event rather than rewriting the original measurement. That preserves what was known before the carrier handled the parcel.

Packing-station workflow

  1. Hydrate order data. Load products, quantities, destination, shipping method and package count. Zid's order schema exposes total weight, weight-cost details and package count; treat them as platform data, not proof of the final carton.
  2. Pack completely. Measure only after all protective material and labels are in place.
  3. Capture actual weight. Read the scale, record its unit and calibration identity, and take a clear photo showing the parcel and display.
  4. Capture three dimensions. Record length, width and height in centimeters. Photograph the measuring tape or capture a short video when the operation requires stronger evidence.
  5. Resolve the rate rule. Select carrier, service, destination scope, factor, included weight, extra-weight step and effective rate-card version.
  6. Calculate provisionally. Compute volumetric and chargeable weights without pretending to predict provider rounding.
  7. Gate Ready. Block the status transition if measurements, factor provenance or required evidence are missing.
  8. Create and bind the shipment. After Ready, bind the resulting AWB, shipment and wallet transaction to the measurement record.
  9. Reconcile. Compare declared, carrier and charged values. Route differences beyond policy tolerance to review.

Reconciliation after Ready

Zid's shipment and transaction documentation describes the shipment tracking page and a transaction log containing shipping fees, weight-difference charges, payment status and wallet references. Polling every order continuously is unnecessary. Use supported order webhooks to trigger targeted work, then read authoritative shipment and transaction state.

A safe sequence is:

  1. receive and authenticate the relevant order-status webhook;
  2. deduplicate by event identity and order transition;
  3. enqueue a reconciliation job;
  4. fetch the current order and shipment state;
  5. match AWB, package count, currency and wallet reference;
  6. record the provider's result without deleting the packing measurement;
  7. open a review task when a weight-difference transaction appears.

Webhooks are delivery signals, not the final accounting authority. A retry may arrive, events can be delayed, and a provider may update a transaction after the status event. Schedule a bounded daily reconciliation for recent shipments.

Decision table

ConditionActionEvidence to retain
Packed measurement agrees with catalog estimateProceed to ReadyMeasurement, rate rule and media hashes
Volumetric weight exceeds actual weightPrice and reserve using volumetric valueDimensions, factor source and calculation
Carrier reports a higher valueReconcile the wallet transactionCarrier result, wallet reference and original evidence
Difference is explainable by rate or roundingClose with a reason codeContract version and calculation trace
Difference is not explainablePrepare one dispute for that shipmentOrder/AWB, scale photo, three dimensions and explanation
Evidence is incompleteEscalate internally; do not fabricate itMissing-evidence reason and operator record
Delivery is near the documented deadlinePrioritize review immediatelydelivered_at and deadline timestamp

Dispute workflow

The current Zid guide asks for the order number or AWB, actual weight, all three dimensions, a clear scale photo, dimension photos or a video, and an explanation. It also says each shipment needs a separate dispute and that acceptance does not guarantee a refund.

Build a case state machine:

detected → evidence_ready → submitted → under_review
         → needs_information → accepted | rejected | expired

Store the submitted bundle hash and timestamp. If support asks for more information, append a new evidence event. Do not replace the original photos, because the ability to show what was submitted matters.

Architecture example

Use five components:

  • catalog/PIM: estimate weights and dimensions;
  • packing station: capture final measurements and media;
  • rate-policy service: version factors, allowances and rounding rules;
  • shipment ledger: bind order, packages, AWB, provider measurement and wallet transaction;
  • exception queue: manage dispute deadlines and outcomes.

A shipping integration should use scoped authorization and the supported two-way API/webhook flow described by the Zid shipping integration guide. Keep merchant credentials out of photos, logs and case descriptions.

Best practices

  • Measure the final carton, not loose products.
  • Store units explicitly and decimals as strings or fixed-precision values.
  • Version every factor and rate rule by carrier service and date.
  • Hash evidence files and keep originals read-only.
  • Calibrate scales and record the calibration identity.
  • Link every wallet deduction to a shipment and AWB.
  • Reconcile recent shipments even when no webhook arrives.
  • Start the dispute timer from the documented delivery event.
  • Redact customer personal data from unnecessary support artifacts.
  • Track root causes: catalog, packaging, factor, carrier measurement or integration.

Anti-patterns

  • Hard-coding 4,000 for every domestic carrier forever.
  • Treating product weight as final packed weight.
  • Taking photos only after a charge appears.
  • Mutating the original measurement to match the carrier.
  • Combining several shipments into one dispute.
  • Retrying a status write blindly after an unknown outcome.
  • Assuming a submitted dispute guarantees a refund.
  • Logging access tokens, addresses or full customer records with evidence.

Limits

Zid's help pages describe the current dashboard and support process, but carrier contracts, factors, rounding and rate cards can vary. The exact API visibility of a carrier measurement or wallet charge depends on the product and integration available to the merchant. Where an API field is unavailable, the system should flag a manual reconciliation step instead of scraping protected pages or inventing data.

Executive checklist

  • Capture final packed weight and dimensions before Ready.
  • Resolve the carrier-service factor and rate version.
  • Store immutable media and calculation evidence.
  • Bind the measurement to AWB, shipment and wallet reference.
  • Reconcile weight-difference transactions after Ready.
  • File one complete dispute per shipment within the documented window.
  • Use results to fix catalog, packaging and rate policies.

For adjacent workflows, see Zid reverse orders: reconcile refunds, returns and stock, Salla shipment pickup time: make the handoff auditable, and Salla order stock relocation. Explore the wider engineering topics hub.

References

  1. Zid — How to calculate and dispute additional weight charges
  2. Zid — Shipping method details and customer rates
  3. Zid — Shipment tracking and transactions
  4. Zid Docs — Create Order schema
  5. Zid Docs — Webhook events
  6. Zid Partners — Integrating shipping systems with Zid
  7. Jeuwre — Measuring a parcel on a scale, CC BY-SA 4.0, Wikimedia Commons

Prepared by: Noor Yasser

Official references

These references document the tools discussed. Examples and design decisions are illustrative and should be adapted to the project and its versions.

Prepared by: Noor Yasser

FROM DECISION TO DELIVERY

Working through a similar engineering challenge?

I help teams turn architecture decisions into a clear scope and dependable, reviewable implementation.

Book a 30-minute callRelated serviceBackend engineering & API integrationsRelevant projectLogistics at scale