Store API Endpoints Documentation¶

This document describes all custom store-facing API endpoints for the AzharStore Medusa v2 backend.

Base URL¶

http://localhost:9000/store

Endpoints¶

GET /store/advertisements¶

Returns active advertisements sorted by display_order.

Request

GET /store/advertisements

Response (200 OK)

{
  "advertisements": [
    {
      "id": "string",
      "title": "string | null",
      "image_url": "string",
      "link_url": "string | null",
      "location": "string",
      "display_order": number,
      "is_active": boolean,
      "created_at": "string (ISO 8601)"
    }
  ]
}

Error Response (500 Internal Server Error)

{
  "error": "Failed to fetch advertisements",
  "message": "string"
}

Example

curl http://localhost:9000/store/advertisements

GET /store/settings¶

Returns all application settings as a typed flat object.

Request

GET /store/settings

Response (200 OK)

{
  "free_delivery_threshold": number,
  "pickup_message": "string | null",
  "ceo_whatsapp": "string | null"
}

Field Descriptions - free_delivery_threshold: Minimum order amount in BHD (cents) for free delivery - pickup_message: Message displayed for pickup orders - ceo_whatsapp: CEO's WhatsApp number for customer support

Error Response (500 Internal Server Error)

{
  "error": "Failed to fetch settings",
  "message": "string"
}

Example

curl http://localhost:9000/store/settings

GET /store/translations¶

Returns i18next-compatible translation bundle for Arabic locale.

Request

GET /store/translations

Response (200 OK)

{
  "ar": {
    "translation": {
      "welcome": "مرحبا",
      "cart": "السلة",
      "checkout": "إتمام الطلب"
    }
  }
}

Format The response follows the i18next resource format: - Top-level key is language code (ar) - Nested translation object contains key-value pairs - Can be directly passed to i18next init

Error Response (500 Internal Server Error)

{
  "error": "Failed to fetch translations",
  "message": "string"
}

Example

curl http://localhost:9000/store/translations

POST /store/orders¶

Creates a new order using the checkout workflow. Validates stock, creates cart, adds items, sets address, adds shipping, creates payment, and completes the order.

Request

POST /store/orders
Content-Type: application/json

Request Body

{
  "region_id": "string",
  "phone_number": "string",
  "customer": {
    "name": "string",
    "phone_number": "string",
    "town": "string",
    "address_road": "string",
    "address_home": "string",
    "address_block": "string"
  },
  "items": [
    {
      "variant_id": "string",
      "quantity": number
    }
  ],
  "delivery_area_id": "string",
  "shipping_method": "delivery | pick_up"
}

Field Descriptions - region_id: Medusa region ID - phone_number: Customer phone number (used for synthetic email generation) - customer.name: Customer full name (split into first_name/last_name) - customer.phone_number: Customer phone number - customer.town: City/town - customer.address_road: Street address line 1 - customer.address_home: Street address line 2 - customer.address_block: Block/area code (mapped to postal_code) - items: Array of cart items - items[].variant_id: Product variant ID - items[].quantity: Quantity (must be >= 1) - delivery_area_id: Shipping option ID for delivery - shipping_method: Either "delivery" or "pick_up"

Response (201 Created)

{
  "order": {
    "id": "string",
    "email": "string",
    "status": "string",
    "items": [...],
    "shipping_address": {...},
    "billing_address": {...},
    "total": number,
    "created_at": "string (ISO 8601)"
  }
}

Error Responses

400 Bad Request - Missing Fields

{
  "error": "Missing required fields",
  "required": ["region_id", "phone_number", "customer", "items", "delivery_area_id", "shipping_method"]
}

400 Bad Request - Invalid Items

{
  "error": "Items must be a non-empty array"
}

400 Bad Request - Invalid Item

{
  "error": "Each item must have variant_id and a valid quantity"
}

400 Bad Request - Insufficient Stock

{
  "error": "INSUFFICIENT_STOCK",
  "message": {
    "code": "INSUFFICIENT_STOCK",
    "variant_id": "string",
    "requested": number,
    "available": number
  }
}

400 Bad Request - Order Creation Failed

{
  "error": "ORDER_CREATION_FAILED",
  "message": "string"
}

Example

href="#__codelineno-21-1">curl -X POST http://localhost:9000/store/orders \ -H "Content-Type: application/json" \ -d '{ "region_id": "reg_123", "phone_number": "+97312345678", "customer": { "name": "John Doe", "phone_number": "+97312345678", "town": "Manama", "address_road": "Main Street", "address_home": "Building 5", "address_block": "321" }, "items": [ { "variant_id": "variant_123", "quantity": 2 } ], "delivery_area_id": "ship_123", "shipping_method": "delivery" }'

Error Handling¶

All endpoints follow consistent error handling:

200 OK: Successful request
201 Created: Successful creation (POST)
204 No Content: Successful deletion
400 Bad Request: Invalid input or validation error
500 Internal Server Error: Server-side error

Error responses always include: - error: Error code or type - message: Human-readable error message

Authentication¶

Store endpoints do not require authentication. They are public-facing for customers.

Rate Limiting¶

No rate limiting is currently implemented. Consider adding rate limiting for order creation in production.

CORS¶

Store endpoints are configured to accept requests from origins specified in the STORE_CORS environment variable.