Shipping
PUDO Locker Integration for South African Shopify Stores.
A PUDO locker integration in South Africa unlocks the cheapest legitimate ecommerce shipping tier in the country — roughly R60 to R120 per parcel, with 24/7 self-service collection at PEP stores and standalone PUDO units. PUDO (run by The Courier Guy) covers more than 500 lockers across South Africa, and Shopify stores can plug in via Bob Go, Shiplogic, or a direct API build. This guide covers locker-to-locker versus door-to-locker flows, size classifications from XS to XL, the 7-day collection window, pickup-code delivery, and the Shopify checkout mechanics that make customers actually pick the locker option instead of defaulting to door delivery.
Prerequisites
- PUDO / Courier Guy business account with API credentials
- Shopify store — Bob Go or Shiplogic app installed, or a custom Carrier Service app
- Clear parcel size mapping (XS, S, M, L, XL) for your product catalog
- SMS or WhatsApp sending provider for pickup-code notifications
- Order confirmation and shipping notification email templates that include the locker address
Step 1. Understand the four PUDO flows
Locker-to-locker (cheapest, customer drops and collects at a locker), door-to-locker (you courier from your warehouse to a locker near the customer), locker-to-door (returns), and door-to-door (same as Courier Guy overnight). For ecommerce, door-to-locker is the main flow. Locker-to-locker is for C2C marketplaces.
Step 2. Map your products to PUDO size classes
PUDO uses five size buckets. Get the internal locker dimensions from the PUDO docs and tag each product variant with its size class in Shopify metafields. Oversized products should suppress the PUDO option at checkout.
{
"pudo_size_classes": {
"XS": { "max_l": 60, "max_w": 17, "max_h": 8, "price_zar": 60 },
"S": { "max_l": 60, "max_w": 41, "max_h": 8, "price_zar": 75 },
"M": { "max_l": 60, "max_w": 41, "max_h": 19, "price_zar": 90 },
"L": { "max_l": 60, "max_w": 41, "max_h": 41, "price_zar": 105 },
"XL": { "max_l": 60, "max_w": 41, "max_h": 69, "price_zar": 120 }
}
}Step 3. Show locker picker at Shopify checkout
Use Bob Go's or Shiplogic's locker-picker widget (both ship drop-in Shopify blocks) or build a custom checkout UI extension. The customer types their suburb, picks a locker, and the locker ID goes onto the order as an attribute.
// Shopify Checkout UI Extension — picker stub
import { reactExtension, Select, useApplyAttributeChange } from '@shopify/ui-extensions-react/checkout';
export default reactExtension('purchase.checkout.shipping-option-list.render-after', () => <LockerPicker />);
function LockerPicker() {
const applyAttr = useApplyAttributeChange();
const lockers = usePudoLockers(); // fetch by suburb
return (
<Select
label="Collect from locker"
options={lockers.map((l) => ({ value: l.id, label: `${l.name} — ${l.suburb}` }))}
onChange={(value) => applyAttr({ type: 'updateAttribute', key: 'pudo_locker_id', value })}
/>
);
}Step 4. Generate a PUDO shipment via API
Call the PUDO shipment endpoint with the locker ID as the delivery node. Response includes a waybill number, a pickup code, and a label.
const shipment = await fetch('https://api-pudo.co.za/v1/shipments', {
method: 'POST',
headers: { 'Authorization': `Bearer ${env.PUDO_API_KEY}` },
body: JSON.stringify({
service: 'D2L', // door to locker
size_class: order.attributes.pudo_size_class,
destination_locker_id: order.attributes.pudo_locker_id,
recipient: { name: order.customer.name, phone: order.shipping_address.phone },
reference: order.name,
}),
}).then((r) => r.json());
// shipment.pickup_code and shipment.label_url
Step 5. Send the pickup code to the customer
Once PUDO scans the parcel into the destination locker, a webhook fires. Use that event to send an SMS or WhatsApp with the 6-digit pickup code, the locker address, and the 7-day collection deadline. Do not email the code alone — SA mobile-first shoppers often miss it.
Step 6. Handle the 7-day collection window
If the parcel is not collected within 7 days PUDO returns it to sender and charges a return fee. Trigger a day 5 reminder and a day 6 final reminder. If no scan-out by day 7, proactively contact the customer — this saves 70 percent of would-be returns in our stores.
Step 7. Book returns as locker-to-door
A PUDO return is a locker-to-door job: the customer drops at any locker, you receive it at your warehouse. Generate the return label up-front and include it in the delivery confirmation email — no printer-at-home requirement in SA, because labels are printed at the locker.
SA gotchas
- Parcels over XL get rejected at the locker. Your checkout must hard-block XL+ products from the locker option, not just warn the customer.
- Locker availability changes daily — refresh the locker list hourly, not monthly. A full locker in Sandton will still show in stale data and fulfillment fails at scan-in.
- PEP-partner lockers close with the PEP store, which means Sunday collections are not guaranteed. Communicate operating hours on the confirmation page.
- The 7-day window starts at locker scan-in, not at order placement. Customers who read the timer from the order date will complain — set expectations in the shipping notification email.
- Pickup codes can be phished. Tell customers in copy that PUDO will never ask for the code over a phone call.
Frequently asked questions
How much does PUDO cost versus door-to-door in South Africa?
PUDO door-to-locker ranges roughly R60 to R120 depending on size, versus R90 to R180 for a Courier Guy overnight door-to-door on the same parcel. For a small-parcel store, PUDO is 30 to 50 percent cheaper.
Can I offer PUDO alongside Courier Guy at checkout?
Yes, and you should. Bob Go and Shiplogic both rate-shop PUDO and Courier Guy in the same cart, and customers pick the locker option about 25 to 40 percent of the time when it's priced cheaper.
What happens if the customer never collects?
The parcel returns to you and PUDO charges a return fee. Best practice is a day 5 and day 6 reminder, then a phone call on day 7 from your support team.
Does PUDO integrate with Shopify POS?
Not natively. You can generate waybills from Shopify admin, but in-store POS users typically use the PUDO portal directly for manual dispatch.