Merchant API

Connect your business systems to MaxaFi — sync customers, transactions, products, and more.

Authentication

Every request requires an API key in the X-Api-Key header. Keys start with mk_ followed by 48 hex characters.

# Example request
curl -H "X-Api-Key: mk_a1b2c3d4e5f6..." \
  https://www.maxafi.com/api/merchant/v1/customers

To get an API key, ask your MaxaFi admin or use the AI agent:

"Create a sandbox API key for my account with read access to transactions and customers"

Environments

Start with sandbox. Switch to production once tested.

Rate Limits

Every response includes rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47

Exceeding limits returns HTTP 429 with a Retry-After header.

Response Format

Success

{
  "success": true,
  "data": { ... },
  "meta": {
    "response_time_ms": 42,
    "api_version": "v1"
  }
}

Error

{
  "success": false,
  "error": "Customer not found"
}

Pagination

Paginated responses include:

"pagination": { "page": 1, "limit": 25, "total": 142, "pages": 6 }

Idempotency

Prevent duplicate operations on POST/PUT by passing an X-Idempotency-Key header:

curl -X POST \
  -H "X-Api-Key: mk_..." \
  -H "X-Idempotency-Key: order-12345" \
  -H "Content-Type: application/json" \
  -d '{"business_name": "Acme Corp"}' \
  https://www.maxafi.com/api/merchant/v1/customers

Same key twice = second request returns original result, no duplicate created.

Customers

curl -H "X-Api-Key: mk_..." \
  "https://www.maxafi.com/api/merchant/v1/customers?search=coffee&state=NY"

{
  "data": {
    "id": 456,
    "business_name": "Main Street Coffee",
    "email": "owner@mainst.coffee",
    "ssn": "***-**-5678",
    "bank_account": "****9012",
    "routing_number": "****4567"
  }
}

{
  "data": { "staging_id": 1001, "status": "promoted", "promoted_id": 456 },
  "message": "Customer created successfully"
}

{
  "error": "Validation failed",
  "detail": "[{\"field\":\"email\",\"error\":\"Invalid email format\"}]"
}

Transactions

curl -H "X-Api-Key: mk_..." \
  "https://www.maxafi.com/api/merchant/v1/transactions?date_from=2026-01-01&status=completed"

Products

Webhooks

Integrations

Staging Pipeline

All POST/PUT data goes through staging before reaching the live database. Review, retry, or reject records.

Audit Log

Usage & Rate Limits

Permission Scopes

Each API key has specific permissions. Requests outside your scope return 403 Forbidden.

Data Masking

Sensitive data is always protected. This is built into the API and cannot be overridden.

Shopify Integration

Connect with the AI agent — just say:

"I want to connect my Shopify store to sync customers and orders"

Or set up manually:

1. Create integration via POST /integrations with platform: "shopify"
2. Copy the returned webhook URL and secret
3. In Shopify Admin → Settings → Notifications → Webhooks
4. Add webhooks for: orders/create, orders/paid, customers/create, customers/update
5. Paste MaxaFi URL, select JSON format

QuickBooks Integration

"Connect my QuickBooks to sync invoices and customers"

1. Create integration with platform: "quickbooks"
2. Go to developer.intuit.com
3. Select your app → Webhooks
4. Add the MaxaFi webhook URL
5. Select entities: Customer, Invoice, Payment

Square Integration

"Connect my Square POS to sync payments and customers"

1. Create integration with platform: "square"
2. Go to developer.squareup.com
3. Your app → Webhooks → Add subscription
4. Select events: payment.completed, customer.created
5. Copy the signature key into your MaxaFi integration config

Field Mapping

External platform data is automatically translated. Example: Shopify → MaxaFi customer mapping:

View all mappings: GET /integrations/field-maps?platform=shopify

HTTP Status Codes

Quick Start

1. Get your API key

# In the AI chat, say:
"Create a sandbox API key with read access to transactions and customers"

# Save the key: mk_abc123...

2. List recent transactions

curl -H "X-Api-Key: mk_abc123..." \
  "https://www.maxafi.com/api/merchant/v1/transactions?limit=10"

3. Create a customer

curl -X POST \
  -H "X-Api-Key: mk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"business_name":"Main Street Coffee","email":"hello@mainst.coffee","state":"NY"}' \
  https://www.maxafi.com/api/merchant/v1/customers

4. Connect Shopify

# In the AI chat:
"Connect my Shopify store to sync orders and customers"

# The agent creates the integration and walks you through setup.

5. Check usage

curl -H "X-Api-Key: mk_abc123..." \
  "https://www.maxafi.com/api/merchant/v1/usage"