Getting Started

{
  "name": "My Awesome App",
  "slug": "my-awesome-app",
  "tagline": "Boost your store with AI-powered recommendations",
  "description": "Full description of your app...",
  "category": "marketing",
  "subcategory": "Personalisation",
  "pricingModel": "freemium",
  "pricingConfig": {
    "trialDays": 14,
    "plans": [
      { "name": "Free", "price": "$0/mo", "features": ["100 recommendations/mo"] },
      { "name": "Pro", "price": "$29/mo", "features": ["Unlimited", "A/B testing"] }
    ]
  },
  "permissions": ["read_products", "read_orders", "read_customers"],
  "oauthRedirectUri": "https://myapp.com/auth/callback",
  "webhookUrl": "https://myapp.com/webhooks/mercentia",
  "languages": ["en", "fr", "de"],
  "regions": ["Global"],
  "privacyPolicyUrl": "https://myapp.com/privacy",
  "termsUrl": "https://myapp.com/terms"
}

GET https://gateway.mercentia.com/oauth/authorize
  ?client_id=sf_app_abc123
  &redirect_uri=https://myapp.com/auth/callback
  &scope=read_products,read_orders
  &state=random_csrf_token
  &response_type=code
  &code_challenge=S256_challenge_here
  &code_challenge_method=S256

GET https://myapp.com/auth/callback
  ?code=auth_code_here
  &state=random_csrf_token
  &store_id=store_uuid

{
  "grant_type": "authorization_code",
  "client_id": "sf_app_abc123",
  "client_secret": "your_client_secret",
  "code": "auth_code_here",
  "redirect_uri": "https://myapp.com/auth/callback",
  "code_verifier": "original_code_verifier"
}

{
  "access_token": "sf_at_xxxxx",
  "refresh_token": "sf_rt_xxxxx",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "read_products,read_orders",
  "store_id": "store_uuid"
}

{
  "grant_type": "refresh_token",
  "client_id": "sf_app_abc123",
  "client_secret": "your_client_secret",
  "refresh_token": "sf_rt_xxxxx"
}

const response = await fetch('https://gateway.mercentia.com/api/v1/products', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'X-Store-Id': storeId,
    'Content-Type': 'application/json',
  },
});

const { data } = await response.json();
console.log(`Found ${data.length} products`);

import requests

response = requests.get(
    'https://gateway.mercentia.com/api/v1/products',
    headers={
        'Authorization': f'Bearer {access_token}',
        'X-Store-Id': store_id,
    }
)

data = response.json()['data']
print(f'Found {len(data)} products')

curl -X GET https://gateway.mercentia.com/api/v1/products \
  -H "Authorization: Bearer sf_at_xxxxx" \
  -H "X-Store-Id: store_uuid" \
  -H "Content-Type: application/json"

import crypto from 'crypto';

app.post('/webhooks/mercentia', (req, res) => {
  // 1. Verify signature
  const signature = req.headers['x-mercentia-signature'];
  const timestamp = req.headers['x-mercentia-timestamp'];
  const body = JSON.stringify(req.body);

  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${timestamp}.${body}`)
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // 2. Check timestamp (reject if older than 5 minutes)
  const age = Date.now() - parseInt(timestamp);
  if (age > 300000) {
    return res.status(401).json({ error: 'Timestamp too old' });
  }

  // 3. Process the event
  const { event, payload } = req.body;

  switch (event) {
    case 'order.created':
      handleNewOrder(payload);
      break;
    case 'product.updated':
      handleProductUpdate(payload);
      break;
    case 'app.uninstalled':
      handleUninstall(payload);
      break;
  }

  // 4. Respond quickly (within 5 seconds)
  res.status(200).json({ received: true });
});