Marketplace account and standalone apps

The SDK lets you build your own storefront experience without embedding the Malonlin marketplace website. You still connect to Malonlin's backend: the marketplace account, subscriptions, wallet, and profile are managed there.

What “standalone” means here#

A standalone integration is an app or website you build that uses the SDK and Malonlin API, rather than using the marketplace's React pages as its interface. You own the UI, hosting, navigation, sign-in experience, and customer support. The SDK supplies API clients for store/product management, carts and checkout, wallet flows, subscriptions, profiles, orders, bookings, ratings, uploads, and webhooks.

It does not provide a ready-made storefront UI, host your site, replace the backend, or bypass backend authorization. Some capabilities depend on a user/store subscription, API-key entitlements, server configuration, and permissions. Current webhook delivery is a backend feature and is separate from local sdk.on(...) events.

Create the account in the marketplace#

1. Open the Malonlin marketplace (malonlin-website2) and create an account from its registration page (/app-web/auth/register).
2. Verify the account email if prompted, then sign in from the marketplace.
3. This account is your common Malonlin identity—not a separate “SDK user.” Use this identity for marketplace profiles, developer settings, user subscriptions, API subscriptions, and the personal wallet.
4. In the intended shared deployment, both the marketplace and SDK-facing backend use the same MongoDB database. The server projects read MONGO_URI (or MONGODB_URI / DATABASE_URL) from deployment configuration; if environments point at different databases, their accounts and wallets will not be shared.

On successful account registration, the backend attempts to create a user wallet and a default user subscription. The wallet can also be resolved or created by the authenticated myWallet operation. A wallet record is not a balance top-up, and an API plan is distinct from a store plan.

Create an API subscription and key#

1. While signed in to the marketplace, open User settings → API subscriptions (/app-web/app/user/settings/api-subscription).
2. Review the available API plans and their displayed entitlements.
3. Create a named key for your integration. The marketplace purchases/assigns the selected API plan and provisions a key for your account.
4. Save the key in a trusted secret manager or server-side environment. Rotate or revoke it if it is exposed.
5. Keep using your account access token for authenticated user actions. The API key identifies the integration and applies API access/plan policies; it does not make your app the user or authorize it to act as a store owner.

The website pairs API keys with the signed-in account's user ID. Paid API plans are user-based and use that same user's wallet; plan purchase and entitlement checks are enforced server-side. Read the currently available plan list rather than assuming a plan code or entitlement remains unchanged.

Connect your standalone app#

Use the deployed GraphQL URL and provide the key in a server-side process. Authenticated operations also need the user's access token:

import { CartSDK } from 'malonlin-sdk';

const sdk = new CartSDK({
  endpoint: process.env.MALONLIN_GRAPHQL_ENDPOINT!,
  apiKey: process.env.MALONLIN_API_KEY!,
  getAccessToken: () => authSession.getAccessToken(),
});

const wallet = await sdk.wallet.myWallet('ZAR');
console.log(wallet);

The SDK sends X-API-Key and, when available, Authorization: Bearer <access-token>. The backend applies its API-key guard and then any operation-specific authentication and permission guards. In the primary server, API-key validation is a global guard except on explicitly exempt operations.

For a Node service or your own sign-in screen, sdk.auth.login(...) authenticates the marketplace account and places its access token into the SDK client. For a browser or mobile app, do not ship a private API key in the app bundle. Put Malonlin requests behind your trusted application server, or use only a public key that the backend operator has deliberately restricted. The API key and user access token are both credentials; protect both.

// Server-side / local demonstration only.
const sdk = new CartSDK({
  endpoint: process.env.MALONLIN_GRAPHQL_ENDPOINT!,
  apiKey: process.env.MALONLIN_API_KEY!,
});

const session = await sdk.auth.login({
  email: process.env.MALONLIN_ACCOUNT_EMAIL!,
  password: process.env.MALONLIN_ACCOUNT_PASSWORD!,
});

console.log('Signed in account ID:', session.admin._id);
// sdk.auth.login(...) also sets the returned access token on this SDK instance.

Do not collect or store a user's marketplace password in a production storefront just to call the API. Connect your app's approved authentication flow and pass its current Malonlin access token through getAccessToken or sdk.setAccessToken(...).

Which subscription uses which wallet?#

The marketplace settings page is the easiest place to manage developer API keys and user profile/subscription information. Use SDK subscription methods for app experiences you build, but let the backend validate the subject, owner, payment reference, and entitlement.

When a request fails#

• Missing/invalid API key: confirm the key is active, the request reaches the expected environment, and X-API-Key is sent.
• Unauthenticated: provide a current user access token for operations requiring a signed-in account.
• Forbidden: check the current user's store membership and permissions; IDs supplied by the app are not proof of access.
• Plan/limit error: inspect the account's API subscription and the store's subscription context; entitlements are server-enforced.
• CORS/browser error: route the request through your server-side application or configure the backend's allowed origins appropriately.

After connecting, continue to Build your first store, then follow Complete store launch. For money movement, read the wallet guide.