cimplify
API reference

Link API

/v1/link/*: customer-scoped Link API for saved addresses, saved mobile money, preferences, sessions, and cross-merchant account data.

The Cimplify Link API is customer-scoped and cross-business. Saved addresses, saved mobile money, preferences, sessions, and Link account data belong to the customer, then checkout scopes what it displays to the current merchant.

SurfaceHostPath prefix
Storefront APIstorefronts.cimplify.io/api/v1/*
Link APIapi.cimplify.io/v1/link/*

@cimplify/sdk talks to this host through client.link.*.

Conventions

  • Authenticated calls use Authorization: Bearer <session_token>.
  • Update routes use POST /v1/link/<resource>/:id with a partial body.
  • Mutating routes accept Idempotency-Key.
  • Raw responses use the platform envelope:
{
  "data": { "...": "..." },
  "meta": { "timestamp": "2026-05-31T12:00:00Z" },
  "status": { "code": 200, "success": true }
}

The SDK unwraps data and returns Result<T, CimplifyError>.

Auth

POST /v1/link/auth/request-otp

curl -X POST https://api.cimplify.io/v1/link/auth/request-otp \
  -H "Content-Type: application/json" \
  -d '{"contact":"+233244000000","contact_type":"phone"}'
{
  "data": {
    "success": true,
    "message": "OTP sent to +233****0000",
    "expires_in": 300,
    "is_new_account": false
  },
  "status": { "code": 200, "success": true }
}

POST /v1/link/auth/verify-otp

curl -X POST https://api.cimplify.io/v1/link/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{
    "contact":"+233244000000",
    "contact_type":"phone",
    "otp_code":"123456"
  }'
{
  "data": {
    "success": true,
    "session_token": "eyJ...",
    "refresh_token": "eyJ...",
    "account_id": "acc_...",
    "customer_id": "cus_...",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+233244000000",
    "message": "Login successful"
  },
  "status": { "code": 200, "success": true }
}

verify-otp also sets the HttpOnly cim_session refresh cookie for .cimplify.io. Carry session_token as a bearer token on API calls.

POST /v1/link/auth/refresh

Refresh rotates the long-lived Link session and returns a new bearer token. It accepts the refresh credential from either source:

  • cim_session cookie, for browser calls from Cimplify-owned domains using credentials: "include".
  • JSON body { "session_token": "<refresh_token>" }, for server-side workers and explicit SDK calls.
curl -X POST https://api.cimplify.io/v1/link/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"session_token":"eyJ_refresh..."}'

The response shape matches verify-otp and includes a rotated refresh_token.

POST /v1/link/auth/logout

curl -X POST https://api.cimplify.io/v1/link/auth/logout \
  -H "Authorization: Bearer eyJ..."
{
  "data": {
    "success": true,
    "message": "Logged out successfully",
    "action": "discard_token"
  },
  "status": { "code": 200, "success": true }
}

Profile and Data

GET /v1/link/data

The one-shot read most callers want: customer, addresses, mobile money, preferences, and defaults.

curl https://api.cimplify.io/v1/link/data \
  -H "Authorization: Bearer eyJ..."
{
  "data": {
    "customer": {
      "id": "cus_...",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "+233244000000"
    },
    "addresses": [],
    "mobile_money": [],
    "preferences": {},
    "default_address": null,
    "default_mobile_money": null
  },
  "status": { "code": 200, "success": true }
}

GET /v1/link/profile

Returns the current Link customer profile.

POST /v1/link/profile

Updates one or more profile fields and returns the updated customer.

curl -X POST https://api.cimplify.io/v1/link/profile \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane A. Doe"}'

POST /v1/link/check-status

Returns { "is_link_customer": boolean } for a submitted contact. Use this in explicit Link account flows after the shopper enters a contact. Embedded checkout uses OAuth login_hint and loads saved details after verification.

Enrollment

POST /v1/link/enroll

Idempotency-keyed. Once enrolled, calling again returns the existing enrollment.

curl -X POST https://api.cimplify.io/v1/link/enroll \
  -H "Authorization: Bearer eyJ..." \
  -H "Idempotency-Key: 91f3..." \
  -H "Content-Type: application/json" \
  -d '{"contact":"+233244000000","name":"Jane Doe"}'

POST /v1/link/enroll-and-link-order

Atomic enrollment plus order attachment.

curl -X POST https://api.cimplify.io/v1/link/enroll-and-link-order \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_...",
    "business_id": "bus_...",
    "address": { "label":"Home", "street_address":"...", "city":"Accra", "region":"GA" },
    "mobile_money": { "phone_number":"+233244000000", "provider":"mtn", "label":"My MTN" },
    "order_type": "delivery"
  }'

Preferences

MethodPathPurpose
GET/v1/link/preferencesRead preferences.
POST/v1/link/preferencesPartially update preferences.
curl -X POST https://api.cimplify.io/v1/link/preferences \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "preferred_order_type":"delivery",
    "default_address_id":"addr_...",
    "notify_on_order": true
  }'

Addresses

MethodPathPurpose
GET/v1/link/addressesList saved addresses.
POST/v1/link/addressesCreate an address.
POST/v1/link/addresses/:idPartially update an address.
DELETE/v1/link/addresses/:idDelete an address.
POST/v1/link/addresses/:id/defaultPromote to default.
POST/v1/link/addresses/:id/track-usageIncrement usage metadata.
curl -X POST https://api.cimplify.io/v1/link/addresses \
  -H "Authorization: Bearer eyJ..." \
  -H "Idempotency-Key: 4a82..." \
  -H "Content-Type: application/json" \
  -d '{
    "label":"Home",
    "street_address":"12 Independence Ave",
    "apartment":"Flat 3",
    "city":"Accra",
    "region":"Greater Accra",
    "country":"GH"
  }'

Mobile Money

MethodPathPurpose
GET/v1/link/mobile-moneyList saved mobile-money methods.
POST/v1/link/mobile-moneyCreate a saved method.
DELETE/v1/link/mobile-money/:idDelete a saved method.
POST/v1/link/mobile-money/:id/defaultPromote to default.
POST/v1/link/mobile-money/:id/track-usageIncrement usage metadata.
POST/v1/link/mobile-money/:id/verifyRun provider verification.
curl -X POST https://api.cimplify.io/v1/link/mobile-money \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number":"+233244000000",
    "provider":"telecel",
    "label":"My main account"
  }'

provider accepts mtn, vodafone, telecel, airtel, airteltigo, and mpesa.

Orders

MethodPathPurpose
GET/v1/link/ordersList the customer's Link-visible orders.
GET/v1/link/orders/:order_idRead one order.

Both routes accept optional business_id query scope for merchant-embedded account views.

Sessions

MethodPathPurpose
GET/v1/link/sessionsList active sessions.
DELETE/v1/link/sessionsRevoke every session.
DELETE/v1/link/sessions/:idRevoke one session.

Checkout Cleanup

Checkout authenticates shoppers through Storefront OAuth. The Link API keeps one first-party cleanup route for clearing Link-owned session state when a checkout or dashboard flow signs out:

MethodPathPurpose
POST/v1/link/elements/logoutClear the Cimplify-owned cim_session cookie and revoke the supplied refresh token when present.

Support

Customer-facing support / chat-widget API. Each session has exactly one widget conversation; the server resolves it from the session identity, so callers never have to track a `conversation_id`.

Inventory

Stock and availability lookups, scoped per location. Inventory is tracked at either the product or the variant level depending on the product’s `inventory_type`.

On this page

ConventionsAuthPOST /v1/link/auth/request-otpPOST /v1/link/auth/verify-otpPOST /v1/link/auth/refreshPOST /v1/link/auth/logoutProfile and DataGET /v1/link/dataGET /v1/link/profilePOST /v1/link/profilePOST /v1/link/check-statusEnrollmentPOST /v1/link/enrollPOST /v1/link/enroll-and-link-orderPreferencesAddressesMobile MoneyOrdersSessionsCheckout CleanupRelated