WooCommerce Shipping Integration: Volumetric Weight, Labels and Tracking

Volumetric weight calculation, rate rules, shipments and labels via API, tracking notifications and the returns flow in WooCommerce shipping integration, along with the errors that come up most in the field.
Technical summary
Technology
WooCommerce, Carrier API, Webhook, ZPL, HPOS
Topic
Automating the post-order shipment, label, tracking and returns flow
Level
Intermediate
Prerequisites
  • Knowledge of WooCommerce shipping zones and order statuses
  • A contract with the carrier that includes API access
In this article7 sections

When the number of orders exceeds a few dozen a day, manual shipping entry starts producing errors: wrong district, missing phone number, tracking numbers that never reach the customer, return packages nobody can match to an order. The problem usually isn’t the carrier but that the data flow between WooCommerce and the carrier API was never designed. Below, we go through each step of this flow in order, from volumetric weight calculation to accepting returns, along with where it gets stuck most often in the field.

The data flow in a shipping integration

A carrier API integration consists of four separate data exchanges, each with a different trigger:

Step Direction Trigger Data
Rate calculation Within the web or via API Cart / checkout page Address, volumetric weight, weight
Shipment creation Web → carrier When the order is prepared Recipient, package, reference
Label Carrier → web Shipment response Barcode, PDF or ZPL
Status tracking Carrier → web Webhook or periodic query Movement and delivery information

The key decision is the moment the shipment is opened. Opening a shipment automatically on payment approval produces shipments that will be cancelled when a stock count discrepancy turns up in the warehouse. Open the shipment when the order has been picked and packed. The actual volumetric weight and number of packages are only known at that moment. In businesses using an ERP or warehouse management system, the shipment is usually opened from that system, and WooCommerce only receives the tracking information. Put in writing from the start which system writes which field, according to the ownership principle in the ERP and web integration patterns article; integrations where two systems write the same field sooner or later overwrite each other’s data.

Volumetric weight and weight calculation

Desi is the unit that converts package volume into a weight equivalent. In domestic shipping in Türkiye, the common formula is the product of length, width and height in centimeters divided by 3000. The divisor can vary by carrier and service type; go by the value in your contract. Pricing usually uses whichever is greater: the desi value or the actual weight in kilograms.

An example calculation: For a 40 × 30 × 25 cm box weighing 6 kg, desi = 40 × 30 × 25 / 3000 = 10. The value used for pricing is 10, because 10 desi is greater than 6 kg. If the same product fits into a 40 × 30 × 15 cm box, the desi drops to 6 and equals the weight. The box standard is a cost decision.

In WooCommerce, weight and dimensions are entered for each product; the units are defined under WooCommerce → Settings → Products. However, adding up the desi of the products in the cart doesn’t give the actual package desi; three small products fit into one box. Two approaches are used:

  • Estimated desi: The sum of product desi values in the cart, or logic that fits them into defined box types, is used; the rate on the checkout page is an estimate.
  • Actual desi: The box dimensions measured in the warehouse are entered when the shipment is opened. The difference between the fee charged to the customer and the carrier invoice is reported periodically.

The picture we encounter most often in the field is this: half the products have empty dimension fields, the desi calculation returns zero and the checkout page shows the lowest rate for a bulky product. Complete the product data before the integration.

Shipping rate rule models

The shipping fee shown to the customer and the amount paid to the carrier aren’t the same thing. When choosing a rate model on corporate e-commerce sites, accuracy, explainability to the customer and checkout page speed are weighed together.

Model Advantage Limitation
Flat rate Simple, fast, easy to understand Loss on bulky products
Free above a certain amount Increases the cart value The cost is loaded onto the product margin
Table based on volumetric weight/weight Close to cost Product dimensions must be complete
Zone-based Reflects the surcharge for remote areas Zone definitions need maintenance
Live API rate Real-time and exact The checkout page becomes dependent on the carrier API

WooCommerce’s built-in structure consists of shipping zones, methods within a zone (flat rate, free shipping, local pickup) and shipping classes. The flat rate method’s cost field supports simple expressions: [qty] gives the number of items, [cost] the cart total; [fee percent="10" min_fee="20"] defines a fee calculated as a percentage of the cart total, with a minimum. For example, the expression 30 + ( 5 * [qty] ) adds 5 units per item to a flat fee of 30 units. Creating a separate shipping class for bulky products and adding a surcharge only to that class solves most problems without setting up a volumetric weight table.

If you use a live API rate, the checkout page mustn’t lock up when the carrier API doesn’t respond; define a short timeout and a fallback flat rate. If the external service goes down, sales shouldn’t stop. Calculated rates are kept in WooCommerce’s shipping session cache; the API isn’t called again unless the address or cart changes.

Creating shipments and printing labels

A shipment request typically carries the recipient name, phone, full address, province/district, number of packages, the volumetric weight and weight of each package, the payment type (sender pays, recipient pays, cash on delivery) and the reference number on your side. Use the order number as the reference; this is the most reliable way to link the record in the carrier panel back to the order.

Points to check in practice:

  • Address normalization: Province and district should come from a selection list, not free text. Carrier APIs validate the province/district name or code against their own lists; the difference between “Eyüp” and “Eyüpsultan” means a shipment error.
  • Phone format: Since an SMS will go to the recipient, the phone number should be stored in a single format (e.g. 10 digits without the country code).
  • Duplicate protection: Once the shipment number is written to the order, the button should be disabled; if the API times out, a query by reference should be made before sending a new request. Otherwise the same order gets two barcodes.
  • Multiple packages: If the order is split across more than one box, each package has its own barcode; tracking information is stored as a list at the order level.

Labels are usually returned as PDF or ZPL. PDF is printed on an office printer but needs cutting for adhesive labels. If there’s a thermal label printer in the warehouse, the ZPL output goes straight to the printer; the label size (commonly 100 × 100 mm or 100 × 150 mm) must match the carrier’s template. If the label length defined on the printer differs from the template, the barcode gets cut off and can’t be read at the branch. In batch printing, opening shipments for the selected orders in one go and merging the labels into a single file speeds up packing.

Tracking number and customer notification

The tracking number should be written to the order as metadata and be visible both on the admin screen and in the order details in the customer’s account. In a store with HPOS enabled, the order object is used instead of post meta directly:

$order = wc_get_order( $order_id );
$order->update_meta_data( '_tracking_number', $tracking_no );
$order->update_meta_data( '_carrier', 'example-carrier' );
$order->save();

// Order note emailed to the customer (second parameter 1 = customer note)
$order->add_order_note(
    sprintf( 'Your order has been shipped. Tracking number: %s', $tracking_no ),
    1
);
$order->update_status( 'completed' );

A note added as a customer note triggers WooCommerce’s “Customer note” email. If the order is moved to completed at the same time, the “Order completed” email goes out too. The customer gets two emails. If you don’t want this, send the tracking number in only one of them (e.g. with a field added to the completed email template). Some businesses define a custom order status called “Shipped” and move the order to completed after delivery; in that case, the custom status’s email template and which group it counts toward in reports must be handled separately.

There are two methods for status updates. If the carrier provides webhooks, events such as delivered, out for delivery and returned arrive in real time; the receiving side must verify the signature and recognize repeated events. If there’s no webhook, open shipments are queried at set intervals. The query job should cover only undelivered shipments younger than a certain age; otherwise thousands of unnecessary requests go out on every run and you hit the carrier’s request limit. The secure design of a webhook receiver is covered separately in the webhook receiver design guide.

Return shipping and warehouse checklist

In the returns flow, the customer is given a return code and hands the package in at a branch with this code. The code should be generated via the API when the return request is approved and linked to the order; that way, the barcode shows which order the package arriving at the warehouse belongs to. When the package reaches the warehouse, the product is checked, then the refund is triggered through the payment provider. Money isn’t refunded before the product is seen. Refund rules on the payment side are in the WooCommerce virtual POS integration article.

The list to check before going live and in daily operations:

  • Are the weight and dimension fields filled in for all products, and are the units correct?
  • Are the standard box types and dimensions defined?
  • Are the volumetric weight divisor and zone rules in the contract the same as the integration settings?
  • Do the province/district fields match the carrier’s list?
  • Is a fallback rate defined for the checkout page in case of an API timeout?
  • Is shipment creation protected against duplicates; is a second shipment for the same order blocked?
  • Are the label size and printer settings compatible with the carrier template?
  • Does the tracking number appear in the customer email and on the account page?
  • Is the report on stalled shipments and undeliverable packages running?
  • Is the return code linked to the order, and is the payment refund triggered after warehouse acceptance?
  • Are the carrier invoice and the shipping fees charged to customers compared monthly?

To plan shipping, payment and ERP flows in a single store setup, see the scope on our WooCommerce e-commerce solutions page.

Frequently asked questions

Which divisor should be used to calculate volumetric weight (desi)?

For domestic shipping in Türkiye, the common divisor is 3000; length, width and height in centimeters are multiplied and divided by 3000. The divisor can vary by carrier and service type; use the value in your shipping contract in the integration.

Should the shipment be created as soon as payment is received?

Usually not. The actual box size and number of packages are only known during packing. Opening the shipment at the packing step reduces cancelled shipments and incorrect volumetric weight declarations.

How is status tracking done if the carrier has no webhook?

Undelivered shipments are queried from the tracking API at set intervals. Limit the query scope to open shipments younger than a certain age, and respect the carrier’s request limits.

Is it possible to work with more than one carrier?

Yes. A separate method or zone rule can be defined for each carrier. Store the carrier information together with the tracking number in the shipment record; the tracking link shown to the customer should be generated according to the carrier.

Support

Contact us for support or a discovery session on this topic.

Contact form
[email protected]

Eretek Web

We build and maintain corporate websites, WordPress and CMS platforms, intranet and SharePoint portals, document management, and form and approval workflows, and keep them secure and up to date.

Knowledge Center

Other articles