Shipping
Aramex South Africa Shopify Integration.
An Aramex South Africa Shopify integration is the go-to when you ship internationally from South Africa or serve B2B contracts requiring the Aramex brand. Aramex SA covers domestic overnight, economy, and international exports from Johannesburg, Cape Town and Durban, with stronger lanes into the Middle East, Europe and rest-of-Africa than most local couriers. This guide walks through account setup, the Aramex Shopify app versus Bob Go aggregation, live rates at checkout, and the international shipping details that matter: HS codes per product, commercial invoice fields, incoterms, and the customs declaration flow that keeps SARS happy on export.
Prerequisites
- Aramex South Africa business account number and API credentials from aramex.co.za
- Shopify store — any plan, though international shipping works best on Shopify plan or above
- SARS exporter number if you plan to ship internationally from SA (mandatory for customs)
- HS (Harmonized System) code for every product variant — store as a Shopify metafield
- Commercial invoice template aligned with the product catalog (Aramex has a sample)
Step 1. Open the right Aramex SA account
Aramex SA splits accounts between ShopRunner (ecommerce) and traditional B2B. For a Shopify store, ask for a ShopRunner account — it has the lighter API and ecommerce-friendly pricing. If you are B2B-heavy, the standard account suits scheduled pickups and account-level invoicing better.
Step 2. Generate API credentials
Log in to the Aramex My Account portal, request API access (business account only), and you will receive a username, password, account number, account PIN and entity code. Store these as secrets.
wrangler secret put ARAMEX_USERNAME
wrangler secret put ARAMEX_PASSWORD
wrangler secret put ARAMEX_ACCOUNT_NUMBER
wrangler secret put ARAMEX_ACCOUNT_PIN
# Entity is usually "JNB" for Johannesburg-origin shipments
wrangler secret put ARAMEX_ENTITYStep 3. Install the Aramex Shopify app or aggregate via Bob Go
Path A: the official Aramex app adds live rates and label generation — solid for single-courier stores. Path B: link Aramex inside Bob Go and rate-shop against Courier Guy and PUDO. Path B is usually better if Aramex is your international-only option and Courier Guy runs your domestic.
Step 4. Call the Aramex rate API for live checkout rates
Aramex uses a SOAP-based ShippingAPI. The CalculateRate method accepts origin, destination, parcel dimensions, and returns cost in ZAR.
// Minimal JSON-over-REST wrapper around Aramex SOAP (via their JSON endpoint)
const rate = await fetch('https://ws.aramex.net/ShippingAPI.V2/RateCalculator/Service_1_0.svc/json/CalculateRate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
ClientInfo: {
UserName: env.ARAMEX_USERNAME,
Password: env.ARAMEX_PASSWORD,
AccountNumber: env.ARAMEX_ACCOUNT_NUMBER,
AccountPin: env.ARAMEX_ACCOUNT_PIN,
AccountEntity: env.ARAMEX_ENTITY,
AccountCountryCode: 'ZA',
Version: 'v1.0',
},
OriginAddress: { City: 'Cape Town', CountryCode: 'ZA' },
DestinationAddress: { City: 'Dubai', CountryCode: 'AE' },
ShipmentDetails: {
PaymentType: 'P',
ProductGroup: 'EXP', // EXP = export, DOM = domestic
ProductType: 'PPX',
ActualWeight: { Value: 1.5, Unit: 'KG' },
ChargeableWeight: { Value: 1.5, Unit: 'KG' },
NumberOfPieces: 1,
},
}),
}).then((r) => r.json());Step 5. Create a shipment and print the waybill
The CreateShipments endpoint returns a waybill and a label PDF. For exports you also get a commercial invoice PDF you must include in the parcel for customs.
Step 6. Add HS codes and commercial invoice data
Customs requires an HS code, country of origin, unit value in ZAR and a truthful goods description for every line item. Store HS codes as a Shopify metafield on the product, then map them into the shipment payload.
const commercialInvoice = {
Reference1: order.name,
Items: order.line_items.map((li) => ({
PackageType: 'Box',
Quantity: li.quantity,
Weight: { Value: li.grams / 1000, Unit: 'KG' },
Comments: li.title,
Reference: li.sku,
HSCode: li.properties.hs_code, // e.g. '6109.10'
GoodsDescription: li.product_type || li.title,
CountryOfOrigin: 'ZA',
CustomsValue: { Value: li.price * li.quantity, CurrencyCode: 'ZAR' },
})),
};Step 7. Handle international returns and RMAs
International returns to SA hit customs twice — export and re-import. For high-value goods, use Aramex's DTP (delivered-paid) service to pre-clear customs. For low-value returns, swap for a store credit rather than eat the freight both ways.
Step 8. Reconcile monthly
Aramex invoicing has ZAR lines for domestic and USD-equivalent lines for international. VAT reclaim on exports requires proof of export (BOE and waybill) held for 5 years, per SARS.
SA gotchas
- International shipments without a valid HS code get held at customs. Do not ship without one — checkout should block the option if HS is missing.
- Aramex SA ShopRunner rates show in ZAR, but B2B accounts sometimes invoice international legs in USD. Match this to your bookkeeping or reconciliation gets messy.
- Residential deliveries in Middle East lanes require a working mobile number. Missing or landline numbers see parcels returned after 3 failed attempts.
- Aramex fuel surcharge updates monthly and applies post-rate. Build a 5 to 8 percent margin into checkout rates so you do not lose on fuel spikes.
- DTP versus DDU confusion: DDU (delivered duty unpaid) means the customer pays duties on receipt — set this expectation on the order confirmation page or expect refund requests.
Frequently asked questions
Is Aramex cheaper than Courier Guy in South Africa?
For domestic overnight, Courier Guy is usually cheaper for low-volume stores. Aramex becomes competitive at higher volumes and wins on international lanes where Courier Guy does not operate directly.
What does Aramex ShopRunner include?
ShopRunner is the Aramex ecommerce product: lighter API, monthly invoicing, ecommerce-tuned pricing, and integrations with Shopify, WooCommerce and Magento.
Do I need a SARS exporter number to ship from South Africa?
Yes for commercial exports. SARS issues an exporter code on eFiling, linked to your tax reference. Without it Aramex cannot clear the shipment. For occasional low-value samples, ask about simplified declarations.
Can I ship restricted items like cosmetics or liquids with Aramex from SA?
Yes, but you must flag MSDS documents for liquids and confirm the destination country accepts them. Aramex publishes a prohibited items list — check it before taking those orders at checkout.