# Merchant API Documentation **Version:** v1 **Base URL:** `/api/v1/merchant` **Last Updated:** November 10, 2026 (v1.7 - Merchant marketing API coverage) --- ## Table of Contents 1. [Overview](#overview) 2. [Authentication](#authentication) 3. [Base URL & Environment](#base-url--environment) 4. [Standard Response Format](#standard-response-format) 5. [Error Handling](#error-handling) 6. [Rate Limiting](#rate-limiting) 7. [Endpoints](#endpoints) - [Authentication Endpoints](#authentication-endpoints) - [Profile Management Endpoints](#profile-management-endpoints) - [Store Branding Endpoints](#store-branding-endpoints) - [Statistics Endpoints](#statistics-endpoints) - [Product Management Endpoints](#product-management-endpoints) - [Product Collections Endpoints](#product-collections-endpoints) - [Marketing Management Endpoints](#marketing-management-endpoints) - [Product Variants Endpoints](#product-variants-endpoints) - [Product Images Endpoints](#product-images-endpoints) - [Order Management Endpoints](#order-management-endpoints) - [Shipment Management Endpoints](#shipment-management-endpoints) - [Visa Services Endpoints](#visa-services-endpoints) - [Airticket Services Endpoints](#airticket-services-endpoints) - [Reference Data Endpoints](#reference-data-endpoints) 8. [Merchant Account States](#merchant-account-states) 9. [Code Examples](#code-examples) --- ## Overview The Merchant API provides authentication and role-scoped store management for e-commerce merchants. This API uses "Merchant" terminology for frontend developers while internally mapping to the Vendor model. Most endpoints return a JSON envelope; file and specialized endpoints may return endpoint-specific payloads. ### Features - ✅ Merchant registration with store setup - ✅ Login with device tracking - ✅ Token-based authentication (Sanctum) - ✅ Password reset functionality - ✅ Store profile management - ✅ Logo and banner upload - ✅ Business hours configuration - ✅ Store statistics and analytics - ✅ Account verification workflow - ✅ Role-based access control - ✅ Visa application operations via dedicated merchant visa endpoints - ✅ Airticket catalog and booking operations via dedicated merchant airticket endpoints ## Merchant Types Merchant accounts are now segmented by `merchant_types`. Current values: - `goods` - `visa` - `airticket` Access rules: - merchants may have one or more merchant types at the same time - merchants with `goods` can access goods management endpoints such as `statistics`, `orders`, `products`, and `collections` - merchants with `visa` can access visa management endpoints under `/api/v1/merchant/visa` - merchants with `airticket` can access airticket management endpoints under `/api/v1/merchant/airticket` - shared endpoints like auth and profile remain available to active merchants regardless of merchant type For visa operations, see [`documentation/VISA_MERCHANT_API.md`](./VISA_MERCHANT_API.md). --- ## Authentication ### Authentication Methods The API uses Laravel Sanctum for authentication: #### 1. Token-Based Authentication Use Bearer token authentication for mobile apps and third-party clients: ```http Authorization: Bearer {access_token} ``` #### 2. SPA Cookie Authentication For first-party SPAs on the same domain, Sanctum issues authentication cookies instead of a bearer token. ### Authentication Flow ``` 1. Register with `name`, `email`, `password`, `store_name`, one or more `merchant_types`, and accepted terms 2. Registration currently creates an active merchant account and returns its account status 3. Login → Receive token 4. Include token in Authorization header for protected routes 5. Token can be refreshed using the authenticated refresh endpoint 6. Logout revokes the current token Both registration and login require a confirmed password at registration; login accepts optional `device_name`. Login is limited to five failed attempts per email and IP. Merchant registrations currently auto-activate and auto-verify in all environments. ``` ### Goods Phase 1 Session Contract - `POST /refresh` is an authenticated endpoint that expects the current bearer token in the `Authorization` header plus an optional `device_name` body field. The contract does **not** require or accept a separate `refresh_token` payload. - Goods web clients should keep token access behind one shared auth/API abstraction instead of reading access tokens directly in product, order, collection, or image-management components. - Merchant registrations currently auto-activate and auto-verify in all environments. This should later be switched to pending and unverified in production. - `GET /orders/{id}/invoice` is the supported merchant-side invoice payload for print/export and customer-support follow-up workflows. ### Marketing Campaign Ownership Contract - Merchant marketing endpoints under `/marketing/*` are scoped to the authenticated `goods` merchant. - Campaign create/update requests are always treated as `merchant` owned. Clients must not send `campaign_owner_type`, `owner_type`, `vendor_id`, `created_by`, `admin_notes`, or manual `status` overrides. - Merchant-created campaigns are storefront promotions only. They can appear in that merchant's shop/deals surfaces and direct campaign detail links, but they must not be promised as customer home/global placements. - Responses may include read-only `campaign_owner_type = merchant` for debugging and contract verification. - Future platform/admin campaigns and merchant join workflows are out of scope for merchant self-service APIs until the admin marketing module is implemented. --- ## Base URL & Environment ### Development ``` http://localhost:8000/api/v1/merchant ``` ### Production ``` https://ecom-backend-api.dmi.community/api/v1/merchant ``` ### Content Type All requests must include: ```http Content-Type: application/json Accept: application/json ``` --- ## Standard Response Format ### Success Response ```json { "success": true, "message": "Operation successful", "data": { // Response data here } } ``` ### Created Response (201) ```json { "success": true, "message": "Resource created successfully", "data": { // Created resource data } } ``` --- ## Error Handling ### Error Response Format ```json { "success": false, "message": "Description of the error", "errors": { "field_name": ["Error message for this field."] } } ``` ### HTTP Status Codes | Code | Description | |------|-------------| | 200 | OK - Request successful | | 201 | Created - Resource created successfully | | 400 | Bad Request - Invalid request format | | 401 | Unauthorized - Authentication required or failed | | 403 | Forbidden - Access denied (not a merchant or inactive account) | | 404 | Not Found - Resource not found | | 422 | Unprocessable Entity - Validation failed | | 429 | Too Many Requests - Rate limit exceeded | | 500 | Internal Server Error - Server error | ### Common Error Responses #### Unauthenticated (401) ```json { "success": false, "message": "Unauthenticated." } ``` #### Access Denied (403) ```json { "success": false, "message": "Access denied. Merchant access required." } ``` #### Merchant Not Active (403) ```json { "success": false, "message": "Your merchant account is not active. Please contact support." } ``` #### Validation Error (422) ```json { "success": false, "message": "Validation failed", "errors": { "email": ["This email address is already registered."], "store_name": ["Store name is required."] } } ``` --- ## Rate Limiting ### Rate Limiting Goods routes use route-level throttles to protect high-traffic operational endpoints: | Endpoint Type | Limit | |---------------|-------| | Merchant auth entrypoints (`register`, `login`) | 10 requests per minute | | Password reset entrypoints (`forgot-password`, `reset-password`) | 5 requests per minute | | Product, order, collection, and profile reads | 60 requests per minute | | Search-heavy reads and many standard writes | 30 requests per minute | | High-sensitivity Goods writes | 10 requests per minute | | File/image uploads | Route-specific, typically 20-30 requests per minute | Examples: - Goods product image and variant image uploads are protected by route middleware and standard auth handling, and are intentionally tighter than normal reads because each request can include up to 10 images at 5 MB each. - Destructive or high-risk Goods mutations such as some reorder/remove operations use tighter throttles than simple reads. - Clients should treat `401`, `403`, and `429` as normal operational responses and surface clear retry or re-login guidance instead of assuming background automation. When rate limited, a `429 Too Many Requests` response is returned: ```json { "success": false, "message": "Too many login attempts. Please try again in 45 seconds." } ``` --- ## Merchant Account States ### Merchant Account States | Status | Description | API Access | |--------|-------------|------------| | `pending` | Awaiting approval | Limited (auth + me endpoints only) | | `active` | Approved and active | Full access | | `suspended` | Temporarily suspended | No access (403) | | `rejected` | Application rejected | No access (403) | --- ## Code Examples ### JavaScript/Fetch ```javascript // Login async function login(email, password) { const response = await fetch('https://ecom-backend-api.dmi.community/api/v1/merchant/login', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' }, body: JSON.stringify({ email, password }) }); return response.json(); } // Get Profile with Token async function getProfile(token) { const response = await fetch('https://ecom-backend-api.dmi.community/api/v1/merchant/profile', { method: 'GET', headers: { 'Authorization': `Bearer ${token}`, 'Accept': 'application/json' } }); return response.json(); } // Update Profile async function updateProfile(token, data) { const response = await fetch('https://ecom-backend-api.dmi.community/api/v1/merchant/profile', { method: 'PUT', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json', 'Accept': 'application/json' }, body: JSON.stringify(data) }); return response.json(); } // Upload Logo async function uploadLogo(token, file) { const formData = new FormData(); formData.append('logo', file); const response = await fetch('https://ecom-backend-api.dmi.community/api/v1/merchant/profile/branding', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Accept': 'application/json' }, body: formData }); return response.json(); } ``` ### cURL - Full Authentication Flow ```bash # 1. Register curl -X POST "https://ecom-backend-api.dmi.community/api/v1/merchant/register" \ -H "Content-Type: application/json" \ -d '{ "name": "John Doe", "email": "merchant@example.com", "address_line_1": "123 Tech Street", "address_line_2": "Suite 456", "city": "San Francisco", "state": "California", "postal_code": "94102", "country": "United States", "website_url": "https://johnelectronics.com", "facebook_url": "https://facebook.com/johnelectronics", "instagram_url": "https://instagram.com/johnelectronics", "twitter_url": "https://twitter.com/johnelectronics", "password": "SecurePass123!", "password_confirmation": "SecurePass123!", "store_name": "John Electronics", "terms_accepted": true }' # 2. Login curl -X POST "https://ecom-backend-api.dmi.community/api/v1/merchant/login" \ -H "Content-Type: application/json" \ -d '{ "email": "merchant@example.com", "address_line_1": "123 Tech Street", "address_line_2": "Suite 456", "city": "San Francisco", "state": "California", "postal_code": "94102", "country": "United States", "website_url": "https://johnelectronics.com", "facebook_url": "https://facebook.com/johnelectronics", "instagram_url": "https://instagram.com/johnelectronics", "twitter_url": "https://twitter.com/johnelectronics", "password": "SecurePass123!" }' # 3. Use Token for Authenticated Requests curl -X GET "https://ecom-backend-api.dmi.community/api/v1/merchant/profile" \ -H "Authorization: Bearer 1|abc123xyz..." # 4. Update Profile (with settings) curl -X PUT "https://ecom-backend-api.dmi.community/api/v1/merchant/profile" \ -H "Authorization: Bearer 1|abc123xyz..." \ -H "Content-Type: application/json" \ -d '{ "store_name": "John Premium Electronics", "description": "Updated store description", "settings": [ {"key": "notification_email", "value": "alerts@store.com"}, {"key": "currency", "value": "USD"} ] }' # 5. Logout curl -X POST "https://ecom-backend-api.dmi.community/api/v1/merchant/logout" \ -H "Authorization: Bearer 1|abc123xyz..." ``` --- ## Notes for Frontend Developers ### Notes for Frontend Developers 1. **Token Storage:** Store the `access_token` securely (e.g., secure storage on mobile, httpOnly cookies for web). 2. **Token Format:** Always include the token in the `Authorization` header as `Bearer {token}`. 3. **Merchant vs Vendor:** The API uses "Merchant" terminology, but internally maps to the "Vendor" model. Both terms refer to the same entity. 4. **Account Approval:** New merchant registrations start with `pending` status and require admin approval before accessing profile and store management features. 5. **Email Verification:** While not blocking, email verification is recommended for full platform features. 6. **File Uploads:** Use `multipart/form-data` for file uploads (logo, banner). Do not include `Content-Type: application/json` header for these requests. 7. **Business Hours:** When updating business hours, send the complete array of all days. Partial updates are not supported. --- ## Endpoints All endpoints are prefixed with `/api/v1/merchant`. --- ## Authentication Endpoints ### Register Create a new merchant account. **Endpoint:** `POST /register` **Authentication:** None (Guest) #### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Merchant owner's full name (max 255 characters) | | email | string | Yes | Unique email address | | password | string | Yes | Password (min 8 characters) | | password_confirmation | string | Yes | Password confirmation | | store_name | string | Yes | Store/business name (max 255 characters) | | phone | string | No | Contact phone number (max 20 characters) | | description | string | No | Store description (max 1000 characters) | | merchant_types | array | Yes | One or more merchant types. Allowed: `goods`, `visa`, `airticket` | | terms_accepted | boolean | Yes | Must be `true` | #### Example Request ```bash curl -X POST "https://ecom-backend-api.dmi.community/api/v1/merchant/register" \ -H "Content-Type: application/json" \ -d '{ "name": "John Doe", "email": "merchant@example.com", "address_line_1": "123 Tech Street", "address_line_2": "Suite 456", "city": "San Francisco", "state": "California", "postal_code": "94102", "country": "United States", "website_url": "https://johnelectronics.com", "facebook_url": "https://facebook.com/johnelectronics", "instagram_url": "https://instagram.com/johnelectronics", "twitter_url": "https://twitter.com/johnelectronics", "password": "SecurePass123!", "password_confirmation": "SecurePass123!", "store_name": "John Electronics", "phone": "+1234567890", "description": "Quality electronics and gadgets", "merchant_types": ["goods", "visa"], "terms_accepted": true }' ``` #### Success Response (201 Created) ```json { "success": true, "message": "Merchant registration successful.", "data": { "user": { "id": 1, "name": "John Doe", "email": "merchant@example.com", "address_line_1": "123 Tech Street", "address_line_2": "Suite 456", "city": "San Francisco", "state": "California", "postal_code": "94102", "country": "United States", "website_url": "https://johnelectronics.com", "facebook_url": "https://facebook.com/johnelectronics", "instagram_url": "https://instagram.com/johnelectronics", "twitter_url": "https://twitter.com/johnelectronics", "profile_photo_url": null }, "merchant": { "id": 1, "store_name": "John Electronics", "slug": "john-electronics-abc123", "merchant_types": ["goods", "visa"], "status": "pending" }, "token": { "access_token": "1|abc123...", "token_type": "Bearer" }, "email_verification_required": true } } ``` #### Validation Errors (422) ```json { "success": false, "message": "Validation failed", "errors": { "email": ["This email address is already registered."], "store_name": ["Store name is required."], "merchant_types": ["Please select at least one merchant type."], "terms_accepted": ["You must accept the terms and conditions."] } } ``` --- ### Login Authenticate a merchant and receive an access token. **Endpoint:** `POST /login` **Authentication:** None (Guest) #### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | email | string | Yes | Registered email address | | password | string | Yes | Account password | | device_name | string | No | Device identifier (default: "API Client") | #### Example Request ```bash curl -X POST "https://ecom-backend-api.dmi.community/api/v1/merchant/login" \ -H "Content-Type: application/json" \ -d '{ "email": "merchant@example.com", "address_line_1": "123 Tech Street", "address_line_2": "Suite 456", "city": "San Francisco", "state": "California", "postal_code": "94102", "country": "United States", "website_url": "https://johnelectronics.com", "facebook_url": "https://facebook.com/johnelectronics", "instagram_url": "https://instagram.com/johnelectronics", "twitter_url": "https://twitter.com/johnelectronics", "password": "SecurePass123!", "device_name": "iPhone 14 Pro" }' ``` #### Success Response (200 OK) ```json { "success": true, "message": "Login successful", "data": { "user": { "id": 1, "name": "John Doe", "email": "merchant@example.com", "address_line_1": "123 Tech Street", "address_line_2": "Suite 456", "city": "San Francisco", "state": "California", "postal_code": "94102", "country": "United States", "website_url": "https://johnelectronics.com", "facebook_url": "https://facebook.com/johnelectronics", "instagram_url": "https://instagram.com/johnelectronics", "twitter_url": "https://twitter.com/johnelectronics", "profile_photo_url": "https://example.com/storage/avatars/user-1.jpg" }, "merchant": { "id": 1, "store_name": "John Electronics", "slug": "john-electronics-abc123", "status": "active", "is_verified": true, "is_active": true }, "token": { "access_token": "2|xyz789...", "token_type": "Bearer" }, "email_verified": true } } ``` #### Error Responses **Invalid Credentials (422)** ```json { "success": false, "message": "Validation failed", "errors": { "email": ["These credentials do not match our records."] } } ``` **Not a Merchant (403)** ```json { "success": false, "message": "Access denied. Merchant access required." } ``` --- ### Logout Revoke the current access token. **Endpoint:** `POST /logout` **Authentication:** Required (Bearer Token) #### Request Headers ```http Authorization: Bearer {access_token} ``` #### Example Request ```bash curl -X POST "https://ecom-backend-api.dmi.community/api/v1/merchant/logout" \ -H "Authorization: Bearer {access_token}" ``` #### Success Response (200 OK) ```json { "success": true, "message": "Logged out successfully" } ``` --- ### Forgot Password Request a password reset link. **Endpoint:** `POST /forgot-password` **Authentication:** None (Guest) #### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | email | string | Yes | Registered email address | #### Example Request ```bash curl -X POST "https://ecom-backend-api.dmi.community/api/v1/merchant/forgot-password" \ -H "Content-Type: application/json" \ -d '{ "email": "merchant@example.com" }' ``` #### Success Response (200 OK) ```json { "success": true, "message": "Password reset link has been sent to your email address." } ``` --- ### Reset Password Reset password using the token received via email. **Endpoint:** `POST /reset-password` **Authentication:** None (Guest) #### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | token | string | Yes | Reset token from email | | email | string | Yes | Registered email address | | password | string | Yes | New password | | password_confirmation | string | Yes | New password confirmation | #### Example Request ```bash curl -X POST "https://ecom-backend-api.dmi.community/api/v1/merchant/reset-password" \ -H "Content-Type: application/json" \ -d '{ "token": "abc123...", "email": "merchant@example.com", "address_line_1": "123 Tech Street", "address_line_2": "Suite 456", "city": "San Francisco", "state": "California", "postal_code": "94102", "country": "United States", "website_url": "https://johnelectronics.com", "facebook_url": "https://facebook.com/johnelectronics", "instagram_url": "https://instagram.com/johnelectronics", "twitter_url": "https://twitter.com/johnelectronics", "password": "NewSecurePass456!", "password_confirmation": "NewSecurePass456!" }' ``` #### Success Response (200 OK) ```json { "success": true, "message": "Password has been reset successfully." } ``` --- ### Refresh Token Revoke current token and issue a new one. **Endpoint:** `POST /refresh` **Authentication:** Required (Bearer Token) #### Request Headers ```http Authorization: Bearer {access_token} ``` #### Request Body (Optional) | Field | Type | Required | Description | |-------|------|----------|-------------| | device_name | string | No | New device identifier | #### Example Request ```bash curl -X POST "https://ecom-backend-api.dmi.community/api/v1/merchant/refresh" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -d '{ "device_name": "New Device" }' ``` #### Success Response (200 OK) ```json { "success": true, "message": "Token refreshed successfully", "data": { "token": { "access_token": "3|newtoken...", "token_type": "Bearer" } } } ``` --- ### Get Current User (Me) Retrieve the authenticated merchant's information. **Endpoint:** `GET /me` **Authentication:** Required (Bearer Token) #### Request Headers ```http Authorization: Bearer {access_token} ``` #### Example Request ```bash curl -X GET "https://ecom-backend-api.dmi.community/api/v1/merchant/me" \ -H "Authorization: Bearer {access_token}" ``` #### Success Response (200 OK) ```json { "success": true, "message": "Merchant information retrieved successfully", "data": { "user": { "id": 1, "name": "John Doe", "email": "merchant@example.com", "address_line_1": "123 Tech Street", "address_line_2": "Suite 456", "city": "San Francisco", "state": "California", "postal_code": "94102", "country": "United States", "website_url": "https://johnelectronics.com", "facebook_url": "https://facebook.com/johnelectronics", "instagram_url": "https://instagram.com/johnelectronics", "twitter_url": "https://twitter.com/johnelectronics", "email_verified_at": "2026-01-20T10:00:00.000000Z" }, "merchant": { "id": 1, "store_name": "John Electronics", "slug": "john-electronics-abc123", "description": "Quality electronics and gadgets", "phone": "+1234567890", "email": "merchant@example.com", "address_line_1": "123 Tech Street", "address_line_2": "Suite 456", "city": "San Francisco", "state": "California", "postal_code": "94102", "country": "United States", "website_url": "https://johnelectronics.com", "facebook_url": "https://facebook.com/johnelectronics", "instagram_url": "https://instagram.com/johnelectronics", "twitter_url": "https://twitter.com/johnelectronics", "status": "active", "is_verified": true, "is_active": true, "logo_url": "/storage/merchants/logos/logo.png", "banner_url": "/storage/merchants/banners/banner.jpg", "business_hours": null, "commission_rate": "10.00", "commission_type": "percentage" }, "roles": ["vendor"] } } ``` --- ### Verify Email Mark the authenticated user's email as verified. **Endpoint:** `POST /verify-email` **Authentication:** Required (Bearer Token) #### Request Headers ```http Authorization: Bearer {access_token} ``` #### Example Request ```bash curl -X POST "https://ecom-backend-api.dmi.community/api/v1/merchant/verify-email" \ -H "Authorization: Bearer {access_token}" ``` #### Success Response (200 OK) ```json { "success": true, "message": "Email verified successfully." } ``` #### Already Verified ```json { "success": true, "message": "Email already verified." } ``` --- ## Profile Management Endpoints Profile endpoints require an active merchant account. The `merchant` middleware checks that the user has the vendor role, has a vendor profile, and the account is active. ### Default Merchant Settings When a merchant account is created, the following default settings are automatically configured. These settings can be updated via the Update Profile endpoint. #### Notification Settings These settings control whether merchants receive various types of notifications. The system automatically checks these settings before sending any notification. - `notification_email` - Email for notifications (defaults to vendor email) - `order_notification` - Enable order notifications (`true`) - **Controls new order email alerts** - `low_stock_alert` - Enable low stock alerts (`true`) - **Controls inventory alert notifications** - `low_stock_threshold` - Stock level to trigger alert (`10`) - `new_review_notification` - Enable review notifications (`true`) - `payment_notification` - Enable payment notifications (`true`) - `promotional_emails` - Enable promotional emails (`true`) > **Important:** When `order_notification` is set to `'false'`, the merchant will NOT receive any email notifications for new orders. When `low_stock_alert` is set to `'false'`, the merchant will NOT receive low stock alerts even if products fall below the threshold. #### Store Settings - `currency` - Store currency (`MMK`) - `timezone` - Store timezone (`Asia/Yangon`) - `date_format` - Date display format (`Y-m-d`) - `time_format` - Time display format (`H:i:s`) #### Order Management - `auto_accept_orders` - Automatically accept orders (`false`) - `order_processing_time` - Processing time in hours (`24`) - `min_order_amount` - Minimum order amount (`0`) - `max_order_amount` - Maximum order amount (`0` = no limit) #### Shipping Settings - `default_shipping_method` - Default shipping method (`standard`) - `free_shipping_threshold` - Free shipping minimum (`0`) - `default_shipping_cost` - Default shipping cost (`0`) #### Inventory Settings - `track_inventory` - Enable inventory tracking (`true`) - `allow_backorders` - Allow backorders (`false`) - `show_out_of_stock` - Show out of stock products (`true`) #### Customer Service - `return_policy_days` - Return policy duration in days (`30`) - `refund_policy` - Refund policy type (`full`) - `customer_support_email` - Support email (defaults to vendor email) #### Display Settings - `products_per_page` - Products per page (`20`) - `show_product_reviews` - Show product reviews (`true`) - `enable_wishlists` - Enable wishlist feature (`true`) #### Marketing - `enable_coupons` - Enable coupon system (`true`) - `enable_flash_sales` - Enable flash sales (`true`) - `show_related_products` - Show related products (`true`) #### Analytics & Reports - `enable_analytics` - Enable analytics tracking (`true`) - `email_reports` - Report frequency (`weekly`) #### Security - `require_email_verification` - Require email verification (`true`) - `enable_two_factor` - Enable two-factor authentication (`false`) > **Note:** All boolean settings are stored as strings (`'true'` or `'false'`). Numeric settings are also stored as strings. --- ### Get Profile Retrieve the complete merchant profile. **Endpoint:** `GET /profile` **Authentication:** Required (Bearer Token + Active Merchant) #### Request Headers ```http Authorization: Bearer {access_token} ``` #### Example Request ```bash curl -X GET "https://ecom-backend-api.dmi.community/api/v1/merchant/profile" \ -H "Authorization: Bearer {access_token}" ``` #### Success Response (200 OK) ```json { "success": true, "message": "Merchant profile retrieved successfully", "data": { "user": { "id": 1, "name": "John Doe", "email": "merchant@example.com", "email_verified_at": "2026-01-20T10:00:00.000000Z", "profile_photo_path": null }, "merchant": { "id": 1, "store_name": "John Electronics", "slug": "john-electronics-abc123", "description": "Quality electronics and gadgets", "phone": "+1234567890", "email": "store@johnelectronics.com", "address_line_1": "123 Tech Street", "address_line_2": "Suite 456", "city": "San Francisco", "state": "California", "postal_code": "94102", "country": "United States", "website_url": "https://johnelectronics.com", "facebook_url": "https://facebook.com/johnelectronics", "instagram_url": "https://instagram.com/johnelectronics", "twitter_url": "https://twitter.com/johnelectronics", "status": "active", "is_verified": true, "verified_at": "2026-01-15T08:00:00.000000Z", "is_active": true, "logo_url": "https://example.com/storage/merchants/logos/logo.png", "banner_url": "https://example.com/storage/merchants/banners/banner.jpg", "business_hours": [ {"day": "Monday", "open": "09:00", "close": "18:00", "is_closed": false}, {"day": "Sunday", "open": "00:00", "close": "00:00", "is_closed": true} ], "commission_rate": "10.00", "commission_type": "percentage", "settings": { "notification_email": "alerts@johnelectronics.com", "currency": "USD", "timezone": "America/New_York", "order_notification": "true", "auto_accept_orders": "false" }, "created_at": "2026-01-10T12:00:00.000000Z", "updated_at": "2026-01-20T10:00:00.000000Z" } } } ``` --- ### Update Profile Update merchant profile information including vendor settings. **Endpoint:** `PUT /profile` **Authentication:** Required (Bearer Token + Active Merchant) #### Request Headers ```http Authorization: Bearer {access_token} Content-Type: application/json ``` #### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | No | Owner's name (max 255 characters) | | store_name | string | No | Store name (max 255 characters) | | description | string | No | Store description (max 2000 characters) | | phone | string | No | Contact phone (max 20 characters) | | email | string | No | Store contact email (unique among vendors) | | address_line_1 | string | No | Street address line 1 (max 255 characters) | | address_line_2 | string | No | Street address line 2 (max 255 characters) | | city | string | No | City (max 100 characters) | | state | string | No | State/Province (max 100 characters) | | postal_code | string | No | Postal/ZIP code (max 20 characters) | | country | string | No | Country (max 100 characters) | | website_url | string | No | Website URL (must be valid URL) | | facebook_url | string | No | Facebook page URL (must be valid URL) | | instagram_url | string | No | Instagram profile URL (must be valid URL) | | twitter_url | string | No | Twitter profile URL (must be valid URL) | | business_hours | array | No | Array of business hours objects | | settings | array | No | Store settings. Supports two formats:
1. Flat object: `{"key1": "value1", "key2": "value2"}`
2. Array of objects: `[{"key": "key1", "value": "value1"}]`
Set value to `null` to delete a setting. | #### Business Hours Object | Field | Type | Required | Description | |-------|------|----------|-------------| | day | string | Yes | Day of the week | | open | string | Yes | Opening time (HH:MM format) | | close | string | Yes | Closing time (HH:MM format) | | is_closed | boolean | No | Whether closed on this day | #### Settings Object | Field | Type | Required | Description | |-------|------|----------|-------------| | key | string | Yes | Setting key name (max 255 characters) | | value | string | No | Setting value (max 1000 characters). Pass `null` to delete the setting | #### Example Request ```bash curl -X PUT "https://ecom-backend-api.dmi.community/api/v1/merchant/profile" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -d '{ "name": "John Smith", "store_name": "John Premium Electronics", "description": "Premium quality electronics and gadgets with warranty", "phone": "+1987654321", "address_line_1": "123 Tech Street", "address_line_2": "Suite 456", "city": "San Francisco", "state": "California", "postal_code": "94102", "country": "United States", "website_url": "https://johnelectronics.com", "facebook_url": "https://facebook.com/johnelectronics", "instagram_url": "https://instagram.com/johnelectronics", "twitter_url": "https://twitter.com/johnelectronics", "business_hours": [ {"day": "Monday", "open": "09:00", "close": "20:00", "is_closed": false}, {"day": "Tuesday", "open": "09:00", "close": "20:00", "is_closed": false}, {"day": "Sunday", "open": "00:00", "close": "00:00", "is_closed": true} ], "settings": [ {"key": "notification_email", "value": "alerts@store.com"}, {"key": "currency", "value": "USD"}, {"key": "timezone", "value": "America/New_York"}, {"key": "order_notification", "value": "true"}, {"key": "old_setting_to_remove", "value": null} ] }' ``` **Alternative: Using Flat Object Format for Settings** ```bash curl -X PUT "https://ecom-backend-api.dmi.community/api/v1/merchant/profile" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -d '{ "store_name": "John Premium Electronics", "settings": { "notification_email": "alerts@store.com", "currency": "USD", "timezone": "America/New_York", "order_notification": "true", "old_setting_to_remove": null } }' ``` #### Success Response (200 OK) ```json { "success": true, "message": "Merchant profile updated successfully", "data": { "user": { "id": 1, "name": "John Smith", "email": "merchant@example.com" }, "merchant": { "id": 1, "store_name": "John Premium Electronics", "slug": "john-electronics-abc123", "description": "Premium quality electronics and gadgets with warranty", "phone": "+1987654321", "email": "store@johnelectronics.com", "address_line_1": "123 Tech Street", "address_line_2": "Suite 456", "city": "San Francisco", "state": "California", "postal_code": "94102", "country": "United States", "website_url": "https://johnelectronics.com", "facebook_url": "https://facebook.com/johnelectronics", "instagram_url": "https://instagram.com/johnelectronics", "twitter_url": "https://twitter.com/johnelectronics", "business_hours": [ {"day": "Monday", "open": "09:00", "close": "20:00", "is_closed": false}, {"day": "Tuesday", "open": "09:00", "close": "20:00", "is_closed": false}, {"day": "Sunday", "open": "00:00", "close": "00:00", "is_closed": true} ], "status": "active", "is_verified": true, "is_active": true, "settings": { "notification_email": "alerts@store.com", "currency": "USD", "timezone": "America/New_York", "order_notification": "true" } } } } ``` > **Note:** The update response returns a subset of fields. Use `GET /profile` to retrieve the complete merchant profile including `logo_url`, `banner_url`, `verified_at`, `commission_rate`, `commission_type`, `created_at`, and `updated_at`. --- ## Store Branding Endpoints Manage store logo and banner images. ### Update Branding Upload logo and/or banner images. **Endpoint:** `POST /profile/branding` **Authentication:** Required (Bearer Token + Active Merchant) #### Request Headers ```http Authorization: Bearer {access_token} Content-Type: multipart/form-data ``` #### Request Body (multipart/form-data) | Field | Type | Required | Description | |-------|------|----------|-------------| | logo | file | No | Logo image (JPEG, PNG, JPG, GIF, WebP; max 2MB) | | banner | file | No | Banner image (JPEG, PNG, JPG, GIF, WebP; max 4MB) | #### Example Request ```bash curl -X POST "https://ecom-backend-api.dmi.community/api/v1/merchant/profile/branding" \ -H "Authorization: Bearer {access_token}" \ -F "logo=@/path/to/logo.png" \ -F "banner=@/path/to/banner.jpg" ``` #### Success Response (200 OK) ```json { "success": true, "message": "Merchant branding updated successfully", "data": { "merchant": { "id": 1, "logo_url": "/storage/merchants/logos/abc123.png", "banner_url": "/storage/merchants/banners/xyz789.jpg" }, "updated": ["logo_url", "banner_url"] } } ``` --- ### Remove Logo Remove the merchant's logo image. **Endpoint:** `DELETE /profile/logo` **Authentication:** Required (Bearer Token + Active Merchant) #### Request Headers ```http Authorization: Bearer {access_token} ``` #### Example Request ```bash curl -X DELETE "https://ecom-backend-api.dmi.community/api/v1/merchant/profile/logo" \ -H "Authorization: Bearer {access_token}" ``` #### Success Response (200 OK) ```json { "success": true, "message": "Logo removed successfully" } ``` --- ### Remove Banner Remove the merchant's banner image. **Endpoint:** `DELETE /profile/banner` **Authentication:** Required (Bearer Token + Active Merchant) #### Request Headers ```http Authorization: Bearer {access_token} ``` #### Example Request ```bash curl -X DELETE "https://ecom-backend-api.dmi.community/api/v1/merchant/profile/banner" \ -H "Authorization: Bearer {access_token}" ``` #### Success Response (200 OK) ```json { "success": true, "message": "Banner removed successfully" } ``` --- ## Statistics Endpoints ### Get Statistics Retrieve merchant store statistics. **Endpoint:** `GET /statistics` **Authentication:** Required (Bearer Token + Active Merchant) #### Request Headers ```http Authorization: Bearer {access_token} ``` #### Example Request ```bash curl -X GET "https://ecom-backend-api.dmi.community/api/v1/merchant/statistics" \ -H "Authorization: Bearer {access_token}" ``` #### Success Response (200 OK) ```json { "success": true, "message": "Merchant statistics retrieved successfully", "data": { "merchant_id": 1, "statistics": { "total_products": 150, "total_orders": 1250, "total_revenue": 125000.50, "total_customers": 450, "average_rating": 4.7, "total_reviews": 320 } } } ``` --- ## Product Management Endpoints Product management endpoints allow merchants to create, manage, and organize their products. ### Get Products List Retrieves a paginated list of the merchant's products with optional filters. **Endpoint:** `GET /products` **Authentication:** Required (Merchant) #### Query Parameters | Parameter | Type | Required | Description | |--------------|---------|----------|--------------------------------------------------| | status | string | No | Filter by product status (e.g., Active, Draft) | | category_id | integer | No | Filter by category ID | | stock_status | string | No | Filter by stock: `low`, `out_of_stock`, `in_stock` | | search | string | No | Search by product name or SKU | | sort_by | string | No | Sort field: `name`, `price`, `quantity`, `created_at`, `order_count` | | sort_order | string | No | Sort direction: `asc` or `desc` (default: desc) | | per_page | integer | No | Items per page (1-50, default: 15) | #### Success Response (200 OK) ```json { "success": true, "message": "Products retrieved successfully", "data": { "products": [ { "id": 1, "name": "Premium Wireless Headphones", "sku": "TST-PRE-A1B2", "price": "99.99", "quantity": 100, "available_quantity": 95, "is_low_stock": false, "status": "Active", "category": "Electronics", "image_url": "https://example.com/images/product.jpg", "order_count": 25, "created_at": "2026-01-21T12:00:00.000000Z" } ], "pagination": { "current_page": 1, "last_page": 5, "per_page": 15, "total": 68 } } } ``` --- ### Get Product Details Retrieves detailed information about a specific product. **Endpoint:** `GET /products/{id}` **Authentication:** Required (Merchant) #### Success Response (200 OK) ```json { "success": true, "message": "Product retrieved successfully", "data": { "id": 1, "name": "Premium Wireless Headphones", "description": "High-quality wireless headphones with noise cancellation", "search_keywords": "headphones, wireless, bluetooth, audio", "sku": "TST-PRE-A1B2", "barcode": "1234567890123", "price": "99.99", "quantity": 100, "reserved_quantity": 5, "available_quantity": 95, "low_stock_threshold": 10, "is_low_stock": false, "featured": true, "is_bestseller": false, "view_count": 1250, "order_count": 25, "average_rating": "4.50", "total_reviews": 18, "status": { "id": 1, "name": "Active" }, "category": { "id": 5, "name": "Electronics" }, "tags": [ {"id": 1, "name": "Wireless"}, {"id": 2, "name": "Audio"} ], "variants": [ { "id": 1, "attribute": {"id": 1, "name": "Color"}, "value": "Black", "additional_price": "0.00", "sku": "TST-PRE-A1B2-BLAC", "quantity": 50, "reserved_quantity": 2, "available_quantity": 48, "images": [ { "id": 11, "url": "https://example.com/images/product-black.jpg", "name": "product-black.jpg", "is_primary": true } ] } ], "images": [ { "id": 1, "url": "https://example.com/images/product-1.jpg", "name": "product-1.jpg", "is_primary": true } ], "created_at": "2026-01-21T12:00:00.000000Z", "updated_at": "2026-01-21T14:30:00.000000Z" } } ``` > **Contract note:** Product detail image arrays are ordered with the primary image first and each image includes an `is_primary` flag. Variant detail payloads follow the same convention. --- ### Create Product Creates a new product. **Endpoint:** `POST /products` **Authentication:** Required (Merchant) #### Request Body | Parameter | Type | Required | Description | |--------------------|---------|----------|---------------------------------------| | name | string | Yes | Product name (max 255 chars) | | category_id | integer | Yes | Category ID | | description | string | No | Product description (max 5000 chars) | | search_keywords | string | No | Search keywords (max 500 chars) | | price | number | Yes | Product price | | compare_at_price | number | No | Original/retail price for showing discount (must be > price) | | cost_price | number | No | Cost price for profit calculation (merchant only) | | quantity | integer | No | Initial stock quantity (default: 0) | | track_inventory | boolean | No | Track inventory automatically (default: true) | | allow_backorders | boolean | No | Continue selling when out of stock (default: false) | | low_stock_threshold| integer | No | Low stock alert threshold (default: 10)| | sku | string | No | SKU (auto-generated if not provided) | | barcode | string | No | Product barcode | | product_status_id | integer | No | Status ID (defaults to Draft) | | featured | boolean | No | Featured product flag | | tag_ids | array | No | Array of tag IDs | #### Example Request ```json { "name": "Premium Wireless Headphones", "category_id": 5, "description": "High-quality wireless headphones with noise cancellation", "price": 99.99, "compare_at_price": 129.99, "cost_price": 45.00, "quantity": 100, "track_inventory": true, "allow_backorders": false, "low_stock_threshold": 10, "featured": true, "tag_ids": [1, 2] } ``` #### Success Response (201 Created) ```json { "success": true, "message": "Product created successfully", "data": { "id": 1, "name": "Premium Wireless Headphones", "sku": "TST-PRE-A1B2", "...": "full product details" } } ``` --- ### Update Product Updates an existing product. **Endpoint:** `PUT /products/{id}` **Authentication:** Required (Merchant) #### Request Body All fields are optional. Only provided fields will be updated. | Parameter | Type | Required | Description | |--------------------|---------|----------|---------------------------------------| | name | string | No | Product name | | category_id | integer | No | Category ID | | description | string | No | Product description | | search_keywords | string | No | Search keywords | | price | number | No | Product price | | compare_at_price | number | No | Original/retail price for showing discount | | cost_price | number | No | Cost price for profit calculation | | quantity | integer | No | Stock quantity | | track_inventory | boolean | No | Track inventory automatically | | allow_backorders | boolean | No | Continue selling when out of stock | | low_stock_threshold| integer | No | Low stock alert threshold | | sku | string | No | SKU (must be unique) | | barcode | string | No | Product barcode | | product_status_id | integer | No | Status ID | | featured | boolean | No | Featured product flag | | tag_ids | array | No | Array of tag IDs (replaces existing) | #### Success Response (200 OK) ```json { "success": true, "message": "Product updated successfully", "data": { "...": "full product details" } } ``` --- ### Delete Product Deletes a product. **Endpoint:** `DELETE /products/{id}` **Authentication:** Required (Merchant) #### Success Response (200 OK) ```json { "success": true, "message": "Product deleted successfully", "data": null } ``` #### Error Response (400 Bad Request) ```json { "success": false, "message": "Cannot delete product with existing orders. Consider archiving instead." } ``` #### Notes - Products with existing orders cannot be deleted - Deleting a product also removes its variants, tags, and images --- ### Update Product Stock Updates the stock quantity for a product. **Endpoint:** `PATCH /products/{id}/stock` **Authentication:** Required (Merchant) #### Request Body | Parameter | Type | Required | Description | |-----------|---------|----------|------------------------------------------------| | quantity | integer | Yes | Quantity value | | operation | string | No | Operation: `set` (default), `add`, `subtract` | #### Example Requests **Set stock to specific value:** ```json { "quantity": 100, "operation": "set" } ``` **Add to existing stock:** ```json { "quantity": 25, "operation": "add" } ``` **Subtract from stock:** ```json { "quantity": 10, "operation": "subtract" } ``` #### Success Response (200 OK) ```json { "success": true, "message": "Stock updated successfully", "data": { "quantity": 100, "reserved_quantity": 5, "available_quantity": 95, "is_low_stock": false } } ``` --- ## Product Variants Endpoints ### Get Product Variants Retrieves all variants for a product. **Endpoint:** `GET /products/{id}/variants` **Authentication:** Required (Merchant) #### Success Response (200 OK) ```json { "success": true, "message": "Variants retrieved successfully", "data": { "product_id": 1, "product_name": "Premium Wireless Headphones", "variants": [ { "id": 1, "attributes": [ {"id": 1, "name": "Color", "value": "Black"}, {"id": 2, "name": "Size", "value": "M"} ], "additional_price": "0.00", "sku": "TST-PRE-COSI", "quantity": 50, "reserved_quantity": 2, "available_quantity": 48 }, { "id": 2, "attributes": [ {"id": 1, "name": "Color", "value": "White"}, {"id": 2, "name": "Size", "value": "L"} ], "additional_price": "5.00", "sku": "TST-PRE-COSI", "quantity": 30, "reserved_quantity": 0, "available_quantity": 30, "images": [ { "id": 21, "url": "https://example.com/images/headphones-white.jpg", "name": "headphones-white.jpg", "is_primary": true } ] } ] } } ``` > **Contract note:** Variant list payloads include image metadata so merchant clients can render thumbnails without issuing one request per variant. --- ### Create Product Variant Creates a new variant for a product. **Endpoint:** `POST /products/{id}/variants` **Authentication:** Required (Merchant) #### Request Body | Parameter | Type | Required | Description | |------------------|---------|----------|--------------------------------| | attributes | array | Yes | List of attribute/value pairs | | attributes[].attribute_id | integer | Yes | Product attribute ID | | attributes[].value | string | Yes | Attribute value (e.g., "Red") | | additional_price | number | No | Additional price (default: 0) | | quantity | integer | No | Stock quantity (default: 0) | | sku | string | No | SKU (auto-generated if not provided) | #### Example Request ```json { "attributes": [ {"attribute_id": 1, "value": "Blue"}, {"attribute_id": 2, "value": "M"} ], "additional_price": 10.00, "quantity": 25 } ``` #### Success Response (201 Created) ```json { "success": true, "message": "Variant created successfully", "data": { "id": 3, "attributes": [ {"id": 1, "name": "Color", "value": "Blue"}, {"id": 2, "name": "Size", "value": "M"} ], "additional_price": "10.00", "sku": "TST-PRE-BLUE", "quantity": 25, "reserved_quantity": 0, "available_quantity": 25 } } ``` --- ### Update Product Variant Updates an existing variant. **Endpoint:** `PUT /products/{productId}/variants/{variantId}` **Authentication:** Required (Merchant) #### Request Body All fields are optional. | Parameter | Type | Required | Description | |------------------|---------|----------|-------------------------| | attributes | array | No | List of attribute/value pairs | | attributes[].attribute_id | integer | Yes if attributes present | Product attribute ID | | attributes[].value | string | Yes if attributes present | Attribute value | | additional_price | number | No | Additional price | | quantity | integer | No | Stock quantity | | sku | string | No | SKU | #### Success Response (200 OK) ```json { "success": true, "message": "Variant updated successfully", "data": { "...": "variant details" } } ``` --- ### Delete Product Variant Deletes a variant. **Endpoint:** `DELETE /products/{productId}/variants/{variantId}` **Authentication:** Required (Merchant) #### Success Response (200 OK) ```json { "success": true, "message": "Variant deleted successfully", "data": null } ``` --- ## Product Variant Images Endpoints ### Get Variant Images Retrieves all images for a product variant. **Endpoint:** `GET /products/{productId}/variants/{variantId}/images` **Authentication:** Required (Merchant) **Rate Limit:** 60 requests/minute #### Success Response (200 OK) ```json { "success": true, "message": "Success", "data": { "images": [ { "id": 1, "url": "https://example.com/storage/variants/red-shirt-front.jpg", "name": "red-shirt-front.jpg", "is_primary": true }, { "id": 2, "url": "https://example.com/storage/variants/red-shirt-back.jpg", "name": "red-shirt-back.jpg", "is_primary": false } ] } } ``` --- ### Upload Variant Images Uploads one or more images for a product variant. **Endpoint:** `POST /products/{productId}/variants/{variantId}/images` **Authentication:** Required (Merchant) **Content-Type:** `multipart/form-data` **Rate Limit:** 10 requests/minute #### Request Body | Parameter | Type | Required | Description | |-----------|-------|----------|------------------------------------| | images[] | files | Yes | Image files (max 10, max 5MB each) | #### Accepted Formats - JPEG, PNG, JPG, GIF, WebP #### Success Response (200 OK) ```json { "success": true, "message": "Images uploaded successfully", "data": { "images": [ { "id": 3, "url": "https://example.com/storage/variants/blue-shirt.jpg", "name": "blue-shirt.jpg", "is_primary": true } ] } } ``` --- ### Delete Variant Image Deletes a specific image from a product variant. **Endpoint:** `DELETE /products/{productId}/variants/{variantId}/images/{imageId}` **Authentication:** Required (Merchant) **Rate Limit:** 30 requests/minute #### Success Response (200 OK) ```json { "success": true, "message": "Image deleted successfully", "data": null } ``` --- ### Set Variant Primary Image Sets a specific image as the primary/featured image for the variant. **Endpoint:** `PATCH /products/{productId}/variants/{variantId}/images/{imageId}/primary` **Authentication:** Required (Merchant) **Rate Limit:** 30 requests/minute #### Success Response (200 OK) ```json { "success": true, "message": "Primary image set successfully", "data": { "images": [ { "id": 2, "url": "https://example.com/storage/variants/red-shirt-back.jpg", "name": "red-shirt-back.jpg", "is_primary": true }, { "id": 1, "url": "https://example.com/storage/variants/red-shirt-front.jpg", "name": "red-shirt-front.jpg", "is_primary": false } ] } } ``` --- ## Product Images Endpoints ### Upload Product Images Uploads one or more images for a product. **Endpoint:** `POST /products/{id}/images` **Authentication:** Required (Merchant) **Content-Type:** `multipart/form-data` #### Request Body | Parameter | Type | Required | Description | |------------|-------|----------|------------------------------------------| | images[] | files | Yes | Image files (max 10, max 5MB each) | #### Accepted Formats - JPEG, PNG, JPG, GIF, WebP #### Success Response (200 OK) ```json { "success": true, "message": "Images uploaded successfully", "data": { "images": [ { "id": 1, "url": "https://example.com/storage/products/image1.jpg", "name": "image1.jpg", "is_primary": true }, { "id": 2, "url": "https://example.com/storage/products/image2.jpg", "name": "image2.jpg", "is_primary": false } ] } } ``` > **Contract note:** Product and variant image uploads both normalize on `data.images`, so merchant web screens can share one parser across product-level and variant-level media workflows. --- ### Delete Product Image Deletes a product image. **Endpoint:** `DELETE /products/{productId}/images/{imageId}` **Authentication:** Required (Merchant) #### Success Response (200 OK) ```json { "success": true, "message": "Image deleted successfully", "data": null } ``` #### Curation Notes - Reordering only applies to products that already belong to the authenticated merchant's collection. - Use `POST /collections/{id}/products` and `DELETE /collections/{id}/products` to change membership first, then `PATCH /collections/{id}/products/reorder` to control storefront order. --- ### Set Primary Product Image Sets a specific image as the primary/featured image for the product. The primary image will be displayed first in listings and product details. **Endpoint:** `PATCH /products/{productId}/images/{imageId}/primary` **Authentication:** Required (Merchant) **Rate Limit:** 30 requests/minute #### Path Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | productId | integer | Yes | Product ID | | imageId | integer | Yes | Image ID to set as primary | #### Success Response (200 OK) ```json { "success": true, "message": "Primary image set successfully", "data": { "images": [ { "id": 5, "url": "https://example.com/storage/products/primary-image.jpg", "name": "primary-image.jpg", "is_primary": true }, { "id": 3, "url": "https://example.com/storage/products/image-2.jpg", "name": "image-2.jpg", "is_primary": false }, { "id": 4, "url": "https://example.com/storage/products/image-3.jpg", "name": "image-3.jpg", "is_primary": false } ] } } ``` #### Error Responses **Product Not Found (400)** ```json { "success": false, "message": "Product not found" } ``` **Image Not Found (400)** ```json { "success": false, "message": "Image not found" } ``` --- ## Reference Data Endpoints ### Get Categories Retrieves available product categories. **Endpoint:** `GET /products/categories` **Authentication:** Required (Merchant) #### Success Response (200 OK) ```json { "success": true, "message": "Categories retrieved successfully", "data": { "categories": [ { "id": 1, "name": "Electronics", "children": [ {"id": 5, "name": "Headphones", "children": []}, {"id": 6, "name": "Speakers", "children": []} ] }, { "id": 2, "name": "Clothing", "children": [] } ] } } ``` --- ### Get Product Statuses Retrieves available product statuses. **Endpoint:** `GET /products/statuses` **Authentication:** Required (Merchant) #### Success Response (200 OK) ```json { "success": true, "message": "Product statuses retrieved successfully", "data": { "statuses": [ {"id": 1, "name": "Draft"}, {"id": 2, "name": "Active"}, {"id": 3, "name": "Inactive"}, {"id": 4, "name": "Out of Stock"} ] } } ``` --- ### Get Product Attributes Retrieves available product attributes for variants. **Endpoint:** `GET /products/attributes` **Authentication:** Required (Merchant) #### Success Response (200 OK) ```json { "success": true, "message": "Product attributes retrieved successfully", "data": { "attributes": [ {"id": 1, "name": "Color"}, {"id": 2, "name": "Size"}, {"id": 3, "name": "Material"} ] } } ``` --- ### Get Product Tags Retrieves available product tags. Supports optional search filtering. **Endpoint:** `GET /products/tags` **Authentication:** Required (Merchant) **Rate Limit:** 60 requests/minute #### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | search | string | No | Filter tags by name (partial match) | #### Success Response (200 OK) ```json { "success": true, "message": "Tags retrieved successfully", "data": { "tags": [ {"id": 1, "name": "New Arrival"}, {"id": 2, "name": "Best Seller"}, {"id": 3, "name": "Sale"}, {"id": 4, "name": "Limited Edition"} ] } } ``` --- ### Create Product Tag Creates a new product tag. If the tag already exists (case-insensitive), returns the existing tag. **Endpoint:** `POST /products/tags` **Authentication:** Required (Merchant) **Rate Limit:** 30 requests/minute #### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Tag name (max 100 characters) | #### Request Example ```json { "name": "Summer Collection" } ``` #### Success Response - New Tag Created (201 Created) ```json { "success": true, "message": "Tag created successfully", "data": { "tag": { "id": 5, "name": "Summer Collection" }, "created": true } } ``` #### Success Response - Tag Already Exists (200 OK) ```json { "success": true, "message": "Tag already exists", "data": { "tag": { "id": 3, "name": "Summer Collection" }, "created": false } } ``` --- ### Create Multiple Product Tags (Bulk) Creates multiple product tags at once. Existing tags are returned without creating duplicates. **Endpoint:** `POST /products/tags/bulk` **Authentication:** Required (Merchant) **Rate Limit:** 10 requests/minute #### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | names | array | Yes | Array of tag names (1-20 items, each max 100 characters) | #### Request Example ```json { "names": ["Winter Sale", "Premium", "Eco-Friendly", "Handmade"] } ``` #### Success Response (200 OK) ```json { "success": true, "message": "Tags processed successfully", "data": { "created": [ {"id": 6, "name": "Winter Sale"}, {"id": 7, "name": "Eco-Friendly"}, {"id": 8, "name": "Handmade"} ], "existing": [ {"id": 2, "name": "Premium"} ], "failed": [], "summary": { "created_count": 3, "existing_count": 1, "failed_count": 0 } } } ``` --- ## Product Collections Endpoints Product Collections allow merchants to create custom groupings of their products, separate from the global category system. Collections can be used for seasonal promotions, featured products, or any custom organization strategy. ### List Collections Retrieve all product collections for the merchant's store. **Endpoint:** `GET /collections` **Authentication:** Required (Merchant) **Rate Limit:** 60 requests/minute #### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | is_active | boolean | No | Filter by active status | | is_featured | boolean | No | Filter by featured status | | search | string | No | Search in name and description | | per_page | integer | No | Items per page (default: 15) | #### Success Response (200 OK) ```json { "success": true, "data": { "current_page": 1, "data": [ { "id": 1, "vendor_id": 5, "name": "Summer Collection", "slug": "summer-collection", "description": "Hot summer items", "image_url": "https://example.com/images/summer.jpg", "display_order": 0, "is_active": true, "is_featured": true, "created_at": "2026-01-29T10:00:00.000000Z", "updated_at": "2026-01-29T10:00:00.000000Z", "products": [ { "id": 101, "name": "Summer Dress", "price": "49.99", "pivot": { "display_order": 0 } } ] } ], "per_page": 15, "total": 5 } } ``` --- ### Create Collection Create a new product collection. **Endpoint:** `POST /collections` **Authentication:** Required (Merchant) **Rate Limit:** 30 requests/minute #### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Collection name (max: 255) | | slug | string | No | URL-friendly slug (auto-generated if not provided) | | description | string | No | Collection description | | image_url | string | No | Collection banner image URL (max: 500) | | display_order | integer | No | Display order (default: 0) | | is_active | boolean | No | Active status (default: true) | | is_featured | boolean | No | Featured on homepage (default: false) | | product_ids | array | No | Array of product IDs to add | #### Example Request ```json { "name": "Summer Collection", "description": "Hot summer items", "is_active": true, "is_featured": true, "product_ids": [101, 102, 103] } ``` #### Success Response (201 Created) ```json { "success": true, "message": "Collection created successfully.", "data": { "id": 1, "vendor_id": 5, "name": "Summer Collection", "slug": "summer-collection", "description": "Hot summer items", "is_active": true, "is_featured": true, "products": [ { "id": 101, "name": "Summer Dress", "price": "49.99" } ] } } ``` #### Error Responses **422 Validation Error - Duplicate Slug** ```json { "success": false, "message": "A collection with this slug already exists." } ``` --- ### Get Collection Details Get detailed information about a specific collection. **Endpoint:** `GET /collections/{id}` **Authentication:** Required (Merchant) **Rate Limit:** 60 requests/minute #### URL Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | integer | Yes | Collection ID | #### Success Response (200 OK) ```json { "success": true, "data": { "id": 1, "vendor_id": 5, "name": "Summer Collection", "slug": "summer-collection", "description": "Hot summer items", "products": [ { "id": 101, "name": "Summer Dress", "price": "49.99", "status": { "id": 1, "name": "Active" }, "category": { "id": 10, "name": "Women's Fashion" } } ] } } ``` --- ### Update Collection Update an existing collection. **Endpoint:** `PATCH /collections/{id}` **Authentication:** Required (Merchant) **Rate Limit:** 30 requests/minute #### URL Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | integer | Yes | Collection ID | #### Request Body All fields are optional. Only include fields you want to update. | Field | Type | Description | |-------|------|-------------| | name | string | Collection name (max: 255) | | slug | string | URL-friendly slug (max: 255) | | description | string | Collection description | | image_url | string | Collection banner image URL (max: 500) | | display_order | integer | Display order (min: 0) | | is_active | boolean | Active status | | is_featured | boolean | Featured status | | product_ids | array | Array of product IDs (replaces existing products) | #### Example Request ```json { "name": "Updated Summer Collection", "is_featured": true, "product_ids": [101, 102, 104, 105] } ``` #### Success Response (200 OK) ```json { "success": true, "message": "Collection updated successfully.", "data": { "id": 1, "name": "Updated Summer Collection", "is_featured": true, "products": [] } } ``` --- ### Delete Collection Delete a collection. Products are not deleted, only the collection. **Endpoint:** `DELETE /collections/{id}` **Authentication:** Required (Merchant) **Rate Limit:** 30 requests/minute #### URL Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | integer | Yes | Collection ID | #### Success Response (200 OK) ```json { "success": true, "message": "Collection deleted successfully." } ``` --- ### Add Products to Collection Add products to an existing collection without removing existing products. **Endpoint:** `POST /collections/{id}/products` **Authentication:** Required (Merchant) **Rate Limit:** 30 requests/minute #### URL Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | integer | Yes | Collection ID | #### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | product_ids | array | Yes | Array of product IDs to add (min: 1) | #### Example Request ```json { "product_ids": [106, 107, 108] } ``` #### Success Response (200 OK) ```json { "success": true, "message": "Products added to collection successfully.", "data": { "id": 1, "products": [] } } ``` --- ### Remove Products from Collection Remove specific products from a collection. **Endpoint:** `DELETE /collections/{id}/products` **Authentication:** Required (Merchant) **Rate Limit:** 30 requests/minute #### URL Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | integer | Yes | Collection ID | #### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | product_ids | array | Yes | Array of product IDs to remove (min: 1) | #### Example Request ```json { "product_ids": [101, 102] } ``` #### Success Response (200 OK) ```json { "success": true, "message": "Products removed from collection successfully.", "data": { "id": 1, "products": [] } } ``` --- ### Reorder Products in Collection Change the display order of products within a collection. **Endpoint:** `PATCH /collections/{id}/products/reorder` **Authentication:** Required (Merchant) **Rate Limit:** 30 requests/minute #### URL Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | integer | Yes | Collection ID | #### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | products | array | Yes | Array of product ordering objects (min: 1) | | products[].product_id | integer | Yes | Product ID | | products[].display_order | integer | Yes | Display order (min: 0) | #### Example Request ```json { "products": [ { "product_id": 103, "display_order": 0 }, { "product_id": 101, "display_order": 1 }, { "product_id": 102, "display_order": 2 } ] } ``` #### Success Response (200 OK) ```json { "success": true, "message": "Products reordered successfully.", "data": { "id": 1, "products": [] } } ``` --- ### Upload Collection Image Upload or replace a collection image. This replaces the existing collection image if one exists. **Endpoint:** `POST /collections/{id}/image` **Authentication:** Required (Merchant) **Rate Limit:** 30 requests/minute #### URL Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | integer | Yes | Collection ID | #### Request Body (multipart/form-data) | Field | Type | Required | Description | |-------|------|----------|-------------| | image | file | Yes | Image file (jpeg, png, jpg, gif, webp, max 5MB) | #### Example Request ```bash curl -X POST "{{baseUrl}}/collections/1/image" \ -H "Authorization: Bearer {{token}}" \ -F "image=@collection.jpg" ``` #### Success Response (200 OK) ```json { "success": true, "message": "Collection image uploaded successfully.", "data": { "id": 22, "url": "https://example.com/storage/collections/collection.jpg", "name": "collection.jpg" } } ``` --- ### Collection Use Cases **Seasonal Collections:** - "Spring Collection" - "Summer Sale" - "Winter Essentials" - "Holiday Gifts" **Product Type Collections:** - "Best Sellers" - "New Arrivals" - "Clearance Items" - "Staff Picks" **Price-Based Collections:** - "Under $25" - "Luxury Items" - "Budget Friendly" **Theme-Based Collections:** - "Eco-Friendly Products" - "Gift Ideas" - "Travel Essentials" - "Work From Home" --- ## Order Management Endpoints Order management allows merchants to view, manage, and fulfill customer orders. All endpoints require merchant authentication and active vendor status. ### List Orders Retrieve a paginated list of orders for the merchant's store with filtering, searching, and sorting capabilities. **Endpoint:** `GET /orders` **Authentication:** Required (Merchant) **Rate Limit:** 60 requests/minute #### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | page | integer | No | Page number (default: 1) | | per_page | integer | No | Items per page (1-50, default: 15) | | status | string | No | Filter by order status name | | from_date | date | No | Filter orders from this date (YYYY-MM-DD) | | to_date | date | No | Filter orders up to this date (YYYY-MM-DD) | | search | string | No | Search by order number | | customer_search | string | No | Search by customer name or email | | product_search | string | No | Search by product name | | min_amount | decimal | No | Filter by minimum order amount | | max_amount | decimal | No | Filter by maximum order amount | | sort_by | string | No | Sort field: `created_at`, `total_amount`, `order_number` (default: created_at) | | sort_order | string | No | Sort direction: `asc` or `desc` (default: desc) | #### Example Request ```bash curl -X GET "https://ecom-backend-api.dmi.community/api/v1/merchant/orders?status=Pending&per_page=20&sort_by=created_at&sort_order=desc" \ -H "Authorization: Bearer {access_token}" ``` #### Success Response (200 OK) ```json { "success": true, "message": "Orders retrieved successfully", "data": { "orders": [ { "id": 1, "order_number": "ORD-20260127ABC123", "status": { "id": 1, "name": "Pending" }, "customer": { "id": 5, "name": "Jane Smith", "email": "jane@example.com" }, "item_count": 3, "subtotal": "299.97", "total_amount": "329.96", "created_at": "2026-01-27T10:30:00.000000Z" } ], "pagination": { "current_page": 1, "last_page": 5, "per_page": 20, "total": 87 } } } ``` --- ### Get Order Details Retrieve detailed information about a specific order. **Endpoint:** `GET /orders/{id}` **Authentication:** Required (Merchant) **Rate Limit:** 60 requests/minute #### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | id | integer | Order ID | #### Example Request ```bash curl -X GET "https://ecom-backend-api.dmi.community/api/v1/merchant/orders/1" \ -H "Authorization: Bearer {access_token}" ``` #### Success Response (200 OK) ```json { "success": true, "message": "Order retrieved successfully", "data": { "id": 1, "order_number": "ORD-20260127ABC123", "status": { "id": 1, "name": "Pending" }, "allowed_transitions": ["Confirmed", "Cancelled"], "customer": { "id": 5, "name": "Jane Smith", "email": "jane@example.com" }, "items": [ { "id": 1, "product_id": 10, "product_variant_id": 22, "quantity": 2, "price": "99.99", "total": "199.98", "product": { "id": 10, "name": "Wireless Headphones", "sku": "WH-001", "image_url": "https://example.com/storage/products/headphones.jpg" }, "variant": { "id": 22, "name": "Black / Large", "sku": "WH-001-BLK-L", "image_url": "https://example.com/images/variants/headphones-black-large.jpg" } } ], "subtotal": "199.98", "discount_amount": "0.00", "coupon_code": null, "shipping_fee": "9.99", "tax_amount": "20.00", "total_amount": "229.97", "shipping_address": { "id": 1, "name": "Jane Smith", "phone": "+1234567890", "address_line1": "123 Main St", "address_line2": "Apt 4B", "city": "New York", "state": "NY", "postal_code": "10001", "country": "United States" }, "billing_address": { "id": 1, "name": "Jane Smith", "phone": "+1234567890", "address_line1": "123 Main St", "address_line2": "Apt 4B", "city": "New York", "state": "NY", "postal_code": "10001", "country": "United States" }, "payment": { "id": 1, "method": "Credit Card", "amount": "229.97", "status": "completed", "transaction_id": "txn_abc123xyz" }, "shipments": [], "cancellation": null, "can_cancel": true, "created_at": "2026-01-27T10:30:00.000000Z", "updated_at": "2026-01-27T10:30:00.000000Z" } } ``` #### Error Response - Order Not Found (404) ```json { "success": false, "message": "Order not found" } ``` --- ### Get Order Invoice Retrieve invoice-friendly data for merchant support, print, and export flows. **Endpoint:** `GET /orders/{id}/invoice` **Authentication:** Required (Merchant) **Rate Limit:** 30 requests/minute #### Success Response (200 OK) ```json { "success": true, "message": "Order invoice retrieved successfully", "data": { "order_id": 1, "order_number": "ORD-20260127ABC123", "invoice_number": "INV-ORD-20260127ABC123", "issued_at": "2026-01-27T10:30:00.000000Z", "status": "Confirmed", "merchant": { "id": 3, "store_name": "Acme Goods", "email": "support@acme.test", "phone": "+1234567890" }, "summary": { "subtotal": 199.98, "discount_amount": 0, "shipping_fee": 9.99, "tax_amount": 20, "total_amount": 229.97, "coupon_code": null }, "vendor_orders": [ { "order_id": 1, "order_number": "ORD-20260127ABC123", "status": "Confirmed", "items": [ { "id": 1, "name": "Wireless Headphones (Black / Large)", "sku": "WH-001-BLK-L", "quantity": 2, "price": 99.99, "line_total": 199.98 } ], "shipments": [] } ] } } ``` #### Notes - Use this endpoint for invoice screens and download/export actions instead of rebuilding totals client-side. - Merchant invoice payloads always reflect the authenticated merchant's own vendor order. --- ### Update Order Status Update the status of an order. Only valid status transitions are allowed based on the current status. **Endpoint:** `PATCH /orders/{id}/status` **Authentication:** Required (Merchant) **Rate Limit:** 30 requests/minute #### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | id | integer | Order ID | #### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | status | string | Yes | New status name (see allowed transitions) | | note | string | No | Optional note about the status change | #### Status Transitions **Merchant-Controlled Statuses (Manual Updates Allowed):** | Current Status | Allowed Transitions | Notes | |----------------|---------------------|-------| | Pending | Confirmed, On Hold, Cancelled | Initial state | | Confirmed | Processing, On Hold, Cancelled | Payment accepted | | Processing | Prepared, On Hold, Cancelled | Order being prepared | | Prepared | Ready to Ship | Items packed | | Ready to Ship | Shipped | Ready for pickup | | On Hold | Processing, Cancelled | Resume or cancel | **System/Courier-Controlled Statuses (Automatic/External Updates Only):** | Current Status | Updated By | Notes | |----------------|------------|-------| | Shipped | System/Courier API | No manual merchant updates | | In Transit | Courier API | Tracking system updates | | Out for Delivery | Courier API | Last mile delivery | | Delivered | Courier API | Final successful state | | Failed Delivery | Courier API | Delivery attempt failed | **Final States (No Further Updates):** | Status | Description | |--------|-------------| | Cancelled | Order cancelled before shipment | | Refunded | Payment returned to customer | | Returned | Customer returned the order | **Status Flow Overview:** - **Merchant Control**: Pending → Confirmed → Processing → Prepared → Ready to Ship → Shipped - **System Control**: Shipped → In Transit → Out for Delivery → Delivered - **Hold Status**: Can be applied from Pending, Confirmed, or Processing (then resume or cancel) - **Cancellation**: Only before shipment (Pending, Confirmed, Processing, On Hold) - **Returns**: Handled through separate return process API #### Example Request ```bash curl -X PATCH "https://ecom-backend-api.dmi.community/api/v1/merchant/orders/1/status" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -d '{ "status": "Confirmed", "note": "Payment verified, preparing for shipment" }' ``` #### Success Response (200 OK) ```json { "success": true, "message": "Order status updated successfully", "data": { "id": 1, "order_number": "ORD-20260127ABC123", "status": { "id": 2, "name": "Confirmed" }, "allowed_transitions": ["Processing", "Cancelled"], "customer": { "id": 5, "name": "Jane Smith", "email": "jane@example.com" }, "items": [...], "total_amount": "229.97", "can_cancel": true, "created_at": "2026-01-27T10:30:00.000000Z", "updated_at": "2026-01-27T10:35:00.000000Z" } } ``` #### Error Response - Invalid Transition (400) ```json { "success": false, "message": "Cannot transition from 'Pending' to 'Shipped'. Allowed: Confirmed, Cancelled" } ``` --- ### Cancel Order Cancel an order. Only orders in Pending, Confirmed, Processing, or On Hold status can be cancelled. **Endpoint:** `POST /orders/{id}/cancel` **Authentication:** Required (Merchant) **Rate Limit:** 10 requests/minute #### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | id | integer | Order ID | #### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | reason | string | Yes | Reason for cancellation (required) | #### Example Request ```bash curl -X POST "https://ecom-backend-api.dmi.community/api/v1/merchant/orders/1/cancel" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -d '{ "reason": "Product out of stock" }' ``` #### Success Response (200 OK) ```json { "success": true, "message": "Order cancelled successfully", "data": { "id": 1, "order_number": "ORD-20260127ABC123", "status": { "id": 6, "name": "Cancelled" }, "cancellation": { "reason": "Product out of stock", "cancelled_by": "John Doe", "cancelled_by_type": "vendor", "refund_amount": "229.97", "refund_status": "pending", "cancelled_at": "2026-01-27T11:00:00.000000Z" }, "can_cancel": false, "created_at": "2026-01-27T10:30:00.000000Z", "updated_at": "2026-01-27T11:00:00.000000Z" } } ``` #### Error Response - Cannot Cancel (400) ```json { "success": false, "message": "Order cannot be cancelled. Only pending, confirmed, or processing orders can be cancelled." } ``` --- ### Get Order Analytics Retrieve comprehensive analytics for the merchant's orders including revenue trends, top products, and order statistics. **Endpoint:** `GET /orders/analytics` **Authentication:** Required (Merchant) **Rate Limit:** 60 requests/minute #### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | period | string | No | Analytics period (not currently used, reserved for future) | #### Example Request ```bash curl -X GET "https://ecom-backend-api.dmi.community/api/v1/merchant/orders/analytics" \ -H "Authorization: Bearer {access_token}" ``` #### Success Response (200 OK) ```json { "success": true, "message": "Order analytics retrieved successfully", "data": { "summary": { "all_time": { "total_orders": 150, "total_revenue": "45750.50", "average_order_value": "305.00", "unique_customers": 87 }, "this_month": { "total_orders": 25, "total_revenue": "7625.00", "average_order_value": "305.00", "unique_customers": 20 }, "today": { "total_orders": 3, "total_revenue": "915.00", "average_order_value": "305.00", "unique_customers": 3 } }, "orders_by_status": { "Pending": 5, "Confirmed": 8, "Processing": 3, "Shipped": 2, "Delivered": 120, "Cancelled": 12 }, "revenue_trend": [ { "date": "2026-01-01", "orders": 3, "revenue": "915.00" }, { "date": "2026-01-02", "orders": 5, "revenue": "1525.00" } ], "top_products": [ { "id": 10, "name": "Wireless Headphones", "total_quantity": 45, "total_revenue": "4499.55" }, { "id": 15, "name": "Smart Watch", "total_quantity": 32, "total_revenue": "6399.68" } ], "orders_by_day_of_week": { "Monday": 25, "Tuesday": 28, "Wednesday": 22, "Thursday": 20, "Friday": 30, "Saturday": 18, "Sunday": 7 }, "generated_at": "2026-01-27T15:30:00+00:00" } } ``` --- ### Get Order Statuses Retrieve all available order statuses and their allowed transitions. **Endpoint:** `GET /orders/statuses` **Authentication:** Required (Merchant) **Rate Limit:** 60 requests/minute #### Example Request ```bash curl -X GET "https://ecom-backend-api.dmi.community/api/v1/merchant/orders/statuses" \ -H "Authorization: Bearer {access_token}" ``` #### Success Response (200 OK) ```json { "success": true, "message": "Order statuses retrieved successfully", "data": { "statuses": [ "Pending", "Confirmed", "Processing", "Prepared", "Ready to Ship", "Shipped", "In Transit", "Out for Delivery", "Delivered", "Cancelled", "Refunded", "On Hold", "Failed Delivery", "Returned" ], "transitions": { "Pending": ["Confirmed", "On Hold", "Cancelled"], "Confirmed": ["Processing", "On Hold", "Cancelled"], "Processing": ["Prepared", "On Hold", "Cancelled"], "Prepared": ["Ready to Ship"], "Ready to Ship": ["Shipped"], "Shipped": ["In Transit"], "In Transit": ["Out for Delivery", "Failed Delivery"], "Out for Delivery": ["Delivered", "Failed Delivery"], "Delivered": ["Returned"], "On Hold": ["Processing", "Cancelled"], "Failed Delivery": ["In Transit", "Returned"], "Cancelled": [], "Refunded": [], "Returned": ["Refunded"] } } } ``` --- ## Shipment Management Endpoints Manage order shipments including tracking information and delivery status. ### Get Order Shipments Retrieve all shipments for a specific order. **Endpoint:** `GET /orders/{orderId}/shipments` **Authentication:** Required (Merchant) **Rate Limit:** 60 requests/minute #### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | orderId | integer | Order ID | #### Example Request ```bash curl -X GET "https://ecom-backend-api.dmi.community/api/v1/merchant/orders/1/shipments" \ -H "Authorization: Bearer {access_token}" ``` #### Success Response (200 OK) ```json { "success": true, "message": "Order shipments retrieved successfully", "data": { "order_id": 1, "order_number": "ORD-20260127ABC123", "shipments": [ { "id": 1, "tracking_number": "TRACK123456", "carrier": "FedEx", "status": { "id": 3, "name": "Shipped" }, "shipping_fee": "9.99", "estimated_delivery_days": 3, "shipped_at": "2026-01-27T14:00:00.000000Z", "delivered_at": null, "created_at": "2026-01-27T12:00:00.000000Z" } ] } } ``` > **Contract note:** Merchant analytics clients should treat `summary`, `orders_by_status`, `revenue_trend`, `top_products`, and `generated_at` as the stable top-level fields. The optional `period` query parameter is currently reserved and does not change the response shape. --- ### Create Shipment Create a new shipment for an order. Orders must be in Confirmed, Processing, Prepared, Ready to Ship, or Shipped status. **Endpoint:** `POST /orders/{orderId}/shipments` **Authentication:** Required (Merchant) **Rate Limit:** 30 requests/minute #### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | orderId | integer | Order ID | #### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | carrier | string | Yes | Carrier name (max 100 characters) | | status | string | No | Initial status: `Pending`, `Preparing`, `Ready to Ship`, `Shipped` (default: Pending) | | shipping_fee | decimal | No | Shipping cost (default: 0.00) | | estimated_delivery_days | integer | No | Estimated delivery in days (1-365) | | shipped_at | date | No | Date when shipped (YYYY-MM-DD) | #### Example Request ```bash curl -X POST "https://ecom-backend-api.dmi.community/api/v1/merchant/orders/1/shipments" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -d '{ "carrier": "FedEx", "status": "Preparing", "shipping_fee": 9.99, "estimated_delivery_days": 3 }' ``` #### Success Response (201 Created) ```json { "success": true, "message": "Shipment created successfully", "data": { "id": 1, "tracking_number": "TRACK123456", "carrier": "FedEx", "status": { "id": 2, "name": "Preparing" }, "shipping_fee": "9.99", "estimated_delivery_days": 3, "shipped_at": null, "delivered_at": null, "created_at": "2026-01-27T12:00:00.000000Z" } } ``` #### Error Response - Invalid Order Status (400) ```json { "success": false, "message": "Shipment can only be created for confirmed, processing, or shipped orders" } ``` --- ### Update Shipment Update shipment information including carrier and status. Tracking numbers are system-generated and immutable. **Endpoint:** `PATCH /orders/{orderId}/shipments/{shipmentId}` **Authentication:** Required (Merchant) **Rate Limit:** 30 requests/minute #### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | orderId | integer | Order ID | | shipmentId | integer | Shipment ID | #### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | carrier | string | No | Carrier name (max 100 characters) | | status | string | No | New status: `Pending`, `Preparing`, `Ready to Ship`, `Shipped`, `In Transit`, `Out for Delivery`, `Delivered`, `Failed Delivery` | | shipping_fee | decimal | No | Shipping cost | | estimated_delivery_days | integer | No | Estimated delivery in days (1-365) | | shipped_at | date | No | Date when shipped | | delivered_at | date | No | Date when delivered | #### Example Request ```bash curl -X PATCH "https://ecom-backend-api.dmi.community/api/v1/merchant/orders/1/shipments/1" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -d '{ "status": "Shipped", "carrier": "FedEx" }' ``` #### Success Response (200 OK) ```json { "success": true, "message": "Shipment updated successfully", "data": { "id": 1, "tracking_number": "TRACK123456-UPDATED", "carrier": "FedEx", "status": { "id": 3, "name": "Shipped" }, "shipping_fee": "9.99", "estimated_delivery_days": 3, "shipped_at": "2026-01-27T14:00:00.000000Z", "delivered_at": null, "created_at": "2026-01-27T12:00:00.000000Z" } } ``` > **Note:** When updating status to "Shipped", the `shipped_at` timestamp is automatically set if not already set. When updating to "Delivered", both `delivered_at` and `actual_delivery_date` are automatically set. --- ### Get Shipment Statuses Retrieve all available shipment statuses. **Endpoint:** `GET /orders/shipment-statuses` **Authentication:** Required (Merchant) **Rate Limit:** 60 requests/minute #### Example Request ```bash curl -X GET "https://ecom-backend-api.dmi.community/api/v1/merchant/orders/shipment-statuses" \ -H "Authorization: Bearer {access_token}" ``` #### Success Response (200 OK) ```json { "success": true, "message": "Shipment statuses retrieved successfully", "data": { "statuses": [ "Pending", "Preparing", "Shipped", "Delivered" ] } } ``` --- --- ## Cancel Specific Items from Order Endpoints Cancel individual items from an order without cancelling the entire order. **Endpoint:** `POST /api/v1/merchant/orders/{id}/items/cancel` **Authentication:** Required (Merchant) **Authorization:** Merchant must own the order **Request Body:** ```json { "reason": "Out of stock", "items": [ { "item_id": 123, "quantity": 2, "notes": "Supplier issue" }, { "item_id": 124, "quantity": 1 } ] } ``` **Parameters:** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | reason | string | Yes | Reason for cancellation (max 255 chars) | | items | array | Yes | Array of items to cancel (min 1 item) | | items.*.item_id | integer | Yes | Order item ID to cancel | | items.*.quantity | integer | No | Quantity to cancel (defaults to full quantity) | | items.*.notes | string | No | Additional notes (max 500 chars) | **Success Response (200):** ```json { "success": true, "message": "2 item(s) cancelled successfully", "data": { "cancelled_items": [123, 124], "total_refund_amount": 150.00, "order_status": "Processing", "errors": [] } } ``` **Note:** If all remaining (non-cancelled) items are already approved or ready, the order status is automatically updated (e.g., Pending → Confirmed, Confirmed → Processing). If the payment is still pending or processing, the payment amount is updated to match the new order total. **Error Response (400):** ```json { "success": false, "message": "Order cannot be cancelled. Only pending, confirmed, or processing orders can have items cancelled.", "errors": [] } ``` **Error Response (404):** ```json { "success": false, "message": "Order not found" } ``` **Notes:** - Only orders in Pending, Confirmed, Processing, or On Hold status can have items cancelled - Only items belonging to your vendor account can be cancelled - Stock is automatically restored for cancelled items - Order totals are recalculated automatically - If all items are cancelled, order status changes to "Cancelled" - Customer receives email notification - Partial quantity cancellation is supported **Example Use Cases:** 1. **Out of Stock:** ```json { "reason": "Item out of stock", "items": [{"item_id": 123, "quantity": 1}] } ``` 2. **Damaged Product:** ```json { "reason": "Product damaged in warehouse", "items": [{"item_id": 456, "notes": "Cannot fulfill"}] } ``` 3. **Partial Cancellation:** ```json { "reason": "Only 3 available", "items": [{"item_id": 789, "quantity": 2}] } ``` --- ## Get Order Cancellation Summary Endpoints Retrieve detailed cancellation information for an order. **Endpoint:** `GET /api/v1/merchant/orders/{id}/cancellation-summary` **Authentication:** Required (Merchant) **Authorization:** Merchant must own the order **Success Response (200):** ```json { "success": true, "data": { "total_items": 5, "cancelled_items": 2, "active_items": 3, "total_refund_amount": 150.00, "cancellations": [ { "id": 1, "item_id": 123, "product_name": "Wireless Mouse", "quantity_cancelled": 2, "refund_amount": 100.00, "reason": "Out of stock", "cancelled_by": "Merchant Name", "refund_status": "pending", "cancelled_at": "2026-01-28T10:30:00Z" } ] } } ``` **Use Cases:** - View cancellation history for an order - Check refund status - Customer support inquiries - Financial reconciliation --- ## Create Shipment (Auto-Generated Tracking) Endpoints Create a new shipment for an order. **Tracking numbers are automatically generated by the system** in the format `SHIP-YYYYMM-XXXXXX`. Merchants only need to provide the carrier name and initial status. **Endpoint:** `POST /api/v1/merchant/orders/{orderId}/shipments` **Authentication:** Required (Merchant) **Request Body:** ```json { "carrier": "DHL Express", "status": "Preparing", "shipping_fee": 15.00, "estimated_delivery_days": 3, "shipped_at": "2026-01-28T10:00:00Z" } ``` **Required Fields:** - `carrier` (string): Shipping carrier name (e.g., "DHL", "FedEx", "UPS") **Optional Fields:** - `status` (string): Initial shipment status (defaults to "Pending") - Options: "Preparing", "Ready to Ship", "Shipped", "In Transit", "Out for Delivery", "Delivered" - `shipping_fee` (decimal): Shipping cost - `estimated_delivery_days` (integer): Expected delivery time in days - `shipped_at` (datetime): Actual ship date **Important:** `tracking_number` is NOT accepted - it's auto-generated by the system and cannot be manually set. **Success Response (200):** ```json { "success": true, "message": "Shipment created successfully", "shipment": { "id": 1, "tracking_number": "SHIP-202601-000001", "carrier": "DHL Express", "status": { "id": 2, "name": "Preparing" }, "shipping_fee": "15.00", "estimated_delivery_days": 3, "shipped_at": "2026-01-28T10:00:00Z", "delivered_at": null, "created_at": "2026-01-28T10:00:00Z" } } ``` **What Happens Automatically:** 1. **Tracking Number Generated:** System creates unique tracking number (format: `SHIP-202601-000001`) 2. **Shipment Record Created:** All shipment details saved to database 3. **Child Order Status Updated:** Vendor's order status automatically syncs based on shipment status 4. **Parent Order Status Synced:** Main order status updated if any vendor ships 5. **Tracking History Created:** Initial history record for the shipment 6. **Email Notification Sent:** If status is "Shipped", customer receives email with: - Order number - Tracking number - Carrier name - Link to track order **Tracking Number Format:** - Pattern: `SHIP-YYYYMM-XXXXXX` - Example: `SHIP-202601-000001` - Sequential numbering per month - Automatically resets each month --- ## Update Shipment (Auto-Sync & Notifications) Endpoints Update an existing shipment. **Tracking numbers cannot be changed** - they are immutable once generated. Status updates trigger automatic order synchronization and email notifications. **Endpoint:** `PATCH /api/v1/merchant/orders/{orderId}/shipments/{shipmentId}` **Authentication:** Required (Merchant) **Request Body:** ```json { "status": "In Transit", "carrier": "FedEx", "shipping_fee": 20.00, "estimated_delivery_days": 2 } ``` **Updatable Fields:** - `status` (string): New shipment status - Options: "Preparing", "Ready to Ship", "Shipped", "In Transit", "Out for Delivery", "Delivered", "Failed Delivery" - `carrier` (string): Update carrier name if changed - `shipping_fee` (decimal): Update shipping cost - `estimated_delivery_days` (integer): Update estimated delivery time **Immutable Fields:** - `tracking_number`: Cannot be changed (auto-generated and permanent) **Success Response (200):** ```json { "success": true, "message": "Shipment updated successfully", "shipment": { "id": 1, "tracking_number": "SHIP-202601-000001", "carrier": "FedEx", "status": { "id": 4, "name": "In Transit" }, "shipping_fee": "20.00", "estimated_delivery_days": 2, "shipped_at": "2026-01-28T10:00:00Z", "delivered_at": null, "updated_at": "2026-01-28T11:00:00Z" } } ``` **What Happens Automatically:** 1. **Shipment Updated:** Changes saved to database 2. **Tracking History Created:** New history record for status change 3. **Timestamps Auto-Set:** - `shipped_at`: Automatically set when status changes to "Shipped" - `delivered_at`: Automatically set when status changes to "Delivered" 4. **Child Order Status Synced:** Vendor's order status updates based on shipment 5. **Parent Order Status Synced:** Main order status syncs across all vendors 6. **Email Notifications Sent:** Customer receives email for these status changes: - "Shipped" → Shipment created notification - "In Transit" → Status update notification - "Out for Delivery" → Status update notification - "Delivered" → Delivery confirmation notification - "Failed Delivery" → Delivery issue notification **Email Notification Content:** - Order number and tracking number - Old status → New status - Carrier information - Delivery date (if delivered) - Link to track order --- ## Get Order Shipments (Enhanced) Endpoints Get all shipments for an order with complete tracking history. **Endpoint:** `GET /api/v1/merchant/orders/{orderId}/shipments` **Authentication:** Required (Merchant) **Success Response (200):** ```json { "success": true, "data": { "shipments": [ { "id": 1, "tracking_number": "1Z999AA10123456784", "carrier": "FedEx", "status": { "id": 4, "name": "In Transit" }, "shipping_fee": 15.00, "shipped_at": "2026-01-28T10:00:00Z", "delivered_at": null, "estimated_delivery_days": 3, "histories": [ { "id": 2, "status_name": "In Transit", "location": "Los Angeles, CA", "description": "Package in transit", "event_time": "2026-01-28T15:00:00Z", "updated_by": "merchant" }, { "id": 1, "status_name": "Shipped", "location": "New York, NY", "description": "Shipment created with status: Shipped", "event_time": "2026-01-28T10:00:00Z", "updated_by": "merchant" } ] } ] } } ``` **New Features:** - Complete tracking timeline with `histories` array - Each history shows location, description, timestamp, and who updated it - Useful for customer support and order tracking --- ## Get Shipment Statuses Endpoints Get all available shipment statuses. **Endpoint:** `GET /api/v1/merchant/orders/shipment-statuses` **Authentication:** Required (Merchant) **Success Response (200):** ```json { "success": true, "data": { "statuses": [ {"id": 1, "name": "Pending"}, {"id": 2, "name": "Preparing"}, {"id": 8, "name": "Ready to Ship"}, {"id": 3, "name": "Shipped"}, {"id": 4, "name": "In Transit"}, {"id": 5, "name": "Out for Delivery"}, {"id": 6, "name": "Delivered"}, {"id": 7, "name": "Failed Delivery"} ] } } ``` **Merchant Control:** - Merchant can update: Pending, Preparing, Ready to Ship, Shipped - System/Courier updates: In Transit, Out for Delivery, Delivered, Failed Delivery **Status Flow:** 1. Pending → Shipment created 2. Preparing → Actively packing 3. Ready to Ship → Packed, waiting for courier pickup 4. Shipped → Courier picked up --- ## Order Management - Merchant Best Practices Endpoints ### Item Cancellation Best Practices 1. **Cancel items ASAP** - Before customer notices 2. **Provide clear reasons** - Helps customer understand 3. **Communicate proactively** - Call customer if high-value item 4. **Use partial cancellation** - Don't cancel entire order if possible 5. **Check stock before accepting** - Prevent cancellations ### Shipment Management Best Practices 1. **Create shipment immediately** - When you hand package to courier 2. **Always add tracking number** - Essential for customer confidence 3. **Update status regularly** - Keep customers informed 4. **Use correct carrier name** - Match tracking URL 5. **Add location notes** - Helps with customer inquiries ### Multi-Vendor Considerations 1. **You only see your orders** - Vendor-specific filtering 2. **Only cancel your items** - Cannot affect other vendors 3. **Your shipments only** - Each vendor manages their own 4. **Order totals auto-adjust** - System handles calculations 5. **Customer sees unified view** - Don't worry about other vendors --- ## Webhook Integration Endpoints ### Courier Tracking Webhook Receive automatic tracking updates from courier services. **Endpoint:** `POST /api/webhooks/courier/tracking` **Authentication:** None in the current code. **Webhook signature verification is not implemented**; do not expose this endpoint to an untrusted courier integration until signature verification is added. **Request from Courier:** ```json { "tracking_number": "1Z999AA10123456784", "status": "in_transit", "location": "Los Angeles, CA", "description": "Package arrived at sorting facility", "carrier": "FedEx", "event_time": "2026-01-28T15:30:00Z", "metadata": { "weight": "2.5kg", "next_stop": "Customer City" } } ``` **Response:** ```json { "success": true, "message": "Tracking updated successfully", "shipment_id": 1 } ``` **What Happens:** 1. System maps courier status to internal status 2. Creates tracking history record 3. Updates shipment status 4. If status is "Delivered": - Sets delivered_at timestamp - Checks if all shipments delivered - Updates order status to "Delivered" if yes - Sends delivery notification to customer **Security status:** The controller's signature-check code is commented out. The endpoint currently accepts unsigned requests and logs the received payload and headers. **Setup Instructions:** See [Shipment Tracking Guide](./ORDER_MANAGEMENT.md) --- ## Quick Reference Endpoints ### Common Operations | Operation | Endpoint | Method | |-----------|----------|--------| | List orders | `/api/v1/merchant/orders` | GET | | Update order status | `/api/v1/merchant/orders/{id}/status` | PATCH | | Cancel specific items | `/api/v1/merchant/orders/{id}/items/cancel` | POST | | Create shipment | `/api/v1/merchant/orders/{id}/shipments` | POST | | Update shipment | `/api/v1/merchant/orders/{id}/shipments/{id}` | PATCH | | View tracking | `/api/v1/merchant/orders/{id}/shipments` | GET | ### Status Quick Reference **Merchant Can Request These Business Transitions:** - Confirmed (from Pending) - Processing (from Confirmed) - On Hold (from Pending/Confirmed/Processing) - Cancelled (from Pending/Confirmed/Processing/On Hold) Shipment events drive the `Shipped` and `Delivered` order states; merchants cannot set these order states directly. **System Updates:** - Delivered (when all shipments delivered) - Refunded (via refund process) --- ## Quick Reference: All Order & Shipment Endpoints ### Summary of Available Endpoints All the endpoints requested by the frontend team are **already implemented and ready to use**: | Endpoint | Method | Status | Description | |----------|--------|--------|-------------| | `/api/v1/merchant/orders` | GET | ✅ Ready | List all orders with filters | | `/api/v1/merchant/orders/{id}` | GET | ✅ Ready | Get order details | | `/api/v1/merchant/orders/{id}/status` | PATCH | ✅ Ready | Update order status (Confirmed, Processing, On Hold only) | | `/api/v1/merchant/orders/{id}/cancel` | POST | ✅ Ready | Cancel entire order | | `/api/v1/merchant/orders/{id}/items/cancel` | POST | ✅ Ready | Cancel specific items (partial cancellation) | | `/api/v1/merchant/orders/{orderId}/shipments` | GET | ✅ Ready | Get all shipments for an order | | `/api/v1/merchant/orders/{orderId}/shipments` | POST | ✅ Ready | Create shipment (tracking auto-generated) | | `/api/v1/merchant/orders/{orderId}/shipments/{shipmentId}` | PATCH | ✅ Ready | Update shipment status | | `/api/v1/merchant/orders/{id}/cancellation-summary` | GET | ✅ Ready | Get cancellation summary | | `/api/v1/merchant/orders/statuses` | GET | ✅ Ready | Get available order statuses | | `/api/v1/merchant/orders/shipment-statuses` | GET | ✅ Ready | Get available shipment statuses | --- ### Complete Endpoint Details #### 1. GET Order Shipments **Endpoint:** `GET /api/v1/merchant/orders/{orderId}/shipments` **Description:** Retrieve all shipments for a specific order with auto-generated tracking numbers. **Authentication:** Required (Merchant Bearer Token) **Path Parameters:** - `orderId` (integer, required) - The order ID **Request Example:** ```bash curl -X GET "https://your-api.com/api/v1/merchant/orders/123/shipments" \ -H "Authorization: Bearer {token}" \ -H "Accept: application/json" ``` **Success Response (200 OK):** ```json { "success": true, "message": "Shipments retrieved successfully", "data": { "order_id": 123, "order_number": "ORD-12345", "shipments": [ { "id": 1, "tracking_number": "SHIP-202601-000001", "carrier": "DHL Express", "status": { "id": 3, "name": "Shipped" }, "shipping_fee": "15.00", "estimated_delivery_days": 3, "shipped_at": "2026-01-28T10:00:00Z", "delivered_at": null, "created_at": "2026-01-28T09:00:00Z" } ] } } ``` **Error Response (404 Not Found):** ```json { "success": false, "message": "Order not found" } ``` **Notes:** - Returns empty array if no shipments exist - Tracking numbers are auto-generated (SHIP-YYYYMM-XXXXXX format) - Only returns shipments for orders belonging to the authenticated merchant --- #### 2. POST Create Shipment (Auto-Generated Tracking) **Endpoint:** `POST /api/v1/merchant/orders/{orderId}/shipments` **Description:** Create a new shipment with auto-generated tracking number. Email notification sent to customer if status is "Shipped". **Authentication:** Required (Merchant Bearer Token) **Path Parameters:** - `orderId` (integer, required) - The order ID **Request Body:** ```json { "carrier": "DHL Express", "status": "Preparing", "shipping_fee": 15.00, "estimated_delivery_days": 3, "shipped_at": "2026-01-28T10:00:00Z" } ``` **Required Fields:** - `carrier` (string) - Shipping carrier name **Optional Fields:** - `status` (string) - Initial shipment status (defaults to "Pending") - Options: "Preparing", "Ready to Ship", "Shipped", "In Transit", "Out for Delivery", "Delivered" - `shipping_fee` (decimal) - Shipping cost - `estimated_delivery_days` (integer) - Estimated delivery time - `shipped_at` (datetime) - Ship date **IMPORTANT:** Do NOT include `tracking_number` - it's auto-generated by the system! **Request Example:** ```bash curl -X POST "https://your-api.com/api/v1/merchant/orders/123/shipments" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "carrier": "DHL Express", "status": "Shipped", "shipping_fee": 15.00, "estimated_delivery_days": 3 }' ``` **Success Response (201 Created):** ```json { "success": true, "message": "Shipment created successfully", "data": { "id": 1, "tracking_number": "SHIP-202601-000001", "carrier": "DHL Express", "status": { "id": 3, "name": "Shipped" }, "shipping_fee": "15.00", "estimated_delivery_days": 3, "shipped_at": null, "delivered_at": null, "created_at": "2026-01-28T10:00:00Z" } } ``` **What Happens Automatically:** 1. ✅ Tracking number generated: `SHIP-202601-000001` 2. ✅ Shipment record created in database 3. ✅ Child order status updated based on shipment status 4. ✅ Parent order status synced across all vendors 5. ✅ Tracking history record created 6. ✅ Email sent to customer (if status is "Shipped") **Error Response (400 Bad Request):** ```json { "success": false, "message": "Shipment can only be created for confirmed, processing, prepared, ready to ship, or shipped orders" } ``` --- #### 3. PATCH Update Shipment **Endpoint:** `PATCH /api/v1/merchant/orders/{orderId}/shipments/{shipmentId}` **Description:** Update an existing shipment. Tracking number cannot be changed (immutable). Email notification sent for important status changes. **Authentication:** Required (Merchant Bearer Token) **Path Parameters:** - `orderId` (integer, required) - The order ID - `shipmentId` (integer, required) - The shipment ID **Request Body:** ```json { "status": "In Transit", "carrier": "FedEx", "shipping_fee": 20.00, "estimated_delivery_days": 2 } ``` **Updatable Fields:** - `status` (string) - Shipment status - Options: "Preparing", "Ready to Ship", "Shipped", "In Transit", "Out for Delivery", "Delivered", "Failed Delivery" - `carrier` (string) - Carrier name - `shipping_fee` (decimal) - Shipping cost - `estimated_delivery_days` (integer) - Estimated delivery time - `shipped_at` (datetime) - Ship date - `delivered_at` (datetime) - Delivery date **IMMUTABLE Field:** - `tracking_number` - Cannot be changed (auto-generated and permanent) **Request Example:** ```bash curl -X PATCH "https://your-api.com/api/v1/merchant/orders/123/shipments/1" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "status": "Delivered" }' ``` **Success Response (200 OK):** ```json { "success": true, "message": "Shipment updated successfully", "data": { "id": 1, "tracking_number": "SHIP-202601-000001", "carrier": "DHL Express", "status": { "id": 6, "name": "Delivered" }, "shipping_fee": "15.00", "estimated_delivery_days": 3, "shipped_at": "2026-01-28T10:00:00Z", "delivered_at": "2026-01-28T15:30:00Z", "created_at": "2026-01-28T10:00:00Z" } } ``` **What Happens Automatically:** 1. ✅ Shipment updated in database 2. ✅ Tracking history record created 3. ✅ `shipped_at` auto-set when status → "Shipped" 4. ✅ `delivered_at` auto-set when status → "Delivered" 5. ✅ Child order status synced from shipment 6. ✅ Parent order status synced across vendors 7. ✅ Email sent to customer for: Shipped, In Transit, Out for Delivery, Delivered, Failed Delivery **Error Response (404 Not Found):** ```json { "success": false, "message": "Shipment not found" } ``` --- #### 4. POST Cancel Order **Endpoint:** `POST /api/v1/merchant/orders/{id}/cancel` **Description:** Cancel an entire order and restore stock. **Authentication:** Required (Merchant Bearer Token) **Path Parameters:** - `id` (integer, required) - The order ID **Request Body:** ```json { "reason": "Customer requested cancellation" } ``` **Required Fields:** - `reason` (string) - Cancellation reason **Request Example:** ```bash curl -X POST "https://your-api.com/api/v1/merchant/orders/123/cancel" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "reason": "Customer requested cancellation" }' ``` **Success Response (200 OK):** ```json { "success": true, "message": "Order cancelled successfully", "data": { "id": 123, "order_number": "ORD-12345", "status": { "id": 7, "name": "Cancelled" }, "cancellation": { "reason": "Customer requested cancellation", "cancelled_by": "Merchant Name", "cancelled_by_type": "vendor", "refund_amount": "150.00", "refund_status": "pending", "cancelled_at": "2026-01-28T12:00:00Z" } } } ``` **What Happens Automatically:** 1. ✅ Order status changed to "Cancelled" 2. ✅ Cancellation record created 3. ✅ Stock restored for all items 4. ✅ Refund marked as pending **Error Response (400 Bad Request):** ```json { "success": false, "message": "Order cannot be cancelled. Only pending, confirmed, processing, or on hold orders can be cancelled." } ``` **Cancellable Statuses:** - Pending - Confirmed - Processing - On Hold **Non-Cancellable Statuses:** - Shipped - Delivered - Already Cancelled --- #### 5. POST Cancel Items (Partial Cancellation) **Endpoint:** `POST /api/v1/merchant/orders/{id}/items/cancel` **Description:** Cancel specific items from an order (partial cancellation). **Authentication:** Required (Merchant Bearer Token) **Path Parameters:** - `id` (integer, required) - The order ID **Request Body:** ```json { "reason": "Out of stock", "items": [ { "item_id": 456, "quantity": 2, "notes": "Will restock next week" }, { "item_id": 457, "quantity": 1 } ] } ``` **Required Fields:** - `reason` (string) - Cancellation reason - `items` (array) - Array of items to cancel - `item_id` (integer) - Order item ID - `quantity` (integer, optional) - Quantity to cancel (defaults to all) - `notes` (string, optional) - Additional notes **Request Example:** ```bash curl -X POST "https://your-api.com/api/v1/merchant/orders/123/items/cancel" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "reason": "Out of stock", "items": [ { "item_id": 456, "quantity": 2 } ] }' ``` **Success Response (200 OK):** ```json { "success": true, "message": "Items cancelled successfully", "data": { "order_id": 123, "cancelled_items": [ { "item_id": 456, "quantity_cancelled": 2, "refund_amount": "40.00" } ], "total_refund": "40.00", "order_updated": true } } ``` **What Happens Automatically:** 1. ✅ Item quantities updated 2. ✅ Cancellation records created 3. ✅ Stock restored for cancelled quantities 4. ✅ Order totals recalculated 5. ✅ Refund amounts calculated 6. ✅ Customer notified via email --- ### Frontend Integration Checklist **Before Building:** - [x] All required endpoints exist and are documented - [x] Auto-generated tracking number system explained - [x] Email notification triggers documented - [x] Order status sync behavior clarified - [x] Request/response examples provided **Required API Headers:** ```javascript const headers = { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json', 'Accept': 'application/json' }; ``` **Base URL:** ``` https://your-api-domain.com/api/v1/merchant ``` **Important Notes for Frontend:** 1. ✅ Do NOT include `tracking_number` in create shipment requests 2. ✅ Tracking numbers are read-only (cannot update) 3. ✅ Order status "Shipped" and "Delivered" cannot be set manually 4. ✅ Use shipment status to control order progression 5. ✅ Email notifications are automatic for key events 6. ✅ Parent order status syncs automatically --- *Documentation Last Updated: November 10, 2026* *All endpoints tested and production-ready* --- #### 6. PATCH Update Order Item Status (NEW) **Endpoint:** `PATCH /api/v1/merchant/orders/{orderId}/items/{itemId}/status` **Description:** Update the status of a specific item in an order. Useful for approving/accepting specific items individually rather than the entire order at once. **Authentication:** Required (Merchant Bearer Token) **Path Parameters:** - `orderId` (integer, required) - The order ID - `itemId` (integer, required) - The order item ID **Request Body:** ```json { "status": "approved", "notes": "Item verified and ready to prepare" } ``` **Required Fields:** - `status` (string) - New item status - Options: "pending", "approved", "preparing", "ready", "cancelled" **Optional Fields:** - `notes` (string) - Optional notes about the status change **Request Example:** ```bash curl -X PATCH "https://your-api.com/api/v1/merchant/orders/123/items/456/status" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "status": "approved" }' ``` **Success Response (200 OK):** ```json { "success": true, "message": "Item status updated successfully", "data": { "item_id": 456, "old_status": "pending", "new_status": "approved", "order_status": "Confirmed" } } ``` **What Happens Automatically:** 1. **Item Status Updated:** Individual item status changed 2. **Order Status Auto-Sync:** Order status updates based on item statuses: - All items **approved** → Order = **Confirmed** - All items **preparing** or **ready** → Order = **Processing** 3. **Validation:** Cannot update status of cancelled items **Item Status Flow:** ``` pending → approved → preparing → ready ↓ cancelled (if needed) ``` **Order Auto-Update Rules:** | When | Then Order Status Becomes | |------|--------------------------| | All items = approved/preparing/ready | Confirmed | | All items = preparing/ready | Processing | | Mixed statuses | Remains current status | **Use Cases:** 1. **Accept Specific Items:** ``` Customer orders 3 items, you have 2 in stock: - Approve items 1 & 2 - Cancel item 3 ``` 2. **Gradual Processing:** ``` Process items as they're ready: - Item 1: pending → approved → preparing → ready - Item 2: pending → approved → preparing → ready ``` 3. **Quality Control:** ``` Check each item individually: - Inspect item → Approve if OK - Update to preparing when starting work - Update to ready when packed ``` **Error Response (400 Bad Request):** ```json { "success": false, "message": "Cannot update status of cancelled item" } ``` **Error Response (404 Not Found):** ```json { "success": false, "message": "Order item not found" } ``` **Notes:** - Items can be managed independently - Order status auto-updates based on all items' statuses - Cannot update cancelled items - Helps track granular order fulfillment progress --- ### Item Status vs Order Status **Understanding the Relationship:** ``` ORDER STATUS (Overall) ITEM STATUS (Individual) ================== ======================= Pending → pending (all items) → approved (you accept this item) Confirmed (auto) ← approved (all items approved) → preparing (you're preparing this item) Processing (auto) ← preparing/ready (all items in progress) → Create shipment when ready Shipped (via shipment) ← Shipment created Delivered (via shipment) ← Shipment delivered ``` **Example Workflow:** ```javascript // 1. Order arrives with 3 items, all "pending" GET /orders/123 → Order Status: Pending → Item 1: pending → Item 2: pending → Item 3: pending // 2. Accept/approve Item 1 PATCH /orders/123/items/1/status Body: { "status": "approved" } → Item 1: approved → Order: Still Pending (not all approved) // 3. Approve items 2 & 3 PATCH /orders/123/items/2/status {"status": "approved"} PATCH /orders/123/items/3/status {"status": "approved"} → All items: approved → Order: Confirmed (auto-updated) ✓ // 4. Start preparing items PATCH /orders/123/items/1/status {"status": "preparing"} PATCH /orders/123/items/2/status {"status": "preparing"} PATCH /orders/123/items/3/status {"status": "preparing"} → All items: preparing → Order: Processing (auto-updated) ✓ // 5. Items ready, create shipment POST /orders/123/shipments Body: { "carrier": "DHL", "status": "Shipped" } → Order: Shipped (auto-updated) ✓ → Email sent to customer ✓ ``` --- *Documentation Last Updated: November 10, 2026* *Item-level status management added for granular control* --- ## Company-Managed Delivery System Endpoints ### Overview The system now supports **automatic shipment creation** for company-managed delivery. When merchants approve all items in an order, a shipment is automatically created with the company's internal delivery team. ### Updated Item Status Workflow **Endpoint:** `PATCH /api/v1/merchant/orders/{orderId}/items/{itemId}/status` **New Automatic Behaviors:** #### When All Items Approved: ```json Request: PATCH /orders/123/items/1/status Body: { "status": "approved" } If this is the last item to approve: → Shipment automatically created → Tracking: SHIP-202601-000001 (auto-generated) → Carrier: [Your Company] Delivery Team → Status: "Preparing" → Order Status: Confirmed ``` #### When All Items Ready: ```json Request: PATCH /orders/123/items/1/status Body: { "status": "ready" } If this is the last item to mark ready: → Shipment automatically updated to "Ready to Ship" → Order Status: Processing → Ready for delivery team pickup ``` ### Complete Flow Example ```javascript // Step 1: Merchant approves items PATCH /api/v1/merchant/orders/123/items/1/status Body: { "status": "approved" } PATCH /api/v1/merchant/orders/123/items/2/status Body: { "status": "approved" } Response (when last item approved): { "success": true, "message": "Item status updated successfully", "data": { "item_id": 2, "new_status": "approved", "order_status": "Confirmed", "shipment_created": true, "tracking_number": "SHIP-202601-000001" } } // Step 2: Merchant marks items ready (after packaging) PATCH /api/v1/merchant/orders/123/items/1/status Body: { "status": "ready" } PATCH /api/v1/merchant/orders/123/items/2/status Body: { "status": "ready" } Response (when last item ready): { "success": true, "message": "Item status updated successfully", "data": { "item_id": 2, "new_status": "ready", "order_status": "Processing", "shipment_updated": true, "shipment_status": "Ready to Ship" } } // Step 3: Delivery team picks up and ships PATCH /api/v1/merchant/orders/123/shipments/1 Body: { "status": "Shipped" } // Step 4: Delivery team delivers PATCH /api/v1/merchant/orders/123/shipments/1 Body: { "status": "Delivered" } ``` ### Important Changes **Before (Manual Shipment Creation):** ``` 1. Items approved 2. Merchant manually creates shipment 3. Merchant provides carrier info 4. Merchant updates to shipped ``` **Now (Automatic for Company Delivery):** ``` 1. Items approved → Shipment AUTO-CREATED ✨ 2. Items ready → Shipment AUTO-UPDATED to Ready to Ship ✨ 3. Delivery team updates to shipped 4. Delivery team updates to delivered ``` ### Carrier Information **Auto-Set Carrier:** - Carrier name: `[Your Application Name] Delivery Team` - Example: "Laravel Delivery Team" - Configured from: `config('app.name')` **To Customize:** Update `.env` file: ```env APP_NAME="Your Company Name" ``` Carrier will be: "Your Company Name Delivery Team" ### API Response Updates The `updateItemStatus` response now includes additional fields when automatic actions occur: ```json { "success": true, "data": { "item_id": 456, "old_status": "pending", "new_status": "approved", "order_status": "Confirmed", // New fields when shipment auto-created "shipment_created": true, "tracking_number": "SHIP-202601-000001", "carrier": "Your Company Delivery Team", // New fields when shipment auto-updated "shipment_updated": true, "shipment_status": "Ready to Ship" } } ``` ### Merchant Responsibilities **What Merchants Do:** ✅ Approve items individually as stock verified ✅ Mark items as "ready" when packaged ✅ System handles shipment creation automatically **What Merchants DON'T Do:** ❌ Manually create shipments ❌ Choose carriers ❌ Generate tracking numbers ❌ Update shipment to "Shipped" (delivery team does this) ### Delivery Team Responsibilities **What Delivery Team Does:** ✅ Pick up packages marked "Ready to Ship" ✅ Update shipment to "Shipped" when picked up ✅ Update shipment to "Delivered" when completed ### Frontend UI Updates Needed **Order Items List:** ```jsx {items.map(item => (

{item.product.name}

Status: {item.status}

{item.status === 'pending' && ( )} {item.status === 'approved' && ( )} {item.status === 'ready' && ( ✅ Ready for Pickup )}

))} {/* Show shipment info when auto-created */} {order.shipments.length > 0 && (

📦 Shipment Created

Tracking: {order.shipments[0].tracking_number}

Carrier: {order.shipments[0].carrier}

Status: {order.shipments[0].status.name}

)} ``` --- *Company-Managed Delivery Documentation - Last Updated: November 10, 2026* --- ## Marketing Management Endpoints All routes below are prefixed by `/api/v1/merchant/marketing` and require an authenticated active `goods` merchant. Campaign and coupon writes are scoped to the current merchant. Clients must not submit ownership or actor fields such as `campaign_owner_type`, `owner_type`, `vendor_id`, or `created_by`. Merchant campaigns are storefront promotions and are not global home placements. See [Marketing Campaign Ownership Contract](#marketing-campaign-ownership-contract). ### Campaigns | Method | Endpoint | Purpose | | --- | --- | --- | | `GET` | `/campaigns` | List campaigns; filters: `status`, `campaign_type`, `is_featured`, `search`, `per_page` (default 15) | | `POST` | `/campaigns` | Create a campaign | | `GET` | `/campaigns/{id}` | Get a merchant-owned campaign | | `PUT` | `/campaigns/{id}` | Update a merchant-owned campaign | | `DELETE` | `/campaigns/{id}` | Delete a campaign | | `POST` | `/campaigns/{id}/publish` | Publish campaign | | `POST` | `/campaigns/{id}/pause` | Pause campaign | | `POST` | `/campaigns/{id}/resume` | Resume campaign | | `POST` | `/campaigns/{id}/complete` | Complete campaign | | `POST` | `/campaigns/{id}/cancel` | Cancel campaign | | `POST` | `/campaigns/{id}/request-review` | Request campaign review | | `PUT` | `/campaigns/{id}/products` | Replace campaign products (`products` or `product_ids`) | | `POST` | `/campaigns/{id}/assets` | Upload image files or set asset URLs | | `POST` | `/campaigns/{id}/preview-link` | Issue a temporary preview link | Campaign creation requires `name`, `campaign_type`, `start_date`, and `end_date` (after `start_date`). Optional product entries use `product_id` with campaign pricing, quantity, and display fields; `product_ids` is accepted as shorthand. For preview links, optional `expires_in_minutes` is 15–10080 (default 1440). For `/campaigns/{id}/assets`, use `multipart/form-data` for `banner_image`, `mobile_banner_image`, or `thumbnail_image`, or send the corresponding `*_url` fields. At least one asset is required. The issued URL is consumed through the public customer preview endpoint with its `token` query parameter. ### Coupons, Audiences, and Analytics | Method | Endpoint | Purpose | | --- | --- | --- | | `GET` | `/coupons` | List coupons; filters: `type`, `status`, `search`, `per_page` (default 15) | | `POST` | `/coupons` | Create a coupon | | `PUT` | `/coupons/{couponId}` | Update a coupon | | `DELETE` | `/coupons/{couponId}` | Delete a coupon | | `GET` | `/audiences` | List audience segments | | `POST` | `/audiences/refresh` | Refresh due segments or selected `segment_ids` | | `GET` | `/analytics` | Campaign analytics; optional `date_from`, `date_to`, `campaign_id` | Coupon creation requires `code`, `type`, `discount`, `valid_from`, and `valid_to` (after `valid_from`). Codes are normalized to uppercase. Optional limits and applicable category/product ID arrays are supported. Update fields are optional; a changed `code` must remain unique. Audience refresh accepts an optional array of existing `segment_ids`; omit it to refresh all due segments. Analytics rejects `date_to` earlier than `date_from`. ## Visa Services Endpoints Merchant Visa APIs support visa catalog operations (countries/types) and operational queue handling for customer visa applications. All endpoints in this section are prefixed with `/api/v1/merchant/visa`. ### Access Requirements All Visa merchant endpoints require: - valid merchant authentication (`auth:sanctum`) - active merchant profile (`merchant` middleware) - merchant type includes `visa` (`merchant-type:visa`) - permission `manage visa applications` (enforced in controller) #### Permission Error (403 Forbidden) ```json { "success": false, "message": "You do not have permission to manage visa applications." } ``` --- ### 1. Dashboard Summary Retrieve queue totals and latest visible applications. **Endpoint:** `GET /visa/dashboard` **Authentication:** Required (Merchant Visa) **Rate Limit:** 60 requests/minute #### Success Response (200 OK) ```json { "success": true, "message": "Visa dashboard retrieved successfully", "data": { "summary": { "all_visible_total": 12, "my_queue_total": 7, "unassigned_total": 5, "visa_type_count": 3, "active_visa_type_count": 2, "submitted_count": 4, "under_review_count": 3, "embassy_processing_count": 2, "approved_count": 2, "rejected_count": 1, "cancelled_count": 0 }, "recent_applications": [] } } ``` --- ### 2. Status Reference Retrieve supported visa statuses and allowed transitions map. **Endpoint:** `GET /visa/statuses` **Authentication:** Required (Merchant Visa) **Rate Limit:** 60 requests/minute #### Success Response (200 OK) ```json { "success": true, "message": "Visa statuses retrieved successfully", "data": { "statuses": [ "pending_payment", "paid", "awaiting_documents", "submitted", "under_review", "embassy_processing", "approved", "rejected", "cancelled" ], "transitions": { "submitted": ["under_review", "cancelled"], "under_review": ["embassy_processing", "approved", "rejected", "cancelled"] } } } ``` --- ### 3. List Visa Countries Retrieve country references for creating and filtering visa types. **Endpoint:** `GET /visa/countries` **Authentication:** Required (Merchant Visa) **Rate Limit:** 60 requests/minute --- ### 4. Create Visa Country Create a visa country record. If a country with the same code already exists, the existing record is returned. **Endpoint:** `POST /visa/countries` **Authentication:** Required (Merchant Visa) **Rate Limit:** 30 requests/minute #### Request Body | Field | Type | Required | Rules | |-------|------|----------|-------| | name | string | Yes | max 255 | | code | string | Yes | exactly 2 letters (`alpha`) | | flag_emoji | string | No | max 20 | | processing_days_min | integer | No | min 1, max 60 | | processing_days_max | integer | No | min 1, max 90, `>= processing_days_min` | | description | string | No | max 2000 | | requirements_summary | array | No | max 20 items, each max 255 chars | --- ### 5. List Visa Types List visa types owned by current merchant. **Endpoint:** `GET /visa/types` **Authentication:** Required (Merchant Visa) **Rate Limit:** 60 requests/minute #### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | country_id | string | No | Filter by country id | | is_active | boolean | No | Filter by active/inactive | | search | string | No | Search name/description/country | | per_page | integer | No | 1-50 (default: 15) | --- ### 6. Create Visa Type Create a merchant-owned visa offering that becomes visible to customer Visa APIs when active. **Endpoint:** `POST /visa/types` **Authentication:** Required (Merchant Visa) **Rate Limit:** 30 requests/minute #### Request Body | Field | Type | Required | Rules | |-------|------|----------|-------| | country_id | string | Yes | must exist in `visa_countries.id` | | name | string | Yes | max 255 | | description | string | No | max 2000 | | service_fee_usd | number | Yes | min 0, max 999999.99 | | government_fee_usd | number | No | min 0, max 999999.99 | | currency | string | No | 3 chars, normalized uppercase | | validity_days | integer | No | 1-3650 | | max_stay_days | integer | No | 1-3650 | | is_recommended | boolean | No | default false | | is_active | boolean | No | default true | | required_documents | array | Yes | min 1 item; lowercase `snake_case` keys | | application_questions | array

Backend routes present