Malonlin SDK Docs
Docs / Getting Started

Build your first store

Let's get a small store working end to end. In a few steps, this Node.js example connects to your Malonlin server, creates a store for the signed-in account, adds a draft product, and prints the result.

The sample creates real records on the server. Run it with a test account and test data. Each run creates another store and product.

1. Install the SDK#

Create a folder for the walkthrough, then install the SDK from npm:

sh
mkdir first-store
cd first-store
npm init -y
npm install malonlin-sdk

2. Set the server URL and sign-in token#

Use the GraphQL URL of the running backend that will own this store. Get an access token by signing in to your test account through your app or the normal authentication flow. Keep the token out of source control.

In PowerShell, set the values for this terminal:

powershell
$env:MALONLIN_GRAPHQL_ENDPOINT = 'https://your-server.example/graphql'
$env:MALONLIN_ACCESS_TOKEN = 'your-test-account-access-token'

In a Unix-like shell:

sh
export MALONLIN_GRAPHQL_ENDPOINT='https://your-server.example/graphql'
export MALONLIN_ACCESS_TOKEN='your-test-account-access-token'

If the backend requires an API key, configure only an appropriately restricted key for this example. Never put a private API key in browser or mobile app code.

3. Create create-store.mjs#

Create create-store.mjs in your first-store folder and paste this in:

js
import { CartSDK } from 'malonlin-sdk';

const endpoint = process.env.MALONLIN_GRAPHQL_ENDPOINT?.trim();
const accessToken = process.env.MALONLIN_ACCESS_TOKEN?.trim();

if (!endpoint) throw new Error('Set MALONLIN_GRAPHQL_ENDPOINT to your server GraphQL URL.');
if (!accessToken) throw new Error('Set MALONLIN_ACCESS_TOKEN to a signed-in test account token.');

const sdk = new CartSDK({
  endpoint,
  accessToken,
  apiKey: process.env.MALONLIN_API_KEY,
});

async function main() {
  const store = await sdk.account.createStore({
    name: 'Little Market Demo',
    email: 'demo-store@example.com',
    categories: ['Home & Living'],
    contact: {
      phone: '+27110000000',
    },
    physicalAddress: {
      line1: '1 Example Street',
      suburb: 'Central',
      city: 'Cape Town',
      state: 'Western Cape',
      postalCode: '8001',
      country: 'South Africa',
    },
  });

  if (!store?.id) throw new Error('The server created no store ID.');

  // Resolve the signed-in owner's membership; do not supply an arbitrary user ID.
  const memberId = await sdk.members.myStoreMemberId(store.id);
  if (!memberId) throw new Error('The server did not return the current user's store membership.');

  const product = await sdk.products.createStoreProduct(
    {
      name: 'Handmade Demo Mug',
      description: 'A sample product created with the Malonlin SDK.',
      price: 120,
      currencyCode: 'ZAR',
      productType: 'PHYSICAL',
      totalInventory: 10,
      categories: ['Home & Living'],
      published: false,
    },
    store.id,
    memberId,
  );

  const storeProducts = await sdk.products.storeProducts(store.id, memberId, 'ZAR');

  console.log('Store created:');
  console.log(JSON.stringify(store, null, 2));
  console.log('\nDraft product created:');
  console.log(JSON.stringify(product, null, 2));
  console.log(`\nProducts visible to this store account: ${storeProducts.length}`);
}

main().catch((error) => {
  console.error('The first-store walkthrough failed:', error);
  process.exitCode = 1;
});

The server requires a store name, email, and physical address. Product name and price are required; this example uses a physical product and creates it unpublished, so it is a draft and is not exposed as a public listing yet.

4. Run it#

From the first-store folder:

powershell
node create-store.mjs

You should see the new store, the draft product, and the number of products returned for that store. If the command fails, check the endpoint and token, confirm the server is reachable, and make sure the signed-in account is permitted to create a store.

The walkthrough file is create-store.mjs above. It uses the SDK's self-scoped store creation and membership lookup. The server still checks authorization, store limits, and product rules on every request.

5. Publish the product when you're ready#

The walkthrough intentionally leaves the product unpublished. Once you've reviewed it, publish it through an owner/member-authorized flow:

js
await sdk.products.toggleStoreProductPublished(
  product.id,
  true,
  store.id,
  memberId,
);

Publishing can make the product visible on public storefronts. Check the returned result and verify the listing with sdk.products.publicStoreProducts(store.id, 'ZAR').

What you just built#

  • A CartSDK connected to your running GraphQL server.
  • A store created for the authenticated account (without sending a caller-chosen owner ID).
  • An owner membership resolved from the authenticated session.
  • A draft physical product created under that store.
  • A store product listing read back from the server.

Next, see the complete store launch guide for advanced setup, store and member management for invitations and permissions, and the field reference for product fields and product-type requirements.

Malonlin SDK documentation