Settings

Health check

GET /access/api/v1/settings/health

Call this on every initial page load before any other endpoint. If it returns a non-200 response for any reason, redirect to your branded coming-soon or maintenance page and stop.

Success response:

{
  "status": "ok",
  "name": "My Shop",
  "id": "69ac75f878a9512e92b56fb5"
}

Store the id in your global state — it is required for analytics events and confirms the shop is ready to serve data.

On any error: redirect to your branded coming-soon or maintenance page. The customer does not need to know the reason.

See Shop Health Check for the full gate pattern.

Get shop settings

GET /access/api/v1/settings

Returns the shop's public configuration. Fetch this on initial load to populate your theme with the merchant's branding, contact details, navigation, shipping options, and feature flags.

Cache this response — settings change infrequently. Revalidate every few minutes or on navigation.

Response:

{
  "status": "success",
  "data": {
    "_id": "69ea29a8defdd6f0debd604a",
    "branding": {
      "logo": {
        "_id": "69ac367da7e93c257591ff5a",
        "type": "image/png",
        "size": "71830",
        "title": "logo.png",
        "uploadUrl": "67e3cd865bf29cd7117f53a8/media/logo.png"
      },
      "address": "123 Example Street, Nairobi",
      "helpEmail": "hello@yourstore.com",
      "helpPhone": "0700xxx000",
      "instagramUrl": "https://instagram.com/yourstore",
      "facebookUrl": "https://facebook.com/yourstore",
      "twitterUrl": "https://twitter.com/yourstore",
      "linkedInUrl": "https://linkedin.com/company/yourstore",
      "tikTokUrl": "https://tiktok.com/@yourstore",
      "youTube": "https://youtube.com/@yourstore",
      "whatsappNumber": "254700xxx000",
      "whatsappText": "Hello there! How can we help?",
      "showContacts": true,
      "showSocials": true
    },
    "headerTopbar": {
      "activateTopBar": true,
      "topBarTemplate": "Announcements",
      "announcements": [
        { "value": "20% off every Friday", "_id": "..." },
        { "value": "Free shipping over KES 2000", "_id": "..." }
      ],
      "showShopNowButton": true,
      "menuCollectionsLimit": 10,
      "announcementInterval": 30000,
      "headerTemplate": "Simple",
      "headerLayout": "CenteredMenu",
      "menuContent": "Pages",
      "menuPages": [
        {
          "name": "Shop",
          "url": "/shop",
          "children": []
        }
      ],
      "menuCollections": []
    },
    "checkout": {
      "requiresAccount": true,
      "requiresPayments": false,
      "paymentActive": false
    },
    "reviews": {
      "allowReviews": true
    },
    "shipping": {
      "active": true,
      "removeAddress": false,
      "standardActive": true,
      "pickupActive": true,
      "mtaaniActive": false,
      "standard": [
        {
          "_id": "...",
          "title": "Standard Delivery",
          "price": 200,
          "description": "Delivered in 1–3 days",
          "default": true
        }
      ],
      "pickup": [
        {
          "_id": "...",
          "name": "Westlands",
          "buildingName": "ABC Building",
          "description": "Main location",
          "fee": 0,
          "openingHours": "9am – 6pm every day",
          "lat": -1.000000,
          "lng": 36.000000,
          "mapUrl": "https://www.google.com/maps?q=-1.000000,36.000000",
          "image": "https://...",
          "phone": "0700xxx000"
        }
      ]
    },
    "tax": {
      "active": true,
      "value": 19
    },
    "policies": [
      { "_id": "...", "policyId": "...", "type": "pricing" }
    ],
    "footer": [
      {
        "title": "Discover",
        "links": []
      },
      {
        "title": "Shop",
        "links": [
          { "title": "Wish List", "link": "/wish-list" },
          { "title": "Your Bag", "link": "/bag" }
        ]
      }
    ],
    "footerConfig": {
      "logo": {
        "_id": "...",
        "type": "image/png",
        "size": "124694",
        "title": "footer-logo.png",
        "uploadUrl": "67e3cd865bf29cd7117f53a8/media/logo.png"
      },
      "footerTemplate": "Centered",
      "showNewsletter": false
    },
    "footerPolicies": [
      { "title": "Pricing Policy", "link": "/support/pricing" }
    ],
    "pages": [
      { "name": "Shop", "url": "/shop" },
      { "_id": "...", "name": "Search", "url": "/search" },
      { "_id": "...", "name": "Checkout", "url": "/checkout" },
      { "_id": "...", "name": "Bag", "url": "/bag" },
      { "_id": "...", "name": "Wish List", "url": "/wish-list" },
      { "_id": "...", "name": "Support", "url": "/support/:id" }
    ],
    "adsTracker": {
      "facebookPixelId": "",
      "gtmId": "",
      "gaMeasurementId": "",
      "tiktokPixelId": "",
      "hotjarId": ""
    },
    "defaultPages": {
      "home": false,
      "shop": true,
      "contact": false
    },
    "popups": {
      "emailCaptureEnabled": false
    },
    "media": {
      "url": "https://your-space.cdn.digitaloceanspaces.com/shop-id/media/"
    }
  }
}

Field reference:

Field	Description
`branding`	Logo, address, contact details (email, phone), social URLs, WhatsApp config, and visibility flags for contacts and socials
`headerTopbar`	Top bar and header config: template, layout, announcement list and interval, Shop Now button, nav mode (`menuContent`), and the nav items themselves (`menuPages` or `menuCollections` depending on mode)
`checkout`	Checkout flags: whether a customer account is required, whether payments are required, and whether a payment provider is currently active
`reviews`	`allowReviews` — whether the reviews module is on. Hide all review UI when `false`
`shipping`	Active shipping methods and their config: standard rates (`title`, `price`, `default`), pickup locations (`name`, `address`, `fee`, `openingHours`, `lat`/`lng`, `mapUrl`), and Mtaani toggle
`tax`	`active` flag and `value` percentage (e.g. `19` = 19%)
`policies`	Array of configured policy types (`privacy`, `terms-of-service`, `refund`, `return`, `exchange`). Use this to know which policy links to show. Fetch content via Get policy document
`footer`	Array of footer column groups (`title` + `links`). Use to build the footer nav
`footerConfig`	Footer logo, layout template, and whether to show the newsletter signup
`footerPolicies`	Array of `{ title, link }` items for the bottom policy links row
`pages`	All pages the merchant has created (`name`, `url`). Use for dynamic navigation menus
`adsTracker`	Pixel and tracking IDs (Meta, GTM, GA4, TikTok, Hotjar). Initialise on the client — skip any field that is an empty string
`defaultPages`	Flags for which built-in pages the merchant is using (`home`, `shop`, `contact`)
`popups`	`emailCaptureEnabled` — show the email capture popup on first visit if `true`
`media.url`	Base CDN URL. Prepend to any `uploadUrl` that is a relative path rather than a full URL

menuCollections items include _id, name, slug, featured, image, and children (same shape, for subcategories). image is null if no image is set.

Get policy document

GET /access/api/v1/settings/policy/:type

Returns the content of a policy document as configured by the merchant.

:type values:

`:type`	Title
`privacy`	Privacy
`terms-of-service`	Terms of Service
`refund`	Refund
`return`	Return
`exchange`	Exchange
`shipping`	Shipping
`delivery`	Delivery
`cancellation`	Cancellation
`payment`	Payment
`pricing`	Pricing
`order`	Order
`warranty`	Warranty
`disclaimer`	Disclaimer
`cookie`	Cookie

Response:

{
  "status": "success",
  "data": {
    "_id": "...",
    "type": "pricing",
    "content": "&lt;p&gt;Pricing Policy&lt;/p&gt;&lt;p&gt;&lt;strong&gt;Free shipping on orders over KES 2000&lt;/strong&gt;&lt;/p&gt;"
  }
}

content is returned as an HTML-escaped string — < is encoded as <, > as >. You must unescape it before rendering:

function unescapeHtml(str) {
  const el = document.createElement('textarea');
  el.innerHTML = str;
  return el.value;
}

const html = unescapeHtml(data.content);
// html is now: <p>Pricing Policy</p><p><strong>Free shipping on orders over KES 2000</strong></p>

Then render the resulting HTML string in your component. content is an empty string if the merchant has not written any content for this policy yet.

Possible errors: POLICY_NOT_FOUND — the merchant has not configured this policy type. Show a "this policy is not currently available" message rather than a 404.

Health check​

Get shop settings​

Get policy document​

Health check

Get shop settings

Get policy document