API Documentation

The wallmarkets API lets you programmatically manage deliveries, returns, products, and supermarket accounts. All endpoints return JSON and require authentication via API key.

Base URL

https://www.wallmarkets.store/api/v1

Response Format

Every response includes a status field and a data payload (or an error object on failure).

{
  "status": "success",
  "data": { ... }
}

Authenticate every request by including your API key as a Bearer token in the Authorization header.

Generating API Keys

Create keys in Account Settings > API Keys. Each key supports:

• Scopes: Restrict access per resource (e.g. deliveries:read, returns:write, products:read)
• Expiry: Optional expiration date — expired keys are rejected automatically
• Rotation: Rotate a key to get a new secret without changing the key ID

Authentication Header

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET \
  https://www.wallmarkets.store/api/v1/deliveries \
  -H 'Authorization: Bearer wm_live_abc123...'

Rate limits protect service stability. Limits vary by plan:

Limits by Plan

Rate Limit Headers

Every response includes these headers:

• X-RateLimit-Limit: Max requests per hour
• X-RateLimit-Remaining: Requests remaining in current window
• X-RateLimit-Reset: UTC epoch seconds when the window resets

Scope required: deliveries:read / deliveries:write

List Deliveries

Returns a paginated list of deliveries for the authenticated user.

# Query Parameters
?page=1&per_page=20&status=pending&date_from=2024-01-01&supermarket_id=5

Get a Delivery

{
  "id": 123,
  "supermarket_name": "E-mart",
  "subchain_name": "Sukhbaatar Branch",
  "products": [
    {"product_id": 8, "name": "Product A", "quantity": 10, "unit_price": 5000},
    {"product_id": 15, "name": "Product B", "quantity": 5, "unit_price": 12000}
  ],
  "total_value": 110000,
  "delivery_date": "2024-10-15",
  "status": "completed",
  "created_at": "2024-10-01T10:30:00Z"
}

Create a Delivery

{
  "supermarket_id": 5,
  "subchain_id": 12,
  "products": [
    {"product_id": 8, "quantity": 10},
    {"product_id": 15, "quantity": 5}
  ],
  "delivery_date": "2024-10-20",
  "notes": "Urgent delivery"
}

Update Delivery Status

{
  "status": "completed"
}

Valid transitions: pending → in_transit → completed, or pending → cancelled.

Scope required: returns:read / returns:write

List Returns

Returns a paginated list. Filter by delivery, supermarket, reason, or date range.

# Query Parameters
?page=1&per_page=20&reason=damaged&delivery_id=123

Create a Return

{
  "delivery_id": 123,
  "product_id": 8,
  "quantity": 3,
  "reason": "damaged",
  "return_date": "2024-10-18",
  "description": "Products arrived damaged during transit"
}

Get a Return

{
  "id": 42,
  "delivery_id": 123,
  "product_id": 8,
  "product_name": "Product A",
  "quantity": 3,
  "reason": "damaged",
  "description": "Products arrived damaged during transit",
  "return_date": "2024-10-18",
  "credit_amount": 15000,
  "created_at": "2024-10-18T09:15:00Z"
}

Scope required: products:read / products:write

List Products

Returns all products for the authenticated user. Filter by category or search by name.

# Query Parameters
?page=1&per_page=50&category=Dairy&search=milk

Get a Product

{
  "id": 8,
  "sequential_id": "P-0008",
  "name": "Whole Milk 1L",
  "weight": 1.05,
  "price": 5000,
  "category": "Dairy",
  "created_at": "2024-08-01T12:00:00Z"
}

Create a Product

{
  "name": "Whole Milk 1L",
  "weight": 1.05,
  "price": 5000,
  "category": "Dairy"
}

A unique sequential_id is assigned automatically.

Update a Product

{
  "price": 5500
}

Only the fields you include are updated. Historical delivery records are not affected.

Scope required: supermarkets:read / supermarkets:write

List Supermarkets

[
  {
    "id": 5,
    "name": "E-mart",
    "branches": [
      {"id": 12, "name": "Sukhbaatar Branch", "address": "..."},
      {"id": 13, "name": "Bayangol Branch", "address": "..."}
    ]
  }
]

Get a Supermarket

Returns the supermarket details including all branches, delivery windows, and contact info.

Create a Supermarket

{
  "name": "E-mart",
  "contact_email": "buyer@emart.mn",
  "branches": [
    {
      "name": "Sukhbaatar Branch",
      "address": "Peace Avenue 15, UB",
      "delivery_window": "08:00-12:00"
    }
  ]
}

Subscribe to webhooks to receive real-time HTTP callbacks when events occur. Webhooks are automatically deactivated after 10 consecutive delivery failures.

Event Types

Webhook Payload Example

{
  "event": "delivery.completed",
  "timestamp": "2024-10-15T14:30:00Z",
  "data": {
    "delivery_id": 123,
    "supermarket_name": "E-mart",
    "subchain_name": "Sukhbaatar Branch",
    "total_value": 110000,
    "completed_at": "2024-10-15T14:30:00Z"
  }
}

Retry Policy

Failed deliveries are retried with exponential backoff (1 min, 5 min, 30 min). After 10 consecutive failures, the subscription is automatically deactivated. Re-enable it from your webhook settings.

HTTP Status Codes

Error Response Format

{
  "status": "error",
  "error": {
    "code": "validation_error",
    "message": "delivery_date must be in the future",
    "field": "delivery_date"
  }
}