API Guide

What is an API?

Imagine you're at a restaurant. You (the customer) want food from the kitchen, but you can't just walk into the kitchen and make it yourself. Instead, you tell the waiter what you want, and the waiter brings it to you.

An API is like that waiter.

• You = A computer program or tool that wants data from your store
• The kitchen = Your MercantileOS store (where all your data lives)
• The waiter (API) = The system that takes requests and delivers data back

Instead of logging into your dashboard and clicking around, other programs can "ask" the API for data (like a list of products) or tell it to do things (like create a new order).

Why Use the API?

Here are some real-world examples of why you might use the API:

• Connect to accounting software - Automatically send orders to QuickBooks or Xero
• Sync inventory with a warehouse - When your warehouse ships something, update the inventory in your store
• Build a mobile app - Create a custom app that shows your products
• Import products from a spreadsheet - Add hundreds of products at once instead of one by one
• Connect to a fulfillment service - Automatically send orders to ShipBob, ShipStation, etc.

Getting Started

To use the API, you need two things:

1. An API key - Like a password that identifies you (we'll create this in the next section)
2. A way to make requests - This could be:
   • A tool like Postman (free, good for testing)
   • Code written by you or a developer
   • Another app that connects to MercantileOS

API Keys

An API key is like a special password. It tells MercantileOS who's making the request and what they're allowed to do.

To create an API key:

1. Go to Settings > API Keys in your dashboard
2. Click "Create key"
3. Give it a name (like "Inventory Sync" or "Accounting App")
4. Choose what it can do:
   • Read - Can view data (products, orders, etc.)
   • Write - Can create and update data
   • Delete - Can delete data
5. Click "Create key"
6. Copy the key immediately! - You won't be able to see it again

Your API key will look something like this:

mk_QSqnKX5nrN4ZsjBUw2wnttDG5js95NEej0glE8sXhDk=

Making Requests

Every time you want to get or send data, you make a "request" to the API. Here's what a request looks like:

GET https://api.mercantileos.com/api/v1/products
Authorization: Bearer mk_QSqnKX5nrN4ZsjBUw2wnttDG5js95NEej0glE8sXhDk=

Let's break this down:

• GET - What you want to do (get data, in this case)
• https://api.mercantileos.com/api/v1/products - The address (URL) you're requesting
• Authorization: Bearer [your-key] - Your API key, so we know it's you

If you're using a tool like Postman:

1. Open Postman
2. Create a new request
3. Paste the URL: https://api.mercantileos.com/api/v1/products
4. Go to the "Authorization" tab
5. Choose "Bearer Token"
6. Paste your API key
7. Click "Send"
8. See your products appear!

Endpoints

An "endpoint" is just a specific address where you can get or send data. Think of it like different departments in a store:

• /api/v1/products - The products department
• /api/v1/orders - The orders department
• /api/v1/customers - The customers department

The base URL is always: https://api.mercantileos.com

So a full URL looks like: https://api.mercantileos.com/api/v1/products

HTTP Methods

There are different "methods" (or verbs) for different actions:

Responses

When you make a request, the API sends back a "response" with:

1. A status code - A number that tells you if it worked
   • 200 - Success! Everything worked.
   • 201 - Created! New thing was made.
   • 400 - Bad request. You sent something wrong.
   • 401 - Unauthorized. Check your API key.
   • 404 - Not found. That thing doesn't exist.
   • 500 - Server error. Something went wrong on our end.
2. Data - The information you asked for (in JSON format)

Here's an example response when you get a product:

{
  "id": "prod_abc123",
  "title": "Blue Cotton T-Shirt",
  "description": "A comfortable blue t-shirt made from 100% cotton.",
  "price": "29.99",
  "status": "active",
  "created_at": "2026-01-15T10:30:00Z"
}

This is JSON (JavaScript Object Notation). It's just a way to structure data that computers can easily read. The curly braces {} contain "key: value" pairs.

Handling Errors

When something goes wrong, the API tells you what happened:

{
  "error": "Product not found",
  "code": "not_found",
  "status": 404
}

Common errors and how to fix them:

• "Unauthorized" (401) - Your API key is missing or wrong. Double-check that you included it and copied it correctly.
• "Not found" (404) - The thing you're looking for doesn't exist. Check the ID or URL.
• "Bad request" (400) - You sent data in the wrong format. Check the examples below.
• "Rate limited" (429) - You're making too many requests too fast. Slow down and try again.

Products

Products are the items you sell. Here are the available endpoints:

Orders

Orders are purchases made by customers:

Customers

Customers are people who have purchased from your store:

Collections

Collections are groups of products:

Discounts

Discounts are coupon codes and sales:

Inventory

Manage stock levels:

Example: List Products

Get all your products:

GET https://api.mercantileos.com/api/v1/products
Authorization: Bearer mk_your_api_key_here

Response:

{
  "products": [
    {
      "id": "prod_abc123",
      "title": "Blue Cotton T-Shirt",
      "price": "29.99",
      "status": "active"
    },
    {
      "id": "prod_def456",
      "title": "Red Cotton T-Shirt",
      "price": "29.99",
      "status": "active"
    }
  ],
  "total_count": 2
}

Example: Create a Product

Add a new product to your store:

POST https://api.mercantileos.com/api/v1/products
Authorization: Bearer mk_your_api_key_here
Content-Type: application/json

{
  "title": "Green Cotton T-Shirt",
  "description": "A comfortable green t-shirt.",
  "price": "29.99",
  "status": "draft"
}

Notice the extra parts:

• Content-Type: application/json - Tells the API we're sending JSON data
• The JSON body with the product details

Response:

{
  "id": "prod_ghi789",
  "title": "Green Cotton T-Shirt",
  "description": "A comfortable green t-shirt.",
  "price": "29.99",
  "status": "draft",
  "created_at": "2026-02-01T14:30:00Z"
}

Example: Update Inventory

Change the stock quantity for a product:

PUT https://api.mercantileos.com/api/v1/products/prod_abc123/inventory
Authorization: Bearer mk_your_api_key_here
Content-Type: application/json

{
  "quantity": 50
}

This sets the inventory to 50 units.

Example: Get Orders

Get all orders from the last 7 days:

GET https://api.mercantileos.com/api/v1/orders?created_at_min=2026-01-25
Authorization: Bearer mk_your_api_key_here

The ?created_at_min=2026-01-25 part is a "query parameter" - it filters the results.

Response:

{
  "orders": [
    {
      "id": "order_123",
      "order_number": "#1001",
      "total": "59.98",
      "status": "fulfilled",
      "customer": {
        "email": "john@example.com",
        "name": "John Smith"
      },
      "created_at": "2026-01-26T10:15:00Z"
    }
  ],
  "total_count": 1
}

What are Webhooks?

So far, we've talked about YOU asking the API for data. But what if you want to be notified when something happens?

That's what webhooks are for.

With a webhook, MercantileOS will automatically send data to YOUR server when something happens. It's like setting up a doorbell - when someone (an event) arrives, you get notified.

Examples of webhook events:

• order.created - A new order was placed
• order.fulfilled - An order was shipped
• product.updated - A product was changed
• customer.created - A new customer signed up

Setting Up Webhooks

You'll need: A URL on your server that can receive data (this usually requires a developer).

To create a webhook:

1. Go to Settings > Webhooks in your dashboard
2. Click "Create webhook"
3. Enter the URL where you want to receive data
4. Select the events you want to be notified about
5. Click "Save"

When the event happens, we'll send a POST request to your URL with the data:

{
  "event": "order.created",
  "created_at": "2026-02-01T14:30:00Z",
  "data": {
    "id": "order_456",
    "order_number": "#1002",
    "total": "89.99",
    "customer": {
      "email": "jane@example.com"
    }
  }
}

Advanced Tax System

MercantileOS includes a comprehensive tax management system with multi-jurisdictional calculation, nexus tracking, and exemption certificates. This is smarter than Shopify's basic state-level tax and doesn't require expensive third-party services like TaxJar or Avalara.

Key Features

• Multi-jurisdictional accuracy: Automatically combines state, county, and city taxes for precise calculations
• Nexus threshold tracking: Monitor sales toward $100k/200 transaction limits with automatic alerts at 75% and 90%
• Product categories: 8 tax categories with state-specific exemption rules (clothing, food, digital goods, etc.)
• Exemption certificates: Upload and track customer tax exemptions with expiration dates
• Historical rates: Full audit trail with rate versioning for compliance

Tax Endpoints

All tax endpoints are under /api/v1/admin/tax/advanced/

Example: Create Tax Nexus

Create an economic nexus in California:

POST https://api.mercantileos.com/api/v1/admin/tax/advanced/nexus
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "country_code": "US",
  "province_code": "CA",
  "nexus_type": "economic",
  "revenue_threshold": 100000,
  "transaction_threshold": 200,
  "auto_collect": true
}

Example: Calculate Tax

Calculate tax for a cart with multi-jurisdictional items:

POST https://api.mercantileos.com/api/v1/admin/tax/advanced/calculate
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "address": {
    "country": "US",
    "province": "CA",
    "city": "Los Angeles",
    "postal_code": "90001"
  },
  "items": [
    {
      "amount": 100.00,
      "tax_category": "standard"
    }
  ]
}

// Response
{
  "total_tax": 9.50,
  "jurisdictions": [
    {
      "type": "state",
      "name": "California",
      "rate": 0.0725,
      "tax_amount": 7.25
    },
    {
      "type": "county",
      "name": "Los Angeles",
      "rate": 0.0150,
      "tax_amount": 1.50
    },
    {
      "type": "city",
      "name": "Los Angeles",
      "rate": 0.0075,
      "tax_amount": 0.75
    }
  ]
}

Advanced Shipping System

The advanced shipping system provides postal code targeting, USPS zone-based pricing, dimensional weight calculation, and smart package optimization. These features are typically only available through expensive apps on Shopify ($9-29/month).

Key Features

• Postal code targeting: Exact ranges (90001-90099) and wildcards (900*) for precise zone matching
• USPS zone-based pricing: Pre-loaded zone chart with ~43,000 ZIP combinations for accurate rate calculation
• Dimensional weight: Automatic calculation using (L × W × H) / 166 formula
• Package optimization: First-Fit Decreasing bin-packing algorithm for multi-item orders
• Multiple rate types: Flat, weight-based, price-based, and USPS zone-based rates

Shipping Endpoints

All shipping endpoints are under /api/v1/admin/shipping/advanced/

Example: Create Shipping Zone

Create a zone for Southern California with postal code targeting:

POST https://api.mercantileos.com/api/v1/admin/shipping/advanced/zones
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "Southern California",
  "countries": ["US"]
}

// Then add postal ranges
POST /api/v1/admin/shipping/advanced/zones/{zone_id}/postal-ranges

{
  "country_code": "US",
  "start": "90001",
  "end": "90099"
}

// Or use wildcard
{
  "country_code": "US",
  "wildcard": "900*"
}

Example: Calculate Shipping Rates

Calculate rates with dimensional weight and package optimization:

POST https://api.mercantileos.com/api/v1/admin/shipping/advanced/calculate
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "destination": {
    "country": "US",
    "postal_code": "10001"
  },
  "items": [
    {
      "weight": 2.5,
      "length": 10,
      "width": 8,
      "height": 6
    }
  ]
}

// Response
{
  "rates": [
    {
      "method_name": "USPS Priority Mail",
      "rate": 12.50,
      "zone": 4,
      "dimensional_weight": 2.89,
      "actual_weight": 2.5,
      "billable_weight": 2.89
    }
  ],
  "packaging": {
    "num_packages": 1,
    "optimized": true
  }
}

Example: USPS Zone Lookup

Lookup USPS zone for origin-destination pair:

POST https://api.mercantileos.com/api/v1/admin/shipping/advanced/usps-zone
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "origin_zip": "90001",
  "dest_zip": "10001"
}

// Response
{
  "zone": 8,
  "origin_prefix": "900",
  "dest_prefix": "100"
}

Need Help?

The API can seem complicated at first, but it's really just about sending and receiving data. Here are some resources:

• Email us - support@mercantileos.com (we're happy to help!)
• Hire a developer - If you need custom integrations, we can recommend someone
• Use Postman - Great for testing requests before writing code

Personalization Engine

The Personalization API enables dynamic, visitor-specific experiences to maximize conversions. Generate personalized discount codes, predict cart abandonment, and trigger automated interventions.

Key Features

• Dynamic Discounts - Auto-generate personalized codes based on visitor behavior
• Abandonment Prediction - ML model predicts cart abandonment risk in real-time
• Smart Interventions - Trigger exit-intent offers when visitors show abandonment signals
• Conversion Tracking - Monitor redemption rates and revenue impact

Personalization Endpoints

Example: Generate Personalized Discount

POST /api/v1/personalization/discounts
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
X-Tenant-ID: YOUR_SHOP_ID

{
  "visitor_id": "vis_abc123",
  "discount_type": "percentage",
  "discount_value": 15.0,
  "reason": "exit_intent",
  "expires_at": "2026-03-01T23:59:59Z"
}

A/B Testing (Bayesian)

Bayesian A/B testing provides statistically rigorous experiment results with faster convergence than traditional frequentist methods. Test offers, pricing, layouts, or messaging with automatic probability calculations.

Key Features

• Fast Convergence - Reach statistical significance faster than traditional A/B tests
• Probability Calculations - Automatic calculation of probability each variant is best
• Multiple Variants - Test 2-10 variants simultaneously
• Real-time Results - Monitor conversion rates and confidence levels as data arrives

Testing Endpoints

Example: Create Bayesian Test

POST /api/v1/testing/bayesian
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "name": "Checkout Discount Test",
  "description": "Test 10% vs 15% vs 20% discount",
  "test_type": "offer",
  "goal_metric": "conversion",
  "target_probability": 0.95,
  "min_sample_size": 1000,
  "variants": [
    { "name": "Control (10%)", "is_control": true, "config": {"discount": 10} },
    { "name": "Variant A (15%)", "is_control": false, "config": {"discount": 15} },
    { "name": "Variant B (20%)", "is_control": false, "config": {"discount": 20} }
  ]
}

Multi-Armed Bandit

Multi-armed bandit algorithms dynamically allocate traffic to better-performing variants during the test, reducing opportunity cost compared to traditional A/B testing.

Algorithms

• Epsilon-Greedy - Explore ε% of time, exploit (1-ε)% on best arm
• Thompson Sampling - Bayesian probability matching (recommended)
• UCB (Upper Confidence Bound) - Optimistic exploration with confidence intervals

Bandit Endpoints

Example: Select Arm

POST /api/v1/testing/bandit/select
Content-Type: application/json

{
  "experiment_id": "exp_abc123",
  "visitor_id": "vis_xyz789"
}

Response:
{
  "arm_id": "arm_2",
  "name": "$129",
  "config": {"price": 129.00}
}

Payment Recovery

Automated payment retry and recovery workflow to recapture failed transactions. Smart retry scheduling based on decline reason and historical recovery rates.

Retry Strategies

• wait_24h - Retry after 24 hours (insufficient funds)
• wait_72h - Retry after 72 hours (do not honor)
• immediate - Retry immediately (temporary decline)
• do_not_retry - Fraudulent or permanently declined

Recovery Endpoints

Example: Create Recovery Sequence

POST /api/v1/recovery/sequences
Content-Type: application/json

{
  "visitor_id": "vis_abc123",
  "abandoned_cart_id": "cart_xyz789",
  "steps": [
    {
      "channel": "email",
      "delay_mins": 60,
      "template_id": "tmpl_abandoned_1",
      "message": "You left items in your cart!"
    },
    {
      "channel": "email",
      "delay_mins": 1440,
      "message": "Still interested? Here's 10% off"
    }
  ]
}

Intelligence & Segmentation

Visitor intelligence and segmentation for targeted marketing and personalization. Real-time purchase intent scoring based on behavioral signals.

Intent Score Ranges

• High (70-100) - Strong purchase intent, show urgency messages
• Medium (40-69) - Considering purchase, nurture with content
• Low (0-39) - Browsing, educate and engage

Intelligence Endpoints

Example: Score Visitor

POST /api/v1/intelligence/intent/score
Content-Type: application/json

{
  "visitor_id": "vis_abc123",
  "session_id": "ses_xyz789",
  "events": [
    {"type": "page_view", "url": "/products/widget"},
    {"type": "add_to_cart", "product_id": "prod_123"},
    {"type": "view_checkout"}
  ]
}

Response:
{
  "visitor_id": "vis_abc123",
  "score": 85,
  "confidence": 0.91,
  "recommended_action": "show_limited_time_offer"
}