# Bernie Backend — New & Updated API Reference

**Base URL:** `http://localhost:8000/api`

All responses use JSON with a `success` boolean and `data` envelope where noted.

---

## Checkout (Updated)

### Preview checkout totals
`POST /api/checkout/preview`

Calculates full pricing with coupons, loyalty points, wallet, VIP, member pricing, quantity promotions, order-value promotions, and delivery fees.

**Body:**
```json
{
  "items": [
    { "product_id": 1, "product_name": "Organic Bananas", "price": 2.99, "quantity": 2 }
  ],
  "coupon_code": "WELCOME10",
  "points_to_redeem": 100,
  "wallet_amount": 5.00,
  "referral_code": "ABC12345",
  "postal_code": "10115"
}
```

**Response `data`:**
```json
{
  "items": [...],
  "subtotal": 5.98,
  "delivery_fee": 2.99,
  "service_fee": 0.06,
  "discount_amount": 0.60,
  "loyalty_discount": 10.00,
  "wallet_amount": 5.00,
  "points_used": 100,
  "vat_amount": 0.54,
  "total": 3.97,
  "free_shipping": false,
  "breakdown": {
    "order_promo_discount": 0,
    "coupon_discount": 0.60,
    "vip_discount": 0,
    "referral_discount": 0,
    "quantity_discount": 0
  }
}
```

### Create order (Updated)
`POST /api/orders`

Same optional fields as preview: `coupon_code`, `points_to_redeem`, `wallet_amount`, `referral_code`, `postal_code`, `customer_email`.

Checkout automatically applies all pricing rules and records coupon redemptions, loyalty spend, and wallet debit.

### Pay order (Updated)
`POST /api/orders/{id}/pay`

**Body:**
```json
{
  "payment_method": "stripe",
  "payment_token": "tok_visa_4242"
}
```

Triggers `OrderPaid` event → earns loyalty points, auto-upgrades VIP tier, sends email notification.

---

## Order Value Promotions (New)

`GET /api/order-value-promotions`

Returns active threshold-based promotions (free shipping, percentage off, fixed discount).

---

## Back In Stock Alerts (New)

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/back-in-stock` | List session subscriptions |
| POST | `/api/back-in-stock` | Subscribe `{ "product_id": 1, "email": "user@example.com" }` |
| DELETE | `/api/back-in-stock/{id}` | Unsubscribe |

**Scheduled command:** `php artisan back-in-stock:process`

---

## Product Sharing (New)

`GET /api/products/{slug}/share`

Returns share links for Facebook, X/Twitter, WhatsApp, Telegram, copy link, and Open Graph metadata.

---

## Quantity Promotions (New)

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/quantity-promotions` | List active promotions |
| GET | `/api/quantity-promotions/product/{productId}` | Promotion for product |

Applied automatically at checkout (Buy X Get Y, bundle, tier discount).

---

## SEO Meta (New)

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/seo/products/{slug}` | SEO meta for product page |
| GET | `/api/seo/categories/{slug}` | SEO meta for category page |

Returns: `meta_title`, `meta_description`, `canonical_url`, `og_*`, `schema_markup`.

---

## Wishlist (Updated)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/wishlist/{productId}/move-to-cart` | Move wishlist item to cart |

---

## Multi Currency (Updated)

`POST /api/currencies/convert`

**Body:** `{ "amount": 100, "from": "EUR", "to": "USD" }`

**Response:**
```json
{
  "success": true,
  "data": {
    "original_amount": 100,
    "converted_amount": 108.50,
    "from": "EUR",
    "to": "USD"
  }
}
```

---

## Customer Auth

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/auth/register` | Register + get Sanctum token |
| POST | `/api/auth/login` | Login + get Sanctum token |
| POST | `/api/auth/logout` | Logout (Bearer token required) |
| GET | `/api/auth/me` | Current customer (Bearer token required) |

---

## Integrated Features at Checkout

These existing modules are now **wired into checkout**:

| Feature | How it works |
|---------|-------------|
| First order discount | Coupon `is_first_order_only` validated by customer/session |
| Loyalty points | Redeem via `points_to_redeem`; earn on payment |
| Member pricing | Applied by tier (guest/registered/bronze–platinum) |
| Daily deals | Deal price overrides base price |
| VIP benefits | Auto discount + free shipping by tier |
| Coupons | Full validation incl. `max_discount_amount`, `free_shipping` |
| Referral | Redeem code at checkout for % discount |
| Wallet | Pay via `wallet_amount` field |
| Delivery zones | Fee from `postal_code` |
| Payment gateways | Stripe/PayPal/COD via `payment_method` + `payment_token` |

---

## Background Jobs / Commands

| Command | Schedule | Description |
|---------|----------|-------------|
| `abandoned-cart:send-reminders` | Every 30 min | Abandoned cart emails |
| `price-alerts:process` | Hourly | Price drop notifications |
| `back-in-stock:process` | Manual/cron | Back-in-stock notifications |
| `seo:generate-sitemap` | Manual | Generate `public/sitemap.xml` |

---

## Security Changes

- Product write APIs (`POST/PUT/DELETE /api/products`) require admin session (`auth:web`)
- Wallet recharge/refund removed from public API (wallet pay only at checkout)
- Notification send requires admin auth

---

## Existing APIs (unchanged)

All previous endpoints remain available:
- Products, Categories, Cart, Basket, Orders
- Coupons validate/claim, Rewards, Wishlist, Referrals
- VIP, Daily Deals, Reviews, Price Alerts
- Languages, Currencies, Delivery, Gateways
- Media, Sections, Save The Food, Weekly Specials

See main [README.md](README.md) for full storefront API documentation.