Start a Project
All guides

Shipping

Courier Guy Shopify Integration for South African Stores.

A Courier Guy Shopify integration is the default shipping choice for most South African Shopify stores, and for good reason: national overnight coverage, solid tracking, and pricing that makes sense from Cape Town to Polokwane. This guide walks through three install paths — the official Shipnode app, a Bob Go aggregator setup, and a direct REST API build for waybill generation and POD webhooks. You will see the real trade-offs around suburb-level rate shopping, outlying-area surcharges, overnight versus economy, and the tracking page customers actually open from SMS and WhatsApp. Everything here assumes a Shopify store selling into South Africa with a live Courier Guy account number.

Updated 15 April 2026 · 9 min read · Shopify · Joshua Kaplan

Prerequisites

  • Active Courier Guy business account with account number and API credentials
  • Shopify store on any plan (Basic is fine for native rates at checkout via apps)
  • Store addresses and default package dimensions configured in Shopify
  • Webhook endpoint or middleware (Make.com, n8n, or a Cloudflare Worker) if you want POD events

Step 1. Pick your integration path

Three realistic options: (1) Shipnode / Courier Guy Shopify app for the fastest path; (2) Bob Go as an aggregator if you want rate shopping across Courier Guy + other couriers; (3) direct REST API for full control over waybills, labels and webhooks. Most stores under R5m/year run option 1 or 2. High-volume stores build option 3.

Step 2. Create API credentials inside the Courier Guy portal

Log in at portal.thecourierguy.co.za, open the API / integrations section, and generate an API key bound to your account number. Keep it out of your git history — store it as a Shopify app secret or a Cloudflare Workers secret.

terminal
# Save your key as a Wrangler secret
wrangler secret put COURIER_GUY_API_KEY
wrangler secret put COURIER_GUY_ACCOUNT_NO

Step 3. Generate a waybill via the REST API

The waybill endpoint accepts pickup, delivery, parcel dimensions and a service type (OVN for overnight, ECO for economy). Response returns a waybill number and a PDF label URL you can print or email.

waybill.js
const res = await fetch('https://api.thecourierguy.co.za/v1/waybills', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${env.COURIER_GUY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    account_number: env.COURIER_GUY_ACCOUNT_NO,
    service_type: 'OVN',
    collection: { suburb: 'Cape Farms', postcode: '7441' },
    delivery: {
      name: order.shipping_address.name,
      street: order.shipping_address.address1,
      suburb: order.shipping_address.city,
      province: order.shipping_address.province,
      postcode: order.shipping_address.zip,
      phone: order.shipping_address.phone,
    },
    parcels: [{ length: 30, width: 20, height: 10, weight: 1.5 }],
    reference: order.name,
  }),
});
const { waybill_number, label_url } = await res.json();

Step 4. Wire up live rates at Shopify checkout

Use Shopify's Carrier Service API or the Courier Guy app's built-in rate card. Send cart weight, destination postcode and suburb, return OVN and ECO as two options. Add a fallback flat rate if the API times out — checkout conversion dies if shipping options spin for more than 3 seconds.

carrier-service.js
// Shopify CarrierService callback payload
export async function rateCallback(req) {
  const { rate } = await req.json();
  const totalWeight = rate.items.reduce((w, i) => w + i.grams * i.quantity, 0);
  try {
    const rates = await getCourierGuyRates({
      to_postcode: rate.destination.postal_code,
      to_suburb: rate.destination.city,
      weight_kg: totalWeight / 1000,
    });
    return Response.json({ rates });
  } catch {
    // Fallback so checkout does not stall
    return Response.json({
      rates: [{ service_name: 'Courier Guy Overnight', total_price: '12900', currency: 'ZAR' }],
    });
  }
}

Step 5. Listen for POD and tracking webhooks

Register a webhook URL in the portal for delivered, out_for_delivery and failed events. Match the waybill number back to the Shopify order and flip fulfillment status. Triggers in Klaviyo or WhatsApp (Gupshup, 360dialog) can fire the delivered notification from the same event.

Step 6. Publish a branded tracking page

Point customers to a /track?waybill=... page on your own domain. Fetch the status from the API and render it — tracking pages on your domain are worth 2 to 4 percent extra LTV from repeat sessions, versus linking to the generic Courier Guy tracker.

Step 7. Send SMS and WhatsApp notifications

Trigger an SMS at handover and a WhatsApp message at out_for_delivery. SA open rates on WhatsApp sit around 90 percent. Clickatell, BulkSMS and 360dialog are the common providers. Keep the template opt-in-aligned with POPIA.

Step 8. Reconcile invoices monthly

Courier Guy bills weekly or monthly depending on your account. Pull the shipment report from the portal, match waybills to Shopify orders, and flag any surcharge lines — outlying-area and residential surcharges are the main surprises.

SA gotchas

  • Outlying-area surcharges apply to many rural and smaller-town postcodes. The rate API returns the base rate only — surcharges often appear on the invoice, not the quote.
  • Residential surcharges hit unexpectedly in suburbs the API classifies as residential. Build a spreadsheet of offenders after your first invoice.
  • Waybill PDF URLs expire. Print or store the label in R2/S3 within minutes, not hours.
  • Same-day and Sameday Express are separate services — not every account has them enabled. Check the portal before promising same-day at checkout.
  • POD scans sometimes lag by 12 to 24 hours on Fridays. Do not auto-refund a "not delivered" complaint before checking the portal manually.

Frequently asked questions

Should I use the Courier Guy app or Bob Go for Shopify?

Use the Courier Guy app if Courier Guy is your only courier. Use Bob Go if you want rate shopping across Courier Guy, PUDO, Aramex and others on the same cart. Bob Go adds a small margin but saves you from running four integrations.

Can I print waybills in bulk?

Yes. The API supports batch waybill creation, and the portal has a bulk upload via CSV. Most stores doing over 50 orders per day automate this from the orders webhook.

Does Courier Guy support cash on delivery in South Africa?

Not for ecommerce by default. COD is available on B2B accounts with a separate agreement. Plan around prepaid online payments instead.

How do I handle returns?

Generate a collection waybill with collection and delivery addresses swapped. The portal has a returns booking form, or the API accepts a service_type of COL for collections.