API Reference

API Overview

LocallyGrown.net provides REST API endpoints for market administration, product management, and order processing.

Base URL

Authentication

The API uses session-based authentication. Users must be logged in to access most endpoints.

• Session Management: HTTP-only cookies for security
• CSRF Protection: Built-in CSRF token validation
• Role-based Access: Endpoints restricted by user permissions
• Market Context: API calls are scoped to the user's market

Response Format

All API responses use JSON format with consistent structure:

{
  "success": true,
  "data": ...,
  "message": "Operation completed successfully"
}

Error Handling

Errors return appropriate HTTP status codes with detailed messages:

{
  "success": false,
  "error": "Error description",
  "code": "ERROR_CODE",
  "details": ...
}

Market Management

Endpoints for managing market settings and configuration.

Get Market Information

Retrieve market details including settings, statistics, and configuration.

Response

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Springfield Farmers Market",
    "subdomain": "springfield",
    "locale": "Springfield, IL",
    "zipCode": "62701",
    "settings": {
      "allowConventional": true,
      "requiresMembership": false,
      "enablePickupLocations": true
    },
    "statistics": {
      "totalUsers": 245,
      "activeProducts": 89,
      "totalOrders": 1523
    }
  }
}

Update Market Settings

Update market configuration. Requires admin permissions.

Request Body

{
  "name": "Springfield Farmers Market",
  "slogan": "Fresh from our farms to your table",
  "allowConventional": true,
  "defaultPercentage": "10.00",
  "requiresMembership": false
}

Product Management

Endpoints for managing products, inventory, and availability.

List Products

Get all products for the current market with optional filtering.

Query Parameters

• active: Filter by active status (true/false)
• grower_id: Filter by grower
• category_id: Filter by category
• wholesale: Include wholesale products (true/false)

Create Product

Create a new product. Requires grower permissions.

Request Body

{
  "name": "Organic Cherry Tomatoes",
  "description": "Sweet, juicy cherry tomatoes grown organically",
  "price": "4.50",
  "unit": "pint",
  "quantity": 20,
  "categoryId": 5,
  "active": true,
  "allowsWholesale": false,
  "wholesalePrice": "3.50"
}

Update Product Availability

Toggle product availability on/off.

Upload Product Image

Upload product image. Supports multipart/form-data.

Order Management

Endpoints for processing orders, payments, and fulfillment.

List Orders

Get orders for the current market with filtering options.

Query Parameters

• start_date: Filter orders from date (YYYY-MM-DD)
• end_date: Filter orders to date (YYYY-MM-DD)
• status: Filter by order status
• user_id: Filter by customer
• grower_id: Filter orders containing grower's products

Get Order Details

Retrieve detailed order information including items and payments.

Response

{
  "success": true,
  "data": {
    "id": 1523,
    "userId": 89,
    "total": "45.75",
    "status": "complete",
    "createdAt": "2024-03-15T10:30:00Z",
    "pickupLocationId": 2,
    "items": [
      {
        "id": 3021,
        "productId": 156,
        "productName": "Organic Cherry Tomatoes",
        "growerName": "Smith Family Farm",
        "quantity": 2,
        "price": "4.50",
        "total": "9.00"
      }
    ],
    "payments": [
      {
        "method": "stripe",
        "amount": "45.75",
        "status": "completed"
      }
    ]
  }
}

Update Order Status

Mark order as complete or incomplete.

Process Prepayment

Process payment for an order using Stripe.

User Management

Endpoints for managing users, permissions, and account information.

List Users

Get users for the current market. Requires admin permissions.

Query Parameters

• role: Filter by user role (admin, grower, customer, volunteer)
• active: Filter by active status
• search: Search by name or email

Get User Details

Retrieve user information and statistics.

Update User

Update user information. Admin can update any user, users can update themselves.

Basket and Checkout

Endpoints for shopping basket management and checkout process.

Add to Basket

Add item to customer's shopping basket.

Request Body

{
  "productId": 156,
  "quantity": 2,
  "comments": "Extra ripe please"
}

Get Basket Contents

Retrieve current basket contents and totals.

Checkout

Convert basket to order and process payment.

Authentication Endpoints

Session management and user authentication.

Sign In

Authenticate user and create session.

Request Body

{
  "username": "[email protected]",
  "password": "securepassword"
}

Sign Out

Destroy user session.

Register

Create new user account.

Rate Limiting and Quotas

API usage is subject to rate limiting to ensure fair usage and system stability.

Rate Limits

• General API: 100 requests per minute per IP
• Authentication: 10 requests per minute per IP
• Image Uploads: 20 requests per minute per user
• Order Processing: 30 requests per minute per user

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Handling Rate Limits

• 429 Status Code: Rate limit exceeded
• Retry-After Header: Seconds to wait before retrying
• Exponential Backoff: Recommended retry strategy
• Caching: Cache responses when possible

Webhooks

LocallyGrown.net can send HTTP webhooks for real-time event notifications.

Supported Events

• order.created: New order placed
• order.completed: Order marked as complete
• product.updated: Product information changed
• user.registered: New user account created
• payment.completed: Payment successfully processed

Webhook Configuration

Contact support to configure webhook endpoints for your market.

Payload Example

{
  "event": "order.created",
  "timestamp": "2024-03-15T10:30:00Z",
  "marketId": 1,
  "data": {
    "orderId": 1523,
    "userId": 89,
    "total": "45.75",
    "itemCount": 3
  }
}

Error Codes

Common API error codes and their meanings.