Add ShipKSA checkout with a single script tag.
Point the SDK at your existing cart and checkout button. Keep your cart in your own format — ShipKSA maps it for you. The SDK shows shoppers outside Saudi Arabia a checkout button styled to match yours, directly beneath it.
One script tag
No init() needed
Your cart, your format
Auto geo-gating
Quick start
1. Expose your cart (any shape)
<script>
// Your store's own cart format — no need to reshape it.
window.cart = () => ({
store: "My Store",
grandTotal: 299,
lines: [{ sku: "A1", name: "Item", count: 1, unit_price: 299 }]
});
</script>
2. Add the SDK (one tag)
<script
src="https://dev.shipksa.com/merchants/docs/shipksa-sdk.js"
cart="cart"
button="#checkout"></script>
cart is your cart source — a global variable name or a
cart-API URL (auto-detected). button points at your existing
checkout button. That's the whole integration — no init() call.
How it behaves
- Matches your button: the ShipKSA button is cloned from yours (size, padding, font, corners) and inserted directly beneath it — in the ShipKSA brand color.
- Geo-gated: shown only to shoppers outside Saudi Arabia (fail-open on any detection error).
- Your format stays yours: ShipKSA maps your cart on our side — you don't reshape it.
- Lazy & self-contained: your cart is read at click time; the SDK handles session, upload, and checkout.
Attributes
cart— a global variable name, or a cart-API URL/path (auto-detected by a leading/orhttp(s)://).button— your checkout button to sit beneath (or a container to mount inside).button-color— override the ShipKSA button color (defaults to brand).
SDK URL:
https://dev.shipksa.com/merchants/docs/shipksa-sdk.js
Onboarding: cart mapping
You don't convert your cart into ShipKSA's format. When you integrate, we
take your cart structure and register an adapter on our side, keyed to your
domain, that maps it to what ShipKSA needs:
{ platform, currency, total, items:[{ sku, title, quantity, price }] }.
Your cart (example)
{
store: "My Store",
grandTotal: 299,
lines: [
{ sku: "A1", name: "Item", count: 1, unit_price: 299 }
]
}
ShipKSA adapter (we maintain)
function adapter(raw) {
return {
platform: raw.store,
currency: "SAR",
total: raw.grandTotal,
items: raw.lines.map(l => ({
sku: l.sku, title: l.name,
quantity: l.count, price: l.unit_price
}))
};
}
If your cart is already in ShipKSA's shape, no adapter is needed — the SDK passes it through.
Other integration options
Cart API endpoint
<!-- a URL value is auto-detected and fetched -->
<script
src="https://dev.shipksa.com/merchants/docs/shipksa-sdk.js"
cart="/cart.js"
button="#checkout"></script>
Advanced: programmatic init
<script src="https://dev.shipksa.com/merchants/docs/shipksa-sdk.js"></script>
<script>
ShipKSA.init({
cart: () => storeCart,
button: "#checkout"
});
</script>