← All Documentation

API Reference

The Mercentia REST API lets your app read and write merchant store data. All endpoints are available at https://gateway.mercentia.com/api/v1.

Base URL: https://gateway.mercentia.com/api/v1
Authentication: Authorization: Bearer {access_token}
Store Context: X-Store-Id: {store_id}
Content Type: application/json
Rate Limit: 1,000 requests/minute (Community), 10,000 (Partner), Unlimited (Elite)

Resources

Products

Scope required: read_products (read), write_products (write)

MethodEndpointDescription
GET/productsList all products (paginated)
GET/products/:idGet a single product with variants and images
POST/productsCreate a new product
PUT/products/:idUpdate a product
DELETE/products/:idDelete a product
GET/products/:id/variantsList product variants
POST/products/:id/variantsAdd a variant
GET/collectionsList collections
POST/collectionsCreate a collection

Product Object

{
  "id": "uuid",
  "name": "Premium Cotton T-Shirt",
  "slug": "premium-cotton-t-shirt",
  "description": "Organic cotton, ethically made",
  "status": "active",
  "price": 29.99,
  "compareAtPrice": 39.99,
  "currency": "USD",
  "sku": "TSH-001",
  "barcode": "1234567890",
  "weight": 200,
  "weightUnit": "g",
  "trackInventory": true,
  "inventoryQuantity": 150,
  "category": "Apparel",
  "tags": ["cotton", "organic", "t-shirt"],
  "images": [{ "url": "https://...", "alt": "Front view", "position": 0 }],
  "variants": [...],
  "metadata": {},
  "createdAt": "2026-04-21T10:00:00Z",
  "updatedAt": "2026-04-21T10:00:00Z"
}

Orders

Scope required: read_orders (read), write_orders (write)

MethodEndpointDescription
GET/ordersList orders (filterable by status, date)
GET/orders/:idGet order detail with items, shipping, payment
PUT/orders/:idUpdate order (notes, tags, status)
POST/orders/:id/fulfillCreate a fulfillment with tracking
POST/orders/:id/refundIssue a refund (full or partial)
POST/draft-ordersCreate a draft order

Order Object

{
  "id": "uuid",
  "orderNumber": "SF-1042",
  "status": "paid",
  "fulfillmentStatus": "unfulfilled",
  "customerEmail": "customer@example.com",
  "subtotal": 59.98,
  "tax": 5.40,
  "shipping": 4.99,
  "total": 70.37,
  "currency": "USD",
  "items": [
    {
      "productId": "uuid",
      "variantId": "uuid",
      "name": "Premium Cotton T-Shirt - Blue / M",
      "quantity": 2,
      "price": 29.99
    }
  ],
  "shippingAddress": { "line1": "...", "city": "...", "country": "US" },
  "paymentMethod": "card",
  "createdAt": "2026-04-21T10:00:00Z"
}

Customers

Scope required: read_customers (read), write_customers (write)

MethodEndpointDescription
GET/customersList customers
GET/customers/:idGet customer with addresses and order history
POST/customersCreate a customer
PUT/customers/:idUpdate customer profile

Inventory

Scope required: read_inventory (read), write_inventory (write)

MethodEndpointDescription
GET/products/:id/inventoryGet stock levels for a product
PUT/products/:id/inventoryAdjust stock level (set or increment/decrement)

Shipping

Scope required: read_shipping (read), write_shipping (write)

MethodEndpointDescription
GET/shipping/zonesList shipping zones and rates
GET/shipping/carriersList configured carriers
POST/shipping/labelsGenerate a shipping label
POST/shipping/ratesCalculate shipping rates for a cart

Discounts

Scope required: read_discounts (read), write_discounts (write)

MethodEndpointDescription
GET/discountsList discount codes
POST/discountsCreate a discount code
PUT/discounts/:idUpdate a discount
DELETE/discounts/:idDelete a discount

Content

Scope required: read_content (read), write_content (write)

MethodEndpointDescription
GET/content/pagesList pages
POST/content/pagesCreate a page
GET/content/blogList blog posts
POST/content/blogCreate a blog post

Analytics

Scope required: read_analytics

MethodEndpointDescription
GET/analytics/overviewSales, orders, AOV, conversion rate summary
GET/analytics/salesSales data with date range and granularity
GET/analytics/top-productsBest-selling products

Store Settings

Scope required: read_store_settings

MethodEndpointDescription
GET/stores/currentGet store name, domain, currency, language
GET/stores/settingsFull store configuration

Pagination

List endpoints support cursor-based pagination:

GET /products?limit=25&cursor=eyJpZCI6Inh4eCJ9

Response:
{
  "data": [...],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJpZCI6Inl5eSJ9",
    "total": 150
  }
}
ParameterDefaultMaxDescription
limit25250Number of records per page
cursor--Opaque cursor from previous response
sortcreated_at-Sort field (varies by resource)
orderdesc-asc or desc

Error Responses

All errors follow a consistent format:

{
  "error": "Descriptive error message",
  "code": "VALIDATION_ERROR",
  "details": [
    { "field": "name", "message": "Name is required" }
  ]
}
StatusMeaning
200Success
201Created
400Bad request — check the error details
401Unauthorized — invalid or expired token
403Forbidden — insufficient scope or permission
404Not found
409Conflict — resource already exists
422Validation error — check the details array
429Rate limited — retry after Retry-After header
500Server error — contact support if persistent

Rate Limits

TierRequests / MinuteBurst
Community1,00050 concurrent
Partner10,000200 concurrent
EliteUnlimited500 concurrent

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994
X-RateLimit-Reset: 1713700000
Retry-After: 30  (only on 429 responses)

API Versioning

The current API version is v1. Breaking changes will be introduced in new versions (v2, v3, etc.) and the previous version will remain supported for at least 12 months with a deprecation notice.

Non-breaking changes (new fields, new endpoints) are added to the current version without a version bump. Your app should handle unknown fields gracefully.