API Documentation

Complete API reference for integrating with ArkifiCommerce. Build powerful e-commerce applications with our RESTful API.

Quick Navigation

Getting Started

Base URL
All API requests should be made to: https://ecommerce.arkifi.store/api

Required Headers

Every API request requires the following headers:

Header Type Required Description
x-api-key string Yes Your platform API key. Get this from your business dashboard.
Content-Type string Yes Set to application/json for JSON requests, or multipart/form-data for file uploads.
Authorization string Conditional Bearer token for authenticated endpoints. Format: Bearer {token}
Example: cURL Request 
curl -X POST https://your-api-domain.com/api/customer/register \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "john.doe@example.com",
    "password": "SecurePass123",
    "transactionPin": "1234"
  }'

Authentication

Most endpoints require authentication using a JWT Bearer token. After successful login, you'll receive a token that should be included in the Authorization header for subsequent requests.

Important
Tokens expire after a set period. If you receive a 401 Unauthorized response, you'll need to login again to get a new token.
Example: Authenticated Request 
curl -X GET https://your-api-domain.com/api/customer/get-card-balance \
  -H "x-api-key: your-api-key-here" \
  -H "Authorization: Bearer your-jwt-token-here"

Register Customer

POST /api/customer/register

Register a new customer account. After successful registration, an email verification OTP will be sent to the provided email address.

Request Body
Parameter Type Required Description
firstName string Yes Customer's first name (max 100 characters)
lastName string Yes Customer's last name (max 100 characters)
emailAddress string Yes Valid email address (max 255 characters)
phoneNumber string Yes Customer's phone number (max 20 characters)
password string Yes Password (minimum 6 characters)
transactionPin string Yes 4-digit transaction PIN (exactly 4 digits)
Request Example 
POST /api/customer/register
Headers:
  x-api-key: your-api-key-here
  Content-Type: application/json

Body:
{
  "firstName": "John",
  "lastName": "Doe",
  "emailAddress": "john.doe@example.com",
  "phoneNumber": "+2348012345678",
  "password": "SecurePass123",
  "transactionPin": "1234"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Registration successful. Please check your email for verification code.",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "john.doe@example.com",
    "phoneNumber": "+2348012345678",
    "shoppingCardNo": "ARK12345",
    "isEmailVerified": false,
    "isNinVerified": false,
    "isBvnVerified": false,
    "isLivenessVerified": false,
    "allowMerchantAccess": false,
    "dateCreated": "2025-01-15T10:30:00Z",
    "dateUpdated": "2025-01-15T10:30:00Z"
  }
}
Error Response (400 Bad Request)
Status: 400 Bad Request
{
  "success": false,
  "message": "Email address already exists",
  "data": null
}

Login Customer

POST /api/customer/login

Authenticate a customer and receive a JWT token for subsequent API requests. The customer can login using either their email address or phone number.

Request Body
Parameter Type Required Description
emailOrPhone string Yes Customer's email address or phone number
password string Yes Customer's password
Request Example 
POST /api/customer/login
Headers:
  x-api-key: your-api-key-here
  Content-Type: application/json

Body:
{
  "emailOrPhone": "john.doe@example.com",
  "password": "SecurePass123"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Login successful",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "john.doe@example.com",
    "phoneNumber": "+2348012345678",
    "shoppingCardNo": "ARK12345",
    "isEmailVerified": true,
    "isNinVerified": false,
    "isBvnVerified": false,
    "isLivenessVerified": false,
    "allowMerchantAccess": false,
    "lastLogin": "2025-01-15T10:30:00Z",
    "dateCreated": "2025-01-15T08:00:00Z",
    "dateUpdated": "2025-01-15T10:30:00Z",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresAt": "2025-01-15T18:30:00Z"
  }
}
Error Response (400 Bad Request)
Status: 400 Bad Request
{
  "success": false,
  "message": "Invalid email/phone or password",
  "data": null
}
Token Usage
Store the token from the response and include it in the Authorization header for authenticated requests: Authorization: Bearer {token}

Email Verification

POST /api/customer/verify-email

Verify a customer's email address using the OTP code sent to their email after registration.

Request Body
Parameter Type Required Description
email string Yes Customer's email address
otp string Yes 6-digit OTP code sent to email
Request Example 
POST /api/customer/verify-email
Headers:
  x-api-key: your-api-key-here
  Content-Type: application/json

Body:
{
  "email": "john.doe@example.com",
  "otp": "123456"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Email verified successfully",
  "data": true
}
POST /api/customer/resend-email-verification

Resend the email verification OTP code to the customer's email address.

Request Body
Parameter Type Required Description
email string Yes Customer's email address
Request Example 
POST /api/customer/resend-email-verification
Headers:
  x-api-key: your-api-key-here
  Content-Type: application/json

Body:
{
  "email": "john.doe@example.com"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "OTP sent successfully",
  "data": {
    "message": "Verification code sent to john.doe@example.com",
    "expiresAt": "2025-01-15T10:35:00Z"
  }
}

Forgot Password

The forgot password flow consists of 4 steps: Send OTP → Verify OTP → Reset Password. Follow these endpoints in sequence.

POST /api/customer/forgot-password

Step 1: Send an OTP code to the customer's email address to initiate password reset.

Request Body
Parameter Type Required Description
email string Yes Customer's email address
Request Example 
POST /api/customer/forgot-password
Headers:
  x-api-key: your-api-key-here
  Content-Type: application/json

Body:
{
  "email": "john.doe@example.com"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "OTP sent successfully",
  "data": {
    "message": "Password reset OTP sent successfully to john.doe@example.com",
    "expiresAt": "2025-01-15T10:35:00Z"
  }
}
POST /api/customer/resend-forgot-password

Resend the forgot password OTP code if the customer didn't receive it or it expired.

Request Body
Parameter Type Required Description
email string Yes Customer's email address
Request Example 
POST /api/customer/resend-forgot-password
Headers:
  x-api-key: your-api-key-here
  Content-Type: application/json

Body:
{
  "email": "john.doe@example.com"
}
POST /api/customer/verify-forgot-password-otp

Step 2: Verify the OTP code received via email. This returns a reset token that will be used in the next step.

Request Body
Parameter Type Required Description
email string Yes Customer's email address
otp string Yes 6-digit OTP code sent to email
Request Example 
POST /api/customer/verify-forgot-password-otp
Headers:
  x-api-key: your-api-key-here
  Content-Type: application/json

Body:
{
  "email": "john.doe@example.com",
  "otp": "123456"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "OTP verified successfully",
  "data": {
    "resetToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresAt": "2025-01-15T11:30:00Z"
  }
}
Important
Save the resetToken from this response. You'll need it in the next step to reset the password.
POST /api/customer/reset-password?resetToken={token}

Step 3: Reset the customer's password using the reset token obtained from OTP verification.

Query Parameters
Parameter Type Required Description
resetToken string Yes Reset token from OTP verification step
Request Body
Parameter Type Required Description
newPassword string Yes New password (minimum 6 characters)
Request Example 
POST /api/customer/reset-password?resetToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Headers:
  x-api-key: your-api-key-here
  Content-Type: application/json

Body:
{
  "newPassword": "NewSecurePass123"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Password reset successfully",
  "data": true
}
Error Response (400 Bad Request)
Status: 400 Bad Request
{
  "success": false,
  "message": "Invalid or expired reset token",
  "data": false
}

Get Card Balance

GET /api/customer/get-card-balance Auth Required

Get the shopping card balance for the authenticated customer. This endpoint requires a valid JWT token.

Request Example 
GET /api/customer/get-card-balance
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Card balance retrieved successfully",
  "data": {
    "customerId": "550e8400-e29b-41d4-a716-446655440000",
    "shoppingCardNo": "ARK12345",
    "currentBalance": 5000.00,
    "previousBalance": 3000.00,
    "lastUpdated": "2025-01-15T10:30:00Z",
    "currency": "NGN"
  }
}
Error Response (401 Unauthorized)
Status: 401 Unauthorized
{
  "success": false,
  "message": "Customer not authenticated",
  "data": null
}

Get Customer By ID

Note
This endpoint is typically used for admin/backend operations. For customer-facing applications, use GET /api/customerprofile/profile which automatically uses the authenticated customer's ID from the JWT token.
GET /api/customer/{customerId}

Get customer information by customer ID. This endpoint requires business ID, platform ID, and environment type as query parameters to identify the customer in the correct environment.

Path Parameters
Parameter Type Required Description
customerId string (GUID) Yes Customer's unique identifier
Query Parameters
Parameter Type Required Description
businessId string (GUID) Yes Business ID associated with the customer
platformId string (GUID) Yes Platform ID associated with the customer
environmentType integer Yes Environment type: 1 = Test, 2 = Live
Request Example 
GET /api/customer/550e8400-e29b-41d4-a716-446655440000?businessId=123e4567-e89b-12d3-a456-426614174000&platformId=789e0123-e89b-12d3-a456-426614174000&environmentType=1
Headers:
  x-api-key: your-api-key-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Customer retrieved successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "john.doe@example.com",
    "phoneNumber": "+2348012345678",
    "shoppingCardNo": "ARK12345",
    "isEmailVerified": true,
    "isNinVerified": false,
    "isBvnVerified": false,
    "isLivenessVerified": false,
    "allowMerchantAccess": false,
    "dateCreated": "2025-01-15T08:00:00Z",
    "dateUpdated": "2025-01-15T10:30:00Z",
    "lastLogin": "2025-01-15T10:30:00Z"
  }
}
Error Response (400 Bad Request)
Status: 400 Bad Request
{
  "success": false,
  "message": "Customer not found in this environment",
  "data": null
}
Alternative for Customer-Facing Apps
For customer-facing applications where the user is authenticated, use GET /api/customerprofile/profile instead. This endpoint automatically extracts the customer ID from the JWT token and doesn't require query parameters. See the Customer Profile section below.

Customer Profile

Manage customer profile information. All endpoints in this section require authentication via JWT Bearer token. The customer ID is automatically extracted from the JWT token, so you don't need to pass it in the request.

GET /api/customerprofile/profile Auth Required

Get the authenticated customer's profile information. This endpoint automatically extracts the customer ID from the JWT token, making it perfect for customer-facing applications.

Request Example 
GET /api/customerprofile/profile
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Customer profile retrieved successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "john.doe@example.com",
    "phoneNumber": "+2348012345678",
    "shoppingCardNo": "ARK12345",
    "isEmailVerified": true,
    "isNinVerified": false,
    "isBvnVerified": false,
    "isLivenessVerified": false,
    "allowMerchantAccess": false,
    "dateCreated": "2025-01-15T08:00:00Z",
    "dateUpdated": "2025-01-15T10:30:00Z",
    "lastLogin": "2025-01-15T10:30:00Z"
  }
}
Error Response (401 Unauthorized)
Status: 401 Unauthorized
{
  "success": false,
  "message": "Customer not authenticated",
  "data": null
}
PUT /api/customer/update-customer Auth Required

Update the authenticated customer's information. You can update any combination of fields. The customer ID is automatically extracted from the JWT token.

Request Body

Note: All fields are optional for updates. Only include the fields you want to update. However, if you include password or transactionPin, they must meet their respective requirements.

Parameter Type Required Description
firstName string No Customer's first name (max 100 characters)
lastName string No Customer's last name (max 100 characters)
emailAddress string No Valid email address (max 255 characters)
phoneNumber string No Customer's phone number (max 20 characters)
password string No New password (minimum 6 characters). Only include if updating password.
transactionPin string No New transaction PIN (exactly 4 digits). Only include if updating PIN.
Request Example 
PUT /api/customer/update-customer
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+2348098765432"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Customer updated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "firstName": "Jane",
    "lastName": "Smith",
    "emailAddress": "john.doe@example.com",
    "phoneNumber": "+2348098765432",
    "shoppingCardNo": "ARK12345",
    "isEmailVerified": true,
    "isNinVerified": false,
    "isBvnVerified": false,
    "isLivenessVerified": false,
    "allowMerchantAccess": false,
    "dateCreated": "2025-01-15T08:00:00Z",
    "dateUpdated": "2025-01-15T11:00:00Z",
    "lastLogin": "2025-01-15T10:30:00Z"
  }
}
Error Response (400 Bad Request)
Status: 400 Bad Request
{
  "success": false,
  "message": "Email address already exists",
  "data": null
}
Error Response (401 Unauthorized)
Status: 401 Unauthorized
{
  "success": false,
  "message": "Customer not authenticated",
  "data": null
}
Partial Updates
You can update only specific fields by including only those fields in the request body. Fields not included will remain unchanged. For example, to update only the phone number, send just {"phoneNumber": "+2348098765432"}.

Transaction PIN Management

PUT /api/customerprofile/update-transaction-pin Auth Required

Update the customer's transaction PIN. Requires the current PIN for verification.

Request Body
Parameter Type Required Description
currentTransactionPin string Yes Current 4-digit transaction PIN
newTransactionPin string Yes New 4-digit transaction PIN (exactly 4 digits)
Request Example 
PUT /api/customerprofile/update-transaction-pin
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "currentTransactionPin": "1234",
  "newTransactionPin": "5678"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Transaction PIN updated successfully",
  "data": {
    "customerId": "550e8400-e29b-41d4-a716-446655440000",
    "isPinUpdated": true,
    "updatedAt": "2025-01-15T10:30:00Z",
    "message": "Transaction PIN updated successfully"
  }
}
Error Response (400 Bad Request)
Status: 400 Bad Request
{
  "success": false,
  "message": "Invalid current transaction PIN",
  "data": null
}

The forgot transaction PIN flow consists of 4 steps similar to password reset: Send OTP → Verify OTP → Reset PIN. Follow these endpoints in sequence.

POST /api/customerprofile/forgot-transaction-pin

Step 1: Send an OTP code to the customer's email address to initiate transaction PIN reset.

Request Body
Parameter Type Required Description
email string Yes Customer's email address
Request Example 
POST /api/customerprofile/forgot-transaction-pin
Headers:
  x-api-key: your-api-key-here
  Content-Type: application/json

Body:
{
  "email": "john.doe@example.com"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "OTP sent successfully",
  "data": {
    "message": "Transaction PIN reset OTP sent successfully to john.doe@example.com",
    "expiresAt": "2025-01-15T10:35:00Z"
  }
}
POST /api/customerprofile/resend-forgot-transaction-pin

Resend the forgot transaction PIN OTP code if the customer didn't receive it or it expired.

Request Body
Parameter Type Required Description
email string Yes Customer's email address
Request Example 
POST /api/customerprofile/resend-forgot-transaction-pin
Headers:
  x-api-key: your-api-key-here
  Content-Type: application/json

Body:
{
  "email": "john.doe@example.com"
}
POST /api/customerprofile/verify-forgot-transaction-pin-otp

Step 2: Verify the OTP code received via email. This returns a reset token that will be used in the next step.

Request Body
Parameter Type Required Description
email string Yes Customer's email address
otp string Yes 6-digit OTP code sent to email
Request Example 
POST /api/customerprofile/verify-forgot-transaction-pin-otp
Headers:
  x-api-key: your-api-key-here
  Content-Type: application/json

Body:
{
  "email": "john.doe@example.com",
  "otp": "123456"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "OTP verified successfully",
  "data": {
    "resetToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresAt": "2025-01-15T11:30:00Z"
  }
}
Important
Save the resetToken from this response. You'll need it in the next step to reset the transaction PIN.
POST /api/customerprofile/reset-transaction-pin/{token}

Step 3: Reset the customer's transaction PIN using the reset token obtained from OTP verification.

Path Parameters
Parameter Type Required Description
token string Yes Reset token from OTP verification step
Request Body
Parameter Type Required Description
email string Yes Customer's email address
newTransactionPin string Yes New 4-digit transaction PIN (exactly 4 digits)
Request Example 
POST /api/customerprofile/reset-transaction-pin/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Headers:
  x-api-key: your-api-key-here
  Content-Type: application/json

Body:
{
  "email": "john.doe@example.com",
  "newTransactionPin": "5678"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Transaction PIN reset successfully",
  "data": true
}
Error Response (400 Bad Request)
Status: 400 Bad Request
{
  "success": false,
  "message": "Invalid or expired reset token",
  "data": false
}

Products

Browse and search products, categories, brands, and subcategories. All endpoints in this section require API key authentication via the x-api-key header.

GET /api/CustomerProuct API Key Required

Get a list of products with optional filtering, pagination, and sorting options. This endpoint supports filtering by category, brand, subcategory, and search terms.

Query Parameters
Parameter Type Required Description
categoryId integer No Filter by product category ID
brandId guid No Filter by brand ID
subcategoryId integer No Filter by product subcategory ID
searchTerm string No Search term to filter products by name or description
pageNumber integer No Page number for pagination (default: 1, minimum: 1)
pageSize integer No Number of items per page (default: 20, minimum: 1, maximum: 100)
sortBy string No Field to sort by: name, price, or createddate (default: "name")
sortOrder string No Sort order: asc or desc (default: "asc")
Request Example 
GET /api/CustomerProuct?categoryId=1&pageNumber=1&pageSize=20&sortBy=price&sortOrder=desc
Headers:
  x-api-key: your-api-key-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Products retrieved successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Premium Product",
      "description": "High-quality product description",
      "slug": "premium-product",
      "sku": "PROD-001",
      "price": 99.99,
      "compareAtPrice": 129.99,
      "discountPercentage": 23.08,
      "stockQuantity": 50,
      "isActive": true,
      "isFeatured": true,
      "requiresShipping": true,
      "installationAvailable": false,
      "installationCharge": null,
      "isMerchant": false,
      "availableForPickup": true,
      "availableForDelivery": true,
      "minDeliveryDays": 3,
      "maxDeliveryDays": 7,
      "images": [
        "https://storage.../product1.jpg",
        "https://storage.../product2.jpg"
      ],
      "productCategoryId": 1,
      "productSubcategoryId": 5,
      "brandId": "550e8400-e29b-41d4-a716-446655440001",
      "businessId": "550e8400-e29b-41d4-a716-446655440002",
      "platformId": "550e8400-e29b-41d4-a716-446655440003",
      "productCategory": {
        "id": 1,
        "name": "Electronics",
        "slug": "electronics"
      },
      "brand": {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "Brand Name"
      },
      "averageRating": 4.5,
      "totalRatings": 120,
      "totalReviews": 85
    }
  ]
}
GET /api/CustomerProuct/{id} API Key Required

Get detailed information about a specific product by its ID.

Path Parameters
Parameter Type Required Description
id guid Yes Product ID (GUID)
Request Example 
GET /api/CustomerProuct/550e8400-e29b-41d4-a716-446655440000
Headers:
  x-api-key: your-api-key-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Product retrieved successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Premium Product",
    "description": "High-quality product description",
    "slug": "premium-product",
    "sku": "PROD-001",
    "price": 99.99,
    "compareAtPrice": 129.99,
    "discountPercentage": 23.08,
    "stockQuantity": 50,
    "isActive": true,
    "isFeatured": true,
    "images": [
      "https://storage.../product1.jpg"
    ],
    "productCategoryId": 1,
    "brandId": "550e8400-e29b-41d4-a716-446655440001",
    "averageRating": 4.5,
    "totalRatings": 120,
    "totalReviews": 85
  }
}
Error Response (404 Not Found)
Status: 404 Not Found
{
  "success": false,
  "message": "Product not found",
  "data": null
}
GET /api/CustomerProuct/categories API Key Required

Get all active product categories available for browsing.

Request Example 
GET /api/CustomerProuct/categories
Headers:
  x-api-key: your-api-key-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Categories retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Electronics",
      "description": "Electronic products and accessories",
      "slug": "electronics",
      "iconUrl": "https://storage.../electronics-icon.png",
      "displayOrder": 1,
      "isActive": true,
      "isFeatured": true,
      "metaTitle": "Electronics",
      "metaDescription": "Browse electronic products",
      "subcategories": [
        {
          "id": 5,
          "productCategoryId": 1,
          "name": "Smartphones",
          "slug": "smartphones",
          "isActive": true
        }
      ]
    }
  ]
}
GET /api/CustomerProuct/categories/{categoryId}/subcategories API Key Required

Get all active subcategories for a specific category.

Path Parameters
Parameter Type Required Description
categoryId integer Yes Category ID
Request Example 
GET /api/CustomerProuct/categories/1/subcategories
Headers:
  x-api-key: your-api-key-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Subcategories retrieved successfully",
  "data": [
    {
      "id": 5,
      "productCategoryId": 1,
      "name": "Smartphones",
      "description": "Mobile phones and smartphones",
      "slug": "smartphones",
      "iconUrl": "https://storage.../smartphones-icon.png",
      "displayOrder": 1,
      "isActive": true,
      "isFeatured": true,
      "metaTitle": "Smartphones",
      "metaDescription": "Browse smartphone products"
    }
  ]
}
GET /api/CustomerProuct/brands API Key Required

Get all active brands available for filtering products.

Request Example 
GET /api/CustomerProuct/brands
Headers:
  x-api-key: your-api-key-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Brands retrieved successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Premium Brand",
      "description": "High-quality brand",
      "slug": "premium-brand",
      "logoUrl": "https://storage.../brand-logo.png",
      "isActive": true,
      "isFeatured": true
    }
  ]
}
GET /api/CustomerProuct/search API Key Required

Search for products by name or description. Results are paginated.

Query Parameters
Parameter Type Required Description
searchTerm string Yes Search term to match against product names and descriptions
pageNumber integer No Page number for pagination (default: 1, minimum: 1)
pageSize integer No Number of items per page (default: 20, minimum: 1, maximum: 100)
Request Example 
GET /api/CustomerProuct/search?searchTerm=laptop&pageNumber=1&pageSize=20
Headers:
  x-api-key: your-api-key-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Products retrieved successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Gaming Laptop",
      "description": "High-performance gaming laptop",
      "price": 1299.99,
      "stockQuantity": 25,
      "images": ["https://storage.../laptop.jpg"]
    }
  ]
}
Error Response (400 Bad Request)
Status: 400 Bad Request
{
  "success": false,
  "message": "Search term is required",
  "data": null
}
GET /api/CustomerProuct/featured API Key Required

Get featured/popular products. These are typically products marked as featured by administrators or popular based on sales/views.

Query Parameters
Parameter Type Required Description
limit integer No Number of featured products to return (default: 10, minimum: 1, maximum: 50)
Request Example 
GET /api/CustomerProuct/featured?limit=10
Headers:
  x-api-key: your-api-key-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Featured products retrieved successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Featured Product",
      "description": "Popular featured product",
      "price": 99.99,
      "isFeatured": true,
      "images": ["https://storage.../featured-product.jpg"],
      "averageRating": 4.8,
      "totalRatings": 250
    }
  ]
}

Cart Management

Manage shopping cart items. All endpoints in this section require authentication via JWT Bearer token. The customer ID is automatically extracted from the JWT token.

POST /api/customer/cart/add Auth Required

Add a product to the customer's shopping cart. If the product already exists in the cart, the quantity will be updated.

Request Body
Parameter Type Required Description
productId guid Yes Product ID to add to cart
quantity integer Yes Quantity to add (minimum: 1)
sessionId string No Session ID for anonymous cart (optional)
Request Example 
POST /api/customer/cart/add
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "productId": "550e8400-e29b-41d4-a716-446655440000",
  "quantity": 2
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Item added to cart successfully",
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "productId": "550e8400-e29b-41d4-a716-446655440000",
    "productName": "Premium Product",
    "productImage": "https://storage.../product.jpg",
    "unitPrice": 99.99,
    "quantity": 2,
    "totalPrice": 199.98,
    "isInStock": true,
    "stockQuantity": 50,
    "dateAdded": "2025-01-15T10:30:00Z"
  }
}
PUT /api/customer/cart/update Auth Required

Update the quantity of an item in the cart.

Request Body
Parameter Type Required Description
cartItemId guid Yes Cart item ID to update
quantity integer Yes New quantity (minimum: 1)
Request Example 
PUT /api/customer/cart/update
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "cartItemId": "660e8400-e29b-41d4-a716-446655440000",
  "quantity": 5
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Cart item updated successfully",
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "productId": "550e8400-e29b-41d4-a716-446655440000",
    "productName": "Premium Product",
    "quantity": 5,
    "totalPrice": 499.95
  }
}
DELETE /api/customer/cart/remove Auth Required

Remove a specific item from the cart.

Request Body
Parameter Type Required Description
cartItemId guid Yes Cart item ID to remove
Request Example 
DELETE /api/customer/cart/remove
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "cartItemId": "660e8400-e29b-41d4-a716-446655440000"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Item removed from cart successfully",
  "data": true
}
DELETE /api/customer/cart/clear Auth Required

Remove all items from the cart, effectively emptying it.

Request Example 
DELETE /api/customer/cart/clear
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Cart cleared successfully",
  "data": true
}
GET /api/customer/cart/summary Auth Required

Get a summary of the cart including all items, subtotals, taxes, shipping, and total amount.

Request Example 
GET /api/customer/cart/summary
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Cart summary retrieved successfully",
  "data": {
    "items": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440000",
        "productId": "550e8400-e29b-41d4-a716-446655440000",
        "productName": "Premium Product",
        "quantity": 2,
        "unitPrice": 99.99,
        "totalPrice": 199.98
      }
    ],
    "totalItems": 2,
    "subTotal": 199.98,
    "taxAmount": 23.99,
    "shippingAmount": 10.00,
    "totalAmount": 233.97,
    "hasOutOfStockItems": false,
    "lastUpdated": "2025-01-15T10:30:00Z"
  }
}
GET /api/customer/cart/items Auth Required

Get all items currently in the cart.

Request Example 
GET /api/customer/cart/items
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Cart items retrieved successfully",
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "productName": "Premium Product",
      "productImage": "https://storage.../product.jpg",
      "unitPrice": 99.99,
      "quantity": 2,
      "totalPrice": 199.98,
      "isInStock": true,
      "stockQuantity": 50,
      "dateAdded": "2025-01-15T10:30:00Z"
    }
  ]
}
POST /api/customer/cart/sync Auth Required

Sync cart items when a customer logs in. This merges session-based cart items with the customer's permanent cart.

Query Parameters
Parameter Type Required Description
sessionId string No Session ID to merge with customer cart (optional)
Request Example 
POST /api/customer/cart/sync?sessionId=abc123xyz
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Cart synced successfully",
  "data": true
}
POST /api/customer/cart/transfer-session Auth Required

Transfer all items from a session-based cart to the authenticated customer's cart.

Query Parameters
Parameter Type Required Description
sessionId string Yes Session ID of the cart to transfer
Request Example 
POST /api/customer/cart/transfer-session?sessionId=abc123xyz
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Session cart transferred successfully",
  "data": true
}
GET /api/customer/cart/count Auth Required

Get the total number of items in the cart (sum of quantities).

Request Example 
GET /api/customer/cart/count
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Cart count retrieved successfully",
  "data": 5
}
GET /api/customer/cart/total Auth Required

Get the total monetary value of all items in the cart (before taxes and shipping).

Request Example 
GET /api/customer/cart/total
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Cart total retrieved successfully",
  "data": 199.98
}

Checkout & Payment

Process orders and handle payments through shopping card or payment gateway. For delivery orders, first get delivery quotes from Terminal Africa to show available delivery options and prices. Also manage pickup locations for order fulfillment. All checkout endpoints require authentication via JWT Bearer token.

POST /api/checkout Auth Required

Process checkout with automatic routing to the appropriate payment method based on the paymentMethod field. Supports both Shopping Card and Payment Gateway payment methods.

Automatic Routing
This endpoint automatically routes to the correct payment processor based on the paymentMethod field. Use the specific endpoints (/shopping-card or /payment-gateway) if you prefer explicit routing.
Request Body
Parameter Type Required Description
totalAmount decimal Yes Total amount for the order (minimum: 0.01)
paymentMethod enum Yes Payment method: ShoppingCard or PaymentGateway
products array Yes List of products with quantities (at least 1 product required)
storeLocationId guid Yes Store location ID for pickup
address string No Delivery address (optional for pickup orders)
redirectUrl string Conditional* Redirect URL for payment gateway (required when paymentMethod is PaymentGateway)
transactionPin string Conditional* Transaction PIN for shopping card payment (required when paymentMethod is ShoppingCard)

* Conditional: Required based on the payment method selected.

Products Array Item
Parameter Type Required Description
productId guid Yes Product ID (GUID)
quantity integer Yes Quantity of the product (minimum: 1)
Request Example (Shopping Card) 
POST /api/checkout
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "totalAmount": 199.98,
  "paymentMethod": "ShoppingCard",
  "products": [
    {
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "quantity": 2
    }
  ],
  "storeLocationId": "770e8400-e29b-41d4-a716-446655440000",
  "transactionPin": "1234"
}
Request Example (Payment Gateway) 
POST /api/checkout
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "totalAmount": 199.98,
  "paymentMethod": "PaymentGateway",
  "products": [
    {
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "quantity": 2
    }
  ],
  "storeLocationId": "770e8400-e29b-41d4-a716-446655440000",
  "redirectUrl": "https://yourapp.com/payment/callback"
}
Success Response - Shopping Card (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Checkout processed successfully",
  "data": {
    "orderId": "880e8400-e29b-41d4-a716-446655440000",
    "transactionId": "990e8400-e29b-41d4-a716-446655440000",
    "remainingBalance": 800.02,
    "amountDeducted": 199.98,
    "orderStatus": "Completed",
    "message": "Order placed successfully"
  }
}
Success Response - Payment Gateway (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Checkout processed successfully",
  "data": {
    "orderId": "880e8400-e29b-41d4-a716-446655440000",
    "transactionReference": "TXN123456789",
    "paymentUrl": "https://payment-gateway.com/pay/TXN123456789",
    "orderStatus": "Pending",
    "paymentMethod": "PaymentGateway",
    "totalAmount": 199.98,
    "currency": "NGN",
    "createdAt": "2025-01-15T10:30:00Z",
    "message": "Payment URL generated successfully"
  }
}
POST /api/checkout/shopping-card Auth Required

Process checkout specifically using the shopping card payment method. This endpoint requires a transaction PIN to authorize the payment.

Payment Method
The paymentMethod field must be set to ShoppingCard. The transactionPin field is required for authorization.
Request Example 
POST /api/checkout/shopping-card
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "totalAmount": 199.98,
  "paymentMethod": "ShoppingCard",
  "products": [
    {
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "quantity": 2
    }
  ],
  "storeLocationId": "770e8400-e29b-41d4-a716-446655440000",
  "transactionPin": "1234"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Checkout processed successfully",
  "data": {
    "orderId": "880e8400-e29b-41d4-a716-446655440000",
    "transactionId": "990e8400-e29b-41d4-a716-446655440000",
    "remainingBalance": 800.02,
    "amountDeducted": 199.98,
    "orderStatus": "Completed",
    "message": "Order placed successfully"
  }
}
POST /api/checkout/payment-gateway Auth Required

Process checkout using a payment gateway (e.g., Paystack, Monnify). This endpoint returns a payment URL that should be used to redirect the customer to complete the payment.

Payment Method
The paymentMethod field must be set to PaymentGateway. The redirectUrl field is required to specify where to redirect the customer after payment.
Request Example 
POST /api/checkout/payment-gateway
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "totalAmount": 199.98,
  "paymentMethod": "PaymentGateway",
  "products": [
    {
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "quantity": 2
    }
  ],
  "storeLocationId": "770e8400-e29b-41d4-a716-446655440000",
  "redirectUrl": "https://yourapp.com/payment/callback"
}

For delivery orders, also include: deliveryOption, address, deliveryFee, deliveryCompanyName, selectedRateId (from the delivery quote), and set totalAmount to cart total + delivery fee. See the Delivery Quotes section and "Checkout Request with Delivery" example below.

Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Checkout processed successfully",
  "data": {
    "orderId": "880e8400-e29b-41d4-a716-446655440000",
    "transactionReference": "TXN123456789",
    "paymentUrl": "https://payment-gateway.com/pay/TXN123456789",
    "orderStatus": "Pending",
    "paymentMethod": "PaymentGateway",
    "totalAmount": 199.98,
    "currency": "NGN",
    "createdAt": "2025-01-15T10:30:00Z",
    "message": "Payment URL generated successfully"
  }
}
Payment Flow
After receiving the response, redirect the customer to the paymentUrl. After payment completion, the customer will be redirected to your redirectUrl with payment status information.

Delivery Quotes

About Delivery Quotes
Before processing checkout for delivery orders, you should first get delivery quotes from Terminal Africa (our logistics provider). This allows customers to see available delivery options, prices, and estimated delivery times. After selecting a delivery company, include the delivery fee and company information in your checkout request.
POST /api/checkout/delivery-quote Auth Required

Get delivery quotes from Terminal Africa for a specific delivery address. Returns a list of available delivery companies with their prices and estimated delivery times.

Request Body
Parameter Type Required Description
storeLocationId guid Yes Store location ID where the order will be picked up from
deliveryAddress string Yes Customer's complete delivery address (minimum 10 characters)
totalAmount decimal No Total order amount (used for insurance calculation)
packageWeight float No Estimated package weight in kg (defaults to 1.0 if not provided)
Request Example 
POST /api/checkout/delivery-quote
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "storeLocationId": "770e8400-e29b-41d4-a716-446655440000",
  "deliveryAddress": "123 Main Street, Victoria Island, Lagos",
  "totalAmount": 199.98,
  "packageWeight": 2.5
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Delivery quote retrieved successfully",
  "data": {
    "success": true,
    "message": "Delivery quote retrieved successfully",
    "companies": [
      {
        "companyId": 1,
        "companyName": "Terminal Express",
        "rateId": "RT-abc123",
        "carrierSlug": "terminal-express",
        "carrierLogo": "https://example.com/logos/terminal-express.png",
        "deliveryFee": 5000.00,
        "estimatedDeliveryTime": "Within 3-5 days",
        "currency": "NGN"
      },
      {
        "companyId": 2,
        "companyName": "Terminal Standard",
        "rateId": "RT-def456",
        "carrierSlug": "terminal-standard",
        "carrierLogo": "https://example.com/logos/terminal-standard.png",
        "deliveryFee": 3500.00,
        "estimatedDeliveryTime": "Within 5-7 days",
        "currency": "NGN"
      },
      {
        "companyId": 3,
        "companyName": "Terminal Premium",
        "rateId": "RT-ghi789",
        "carrierSlug": "terminal-premium",
        "carrierLogo": "https://example.com/logos/terminal-premium.png",
        "deliveryFee": 7500.00,
        "estimatedDeliveryTime": "Within 1-2 days",
        "currency": "NGN"
      }
    ]
  }
}

Each company includes rateId (send as selectedRateId in checkout), carrierLogo (URL for display), and carrierSlug. You can optionally send carrierLogo in the checkout request for audit/display.

Using Delivery Quotes in Checkout
After receiving the delivery quote response:
  1. Display the available companies to the customer
  2. Allow the customer to select a delivery company
  3. When processing checkout, include the following in your checkout request:
    • deliveryOption: Set to "Delivery"
    • address: The delivery address
    • totalAmount: Cart total + selected company's deliveryFee (must match backend calculation or you will get "Total amount mismatch")
    • deliveryFee: The selected company's deliveryFee
    • deliveryCompanyName: The selected company's companyName
    • selectedRateId: The selected company's rateId from the quote response (recommended: ensures backend uses the same rate and avoids total mismatch)
Checkout Request with Delivery 
POST /api/checkout
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "totalAmount": 199.98,
  "paymentMethod": "ShoppingCard",
  "products": [
    {
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "quantity": 2
    }
  ],
  "storeLocationId": "770e8400-e29b-41d4-a716-446655440000",
  "deliveryOption": "Delivery",
  "address": "123 Main Street, Victoria Island, Lagos",
  "deliveryFee": 5000.00,
  "deliveryCompanyName": "Terminal Express",
  "selectedRateId": "RT-xxxxx",
  "carrierLogo": "https://example.com/logos/terminal-express.png",
  "transactionPin": "1234"
}

Note: totalAmount must be cart total + delivery fee. Include selectedRateId from the delivery quote response so the backend uses the same rate and fee (avoids "Total amount mismatch" errors). carrierLogo is optional (from the quote) for display/audit.

Error Response (400 Bad Request)
Status: 400 Bad Request
{
  "success": false,
  "message": "Terminal Africa settings not configured for this platform",
  "data": null
}

Saved Delivery Addresses

Customers can save delivery addresses (stored with Terminal Africa). Use these endpoints to list, update, or delete saved addresses. Requires x-api-key (platform and environment are derived from it) and customer JWT (Bearer token). You do not pass email, platformId, or environment in the request.

GET /api/checkout/saved-delivery-addresses Auth Required

Get all saved delivery addresses for the authenticated customer. Platform and environment are derived from the request x-api-key header; customer is identified from the JWT.

Query Parameters

None. Send x-api-key and Authorization: Bearer <jwt>.

Request Example 
GET /api/checkout/saved-delivery-addresses
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Saved addresses retrieved successfully",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "platformId": "770e8400-e29b-41d4-a716-446655440000",
      "businessId": "550e8400-e29b-41d4-a716-446655440001",
      "environmentType": 1,
      "providerName": "Terminal Africa",
      "providerAddressId": "addr_abc123",
      "firstName": "John",
      "lastName": "Doe",
      "email": "customer@example.com",
      "phone": "+2348012345678",
      "line1": "123 Main Street",
      "line2": null,
      "city": "Lagos",
      "state": "Lagos",
      "country": "NG",
      "zip": null,
      "isResidential": true,
      "dateCreated": "2025-01-15T10:00:00Z",
      "dateUpdated": "2025-01-15T10:00:00Z"
    }
  ]
}
PUT /api/checkout/saved-delivery-addresses Auth Required

Update an existing saved delivery address. Pass the same providerAddressId with updated fields. Platform and environment are derived from x-api-key; customer from JWT.

Request Body
ParameterTypeRequiredDescription
providerAddressIdstringYesID of the address to update (from get response)
line1stringYesStreet address
line2stringNoAddress line 2
citystringYesCity
statestringYesState
countrystringYesCountry code (e.g. NG), max 2 chars
zipstringNoPostal code
firstNamestringNoFirst name
lastNamestringNoLast name
emailstringNoEmail
phonestringNoPhone
isResidentialbooleanNoResidential address (default true)
Request Example 
PUT /api/checkout/saved-delivery-addresses
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "providerAddressId": "addr_abc123",
  "line1": "456 Updated Street",
  "line2": "Apt 2",
  "city": "Lagos",
  "state": "Lagos",
  "country": "NG",
  "zip": "100001",
  "firstName": "John",
  "lastName": "Doe",
  "email": "customer@example.com",
  "phone": "+2348012345678",
  "isResidential": true
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Address updated successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "providerAddressId": "addr_abc123",
    "line1": "456 Updated Street",
    "city": "Lagos",
    "state": "Lagos",
    "country": "NG",
    "dateUpdated": "2025-01-15T12:00:00Z"
  }
}
DELETE /api/checkout/saved-delivery-addresses Auth Required

Delete a saved delivery address by providerAddressId. Platform and environment are derived from x-api-key; customer from JWT.

Query Parameters
ParameterTypeRequiredDescription
providerAddressIdstringYesID of the address to delete (from get response)
Request Example 
DELETE /api/checkout/saved-delivery-addresses?providerAddressId=addr_abc123
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Address deleted successfully",
  "data": true
}

Pickup Locations

GET /api/PickUpLocation API Key Required

Get all available pickup locations for the platform. Locations are filtered based on the API key.

Request Example 
GET /api/PickUpLocation
Headers:
  x-api-key: your-api-key-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Pickup locations retrieved successfully",
  "data": [
    {
      "storeLocationId": "770e8400-e29b-41d4-a716-446655440000",
      "name": "Lagos Main Store",
      "address": "123 Main Street, Lagos",
      "state": "Lagos",
      "country": "Nigeria",
      "isActive": true,
      "businessId": "550e8400-e29b-41d4-a716-446655440001",
      "platformId": "550e8400-e29b-41d4-a716-446655440002"
    }
  ]
}
GET /api/PickUpLocation/state/{state} API Key Required

Get all pickup locations filtered by state name.

Path Parameters
Parameter Type Required Description
state string Yes State name (e.g., "Lagos", "Abuja")
Request Example 
GET /api/PickUpLocation/state/Lagos
Headers:
  x-api-key: your-api-key-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Pickup locations retrieved successfully",
  "data": [
    {
      "storeLocationId": "770e8400-e29b-41d4-a716-446655440000",
      "name": "Lagos Main Store",
      "address": "123 Main Street, Lagos",
      "state": "Lagos",
      "country": "Nigeria",
      "isActive": true
    }
  ]
}
GET /api/PickUpLocation/states API Key Required

Get a list of all states that have active pickup locations available.

Request Example 
GET /api/PickUpLocation/states
Headers:
  x-api-key: your-api-key-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "States retrieved successfully",
  "data": [
    "Lagos",
    "Abuja",
    "Port Harcourt",
    "Kano"
  ]
}
GET /api/PickUpLocation/{id} API Key Required

Get detailed information about a specific pickup location by its ID.

Path Parameters
Parameter Type Required Description
id guid Yes Pickup location ID (GUID)
Request Example 
GET /api/PickUpLocation/770e8400-e29b-41d4-a716-446655440000
Headers:
  x-api-key: your-api-key-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Pickup location retrieved successfully",
  "data": {
    "storeLocationId": "770e8400-e29b-41d4-a716-446655440000",
    "name": "Lagos Main Store",
    "address": "123 Main Street, Lagos",
    "state": "Lagos",
    "country": "Nigeria",
    "isActive": true,
    "businessId": "550e8400-e29b-41d4-a716-446655440001",
    "platformId": "550e8400-e29b-41d4-a716-446655440002"
  }
}
Error Response (404 Not Found)
Status: 404 Not Found
{
  "success": false,
  "message": "Pickup location not found",
  "data": null
}

Shopping Card & Transactions

Fund shopping cards and verify transaction status. All endpoints in this section require authentication via JWT Bearer token. The customer ID is automatically extracted from the JWT token.

POST /api/transaction/fund-shopping-card Auth Required

Initialize a payment to fund the customer's shopping card. This endpoint creates a payment transaction and returns a payment URL that should be used to redirect the customer to complete the payment.

Payment Flow
After receiving the response, redirect the customer to the authorizationUrl or checkoutUrl to complete the payment. After payment completion, the customer will be redirected to your callbackUrl with transaction status information. Use the verify-transaction endpoint to confirm the transaction status.
Request Body
Parameter Type Required Description
amount decimal Yes Amount to fund the shopping card (minimum: 1.00)
callbackUrl string Yes Valid URL where the customer will be redirected after payment completion
Request Example 
POST /api/transaction/fund-shopping-card
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "amount": 5000.00,
  "callbackUrl": "https://yourapp.com/payment/callback"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Payment initialization successful",
  "data": {
    "success": true,
    "message": "Payment URL generated successfully",
    "authorizationUrl": "https://payment-gateway.com/authorize/ACC123456",
    "accessCode": "ACC123456",
    "reference": "REF123456789",
    "checkoutUrl": "https://payment-gateway.com/checkout/REF123456789",
    "transactionReference": "TXN123456789",
    "paymentReference": "PAY123456789",
    "gateway": "Paystack"
  }
}
Error Response (400 Bad Request)
Status: 400 Bad Request
{
  "success": false,
  "message": "Amount must be greater than 0",
  "data": null
}
Important
Save the transactionReference or reference from the response. You'll need it to verify the transaction status after payment completion using the verify-transaction endpoint.
POST /api/transaction/verify-transaction Auth Required

Verify the status of a transaction using the transaction reference. This endpoint can be used to check the status of shopping card funding transactions or checkout payment transactions.

Request Body
Parameter Type Required Description
transactionReference string Yes Transaction reference from payment gateway or checkout response
Request Example 
POST /api/transaction/verify-transaction
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "transactionReference": "TXN123456789"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Transaction verified successfully",
  "data": {
    "isSuccessful": true,
    "transactionReference": "TXN123456789",
    "status": "success",
    "amount": 5000.00,
    "currency": "NGN",
    "completedAt": "2025-01-15T10:35:00Z",
    "paymentMethod": "PaymentGateway",
    "message": "Transaction completed successfully"
  }
}
Error Response (404 Not Found)
Status: 404 Not Found
{
  "success": false,
  "message": "Transaction not found",
  "data": null
}
Transaction Status
The isSuccessful field indicates whether the transaction was successful. The status field provides additional details about the transaction state (e.g., "success", "pending", "failed").

Bills Payment

Pay utility bills including airtime, data, electricity, and cable TV subscriptions. All endpoints in this section require authentication via JWT Bearer token and API key. The customer ID is automatically extracted from the JWT token.

Services

GET /api/billspayment/services/airtime Auth Required

Get all available airtime services (MTN, Glo, Airtel, 9mobile).

Request Example 
GET /api/billspayment/services/airtime
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Airtime services retrieved successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "MTN",
      "slug": "mtn",
      "isActive": true
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "name": "Glo",
      "slug": "glo",
      "isActive": true
    }
  ]
}
GET /api/billspayment/services/data Auth Required

Get all available data services (MTNData, GloData, AirtelData, 9mobileData).

Request Example 
GET /api/billspayment/services/data
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Data services retrieved successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "name": "MTNData",
      "slug": "mtndata",
      "isActive": true
    }
  ]
}
GET /api/billspayment/services/cable Auth Required

Get all available cable TV services (Showmax, DSTV, GOTV, Startimes).

Request Example 
GET /api/billspayment/services/cable
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Cable services retrieved successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440004",
      "name": "DSTV",
      "slug": "dstv",
      "isActive": true
    }
  ]
}
GET /api/billspayment/services/electricity Auth Required

Get all available electricity distribution companies (DISCOs): EKEDC, IKEDC, EEDC, KAEDCO, KEDCO, AEDC, PHED, JEDC, BEDC, YEDC.

Request Example 
GET /api/billspayment/services/electricity
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Electricity services retrieved successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440005",
      "name": "EKEDC",
      "slug": "ekedc",
      "isActive": true
    }
  ]
}
GET /api/billspayment/periods Auth Required

Get available billing periods for data plans (Daily, Weekly, Monthly).

Request Example 
GET /api/billspayment/periods
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Billing periods retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Daily"
    },
    {
      "id": 2,
      "name": "Weekly"
    },
    {
      "id": 3,
      "name": "Monthly"
    }
  ]
}

Plans

POST /api/billspayment/dataplans Auth Required

Get available data plans for a specific service and billing period. Use this to retrieve data bundle options before purchase.

Request Body
Parameter Type Required Description
serviceName string Yes Data service name (e.g., "MTNData", "GloData") (max 50 characters)
period string Yes Billing period: "Daily", "Weekly", or "Monthly" (max 50 characters)
Request Example 
POST /api/billspayment/dataplans
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "serviceName": "MTNData",
  "period": "Monthly"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Data plans retrieved successfully",
  "data": [
    {
      "id": 1,
      "slug": "mtn-1gb-monthly",
      "name": "1GB Monthly",
      "amount": 500.00,
      "billerId": 101,
      "slugName": "mtn-1gb-monthly"
    },
    {
      "id": 2,
      "slug": "mtn-2gb-monthly",
      "name": "2GB Monthly",
      "amount": 1000.00,
      "billerId": 101,
      "slugName": "mtn-2gb-monthly"
    }
  ]
}
POST /api/billspayment/discoplans Auth Required

Get available plans/packages for a specific electricity distribution company (DISCO).

Request Body
Parameter Type Required Description
discoName string Yes DISCO name (e.g., "EKEDC", "IKEDC") (max 50 characters)
Request Example 
POST /api/billspayment/discoplans
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "discoName": "EKEDC"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "DISCO plans retrieved successfully",
  "data": [
    {
      "id": 1,
      "slug": "ekedc-prepaid",
      "name": "EKEDC Prepaid",
      "amount": null,
      "billerId": 201,
      "billerSlug": "ekedc",
      "slugName": "ekedc-prepaid"
    }
  ]
}
POST /api/billspayment/cableplans Auth Required

Get available subscription plans for a specific cable TV provider.

Request Body
Parameter Type Required Description
cableTvName string Yes Cable TV provider name (e.g., "DSTV", "GOTV") (max 50 characters)
Request Example 
POST /api/billspayment/cableplans
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "cableTvName": "DSTV"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Cable plans retrieved successfully",
  "data": [
    {
      "id": 1,
      "slug": "dstv-compact",
      "name": "DSTV Compact",
      "amount": 7900.00,
      "billerId": 301,
      "billerSlug": "dstv",
      "slugName": "dstv-compact"
    },
    {
      "id": 2,
      "slug": "dstv-premium",
      "name": "DSTV Premium",
      "amount": 24500.00,
      "billerId": 301,
      "billerSlug": "dstv",
      "slugName": "dstv-premium"
    }
  ]
}

Customer Validation

POST /api/billspayment/electricity/validate Auth Required

Validate an electricity meter/card number before purchase. This endpoint verifies the meter number and returns customer details including minimum payment amount.

Request Body
Parameter Type Required Description
meterNumber string Yes Electricity meter/card number (max 50 characters)
billerSlug string Yes Biller slug (e.g., "ekedc", "ikedc") (max 100 characters)
billerId integer Yes Biller ID (numeric ID from service response)
Request Example 
POST /api/billspayment/electricity/validate
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "meterNumber": "12345678901",
  "billerSlug": "ekedc",
  "billerId": 201
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Electricity customer validated successfully",
  "data": {
    "isValid": true,
    "message": "Customer validated successfully",
    "customerName": "John Doe",
    "meterNumber": "12345678901",
    "minAmount": 100.00,
    "customerMessage": "Customer validated successfully"
  }
}
POST /api/billspayment/cable/validate Auth Required

Validate a cable TV smart card number before purchase. This endpoint verifies the smart card number and returns customer details including minimum payment amount.

Request Body
Parameter Type Required Description
smartCardNumber string Yes Cable TV smart card number (max 50 characters)
billerSlug string Yes Biller slug (e.g., "dstv", "gotv") (max 100 characters)
billerId integer Yes Biller ID (numeric ID from service response)
Request Example 
POST /api/billspayment/cable/validate
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "smartCardNumber": "12345678901",
  "billerSlug": "dstv",
  "billerId": 301
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Cable customer validated successfully",
  "data": {
    "isValid": true,
    "message": "Customer validated successfully",
    "customerName": "John Doe",
    "smartCardNumber": "12345678901",
    "minAmount": 500.00,
    "customerMessage": "Customer validated successfully"
  }
}

Purchase

POST /api/billspayment/airtime/purchase Auth Required

Purchase airtime for a phone number. Payment is deducted from the customer's shopping card balance using the provided transaction PIN.

Request Body
Parameter Type Required Description
airtimeServiceId guid Yes Airtime service ID (GUID from services endpoint)
amount decimal Yes Amount to purchase (minimum: ₦50, maximum: ₦50,000)
phoneNumber string Yes Recipient phone number (must be valid phone format)
transactionPin string Yes Customer's transaction PIN (4-6 digits)
Request Example 
POST /api/billspayment/airtime/purchase
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "airtimeServiceId": "550e8400-e29b-41d4-a716-446655440001",
  "amount": 1000.00,
  "phoneNumber": "+2348012345678",
  "transactionPin": "1234"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Airtime purchased successfully",
  "data": {
    "success": true,
    "message": "Airtime purchase completed",
    "transactionReference": "TXN123456789",
    "paymentReference": "PAY123456789",
    "token": "AIRTIME_TOKEN_12345",
    "amount": 1000.00,
    "telcoName": "MTN",
    "phoneNumber": "+2348012345678",
    "processedAt": "2025-01-15T10:30:00Z"
  }
}
POST /api/billspayment/data/purchase Auth Required

Purchase data bundle for a phone number. Payment is deducted from the customer's shopping card balance using the provided transaction PIN.

Request Body
Parameter Type Required Description
dataServiceId guid Yes Data service ID (GUID from services endpoint)
amount decimal Yes Amount to purchase (minimum: ₦50, maximum: ₦50,000)
phoneNumber string Yes Recipient phone number (must be valid phone format)
packageSlug string Yes Package slug from data plans response (max 100 characters)
billerId integer Yes Biller ID from data plans response
transactionPin string Yes Customer's transaction PIN (4-6 digits)
Request Example 
POST /api/billspayment/data/purchase
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "dataServiceId": "550e8400-e29b-41d4-a716-446655440003",
  "amount": 1000.00,
  "phoneNumber": "+2348012345678",
  "packageSlug": "mtn-2gb-monthly",
  "billerId": 101,
  "transactionPin": "1234"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Data purchased successfully",
  "data": {
    "success": true,
    "message": "Data purchase completed",
    "transactionReference": "TXN123456789",
    "paymentReference": "PAY123456789",
    "token": "DATA_TOKEN_12345",
    "status": "success",
    "amount": 1000.00,
    "phoneNumber": "+2348012345678",
    "processedAt": "2025-01-15T10:30:00Z"
  }
}
POST /api/billspayment/electricity/purchase Auth Required

Purchase electricity (prepaid/postpaid) for a meter number. Payment is deducted from the customer's shopping card balance using the provided transaction PIN.

Request Body
Parameter Type Required Description
electricityServiceId guid Yes Electricity service ID (GUID from services endpoint)
amount decimal Yes Amount to purchase (minimum: ₦100, maximum: ₦100,000)
meterNumber string Yes Electricity meter/card number (max 50 characters)
packageSlug string Yes Package slug from DISCO plans response (max 100 characters)
billerSlug string Yes Biller slug (e.g., "ekedc", "ikedc") (max 100 characters)
billerId integer Yes Biller ID from DISCO plans response
transactionPin string Yes Customer's transaction PIN (4-6 digits)
Request Example 
POST /api/billspayment/electricity/purchase
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "electricityServiceId": "550e8400-e29b-41d4-a716-446655440005",
  "amount": 5000.00,
  "meterNumber": "12345678901",
  "packageSlug": "ekedc-prepaid",
  "billerSlug": "ekedc",
  "billerId": 201,
  "transactionPin": "1234"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Electricity purchased successfully",
  "data": {
    "success": true,
    "message": "Electricity purchase completed",
    "transactionReference": "TXN123456789",
    "paymentReference": "PAY123456789",
    "token": "ELECTRICITY_TOKEN_12345",
    "status": "success",
    "amount": 5000.00,
    "meterNumber": "12345678901",
    "processedAt": "2025-01-15T10:30:00Z"
  }
}
POST /api/billspayment/cable/purchase Auth Required

Purchase cable TV subscription for a smart card number. Payment is deducted from the customer's shopping card balance using the provided transaction PIN.

Request Body
Parameter Type Required Description
cableServiceId guid Yes Cable service ID (GUID from services endpoint)
amount decimal Yes Amount to purchase (minimum: ₦500, maximum: ₦100,000)
smartCardNumber string Yes Cable TV smart card number (max 50 characters)
packageSlug string Yes Package slug from cable plans response (max 100 characters)
billerSlug string Yes Biller slug (e.g., "dstv", "gotv") (max 100 characters)
billerId integer Yes Biller ID from cable plans response
transactionPin string Yes Customer's transaction PIN (4-6 digits)
Request Example 
POST /api/billspayment/cable/purchase
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "cableServiceId": "550e8400-e29b-41d4-a716-446655440004",
  "amount": 7900.00,
  "smartCardNumber": "12345678901",
  "packageSlug": "dstv-compact",
  "billerSlug": "dstv",
  "billerId": 301,
  "transactionPin": "1234"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Cable TV purchased successfully",
  "data": {
    "success": true,
    "message": "Cable TV purchase completed",
    "transactionReference": "TXN123456789",
    "paymentReference": "PAY123456789",
    "token": "CABLE_TOKEN_12345",
    "status": "success",
    "amount": 7900.00,
    "smartCardNumber": "12345678901",
    "processedAt": "2025-01-15T10:30:00Z"
  }
}
Payment Method
All purchase endpoints deduct payment from the customer's shopping card balance using the provided transaction PIN. Ensure the customer has sufficient balance before making a purchase.

Wishlist

Manage your wishlist to save products for later purchase. All endpoints in this section require authentication via JWT Bearer token and API key. The customer ID is automatically extracted from the JWT token.

POST /api/ProductWishList/add Auth Required

Add a product to the customer's wishlist. You can optionally add notes and set a priority level (1-5) for the item.

Request Body
Parameter Type Required Description
productId guid Yes The ID of the product to add to the wishlist
notes string No Optional notes about the product (max 500 characters)
priority integer No Priority level (1-5, where 1 is highest priority). Default: 1
Request Example 
POST /api/ProductWishList/add
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "productId": "550e8400-e29b-41d4-a716-446655440000",
  "notes": "Need this for birthday gift",
  "priority": 1
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Product added to wishlist successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "productId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "customer-id-here",
    "productName": "Smartphone X",
    "productDescription": "Latest smartphone with advanced features",
    "productImage": "https://example.com/product.jpg",
    "productPrice": 50000.00,
    "compareAtPrice": 60000.00,
    "discountPercentage": 16.67,
    "isInStock": true,
    "stockQuantity": 50,
    "productSlug": "smartphone-x",
    "productSku": "SPX-001",
    "notes": "Need this for birthday gift",
    "priority": 1,
    "dateAdded": "2025-01-15T10:30:00Z",
    "dateUpdated": null,
    "platformId": "platform-id-here",
    "businessId": "business-id-here",
    "environmentType": "Test",
    "categoryName": "Electronics",
    "brandName": "TechBrand"
  }
}
DELETE /api/ProductWishList/remove/{wishListItemId} Auth Required

Remove a single item from the customer's wishlist by wishlist item ID.

Path Parameters
Parameter Type Required Description
wishListItemId guid Yes The ID of the wishlist item to remove
Request Example 
DELETE /api/ProductWishList/remove/a1b2c3d4-e5f6-7890-1234-567890abcdef
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Item removed from wishlist successfully",
  "data": true
}
DELETE /api/ProductWishList/remove Auth Required

Remove a single item from the customer's wishlist by sending the wishlist item ID in the request body.

Request Body
Parameter Type Required Description
wishListItemId guid Yes The ID of the wishlist item to remove
Request Example 
DELETE /api/ProductWishList/remove
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "wishListItemId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Item removed from wishlist successfully",
  "data": true
}
PUT /api/ProductWishList/update Auth Required

Update a wishlist item's notes or priority level. This is useful for organizing your wishlist or updating reminders about specific products.

Request Body
Parameter Type Required Description
wishListItemId guid Yes The ID of the wishlist item to update
notes string No Updated notes about the product (max 500 characters)
priority integer No Updated priority level (1-5, where 1 is highest priority)
Request Example 
PUT /api/ProductWishList/update
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "wishListItemId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "notes": "Updated: Buy this next month",
  "priority": 2
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Wishlist item updated successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "productId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "customer-id-here",
    "productName": "Smartphone X",
    "notes": "Updated: Buy this next month",
    "priority": 2,
    "dateUpdated": "2025-01-15T11:00:00Z"
  }
}
GET /api/ProductWishList Auth Required

Get all items in the customer's wishlist with pagination support. Items are returned with full product details including prices, stock status, and images.

Query Parameters
Parameter Type Required Description
page integer No Page number for pagination (default: 1, minimum: 1)
pageSize integer No Number of items per page (default: 20, minimum: 1, maximum: 100)
Request Example 
GET /api/ProductWishList?page=1&pageSize=20
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Wishlist retrieved successfully",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "customerId": "customer-id-here",
      "productName": "Smartphone X",
      "productDescription": "Latest smartphone with advanced features",
      "productImage": "https://example.com/product.jpg",
      "productPrice": 50000.00,
      "compareAtPrice": 60000.00,
      "discountPercentage": 16.67,
      "isInStock": true,
      "stockQuantity": 50,
      "productSlug": "smartphone-x",
      "productSku": "SPX-001",
      "notes": "Need this for birthday gift",
      "priority": 1,
      "dateAdded": "2025-01-15T10:30:00Z",
      "dateUpdated": null,
      "platformId": "platform-id-here",
      "businessId": "business-id-here",
      "environmentType": "Test",
      "categoryName": "Electronics",
      "brandName": "TechBrand"
    }
  ]
}
GET /api/ProductWishList/summary Auth Required

Get a summary of the customer's wishlist with statistics including total items, total value, average item price, stock status breakdown, and priority distribution.

Request Example 
GET /api/ProductWishList/summary
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Wishlist summary retrieved successfully",
  "data": {
    "totalItems": 15,
    "totalValue": 750000.00,
    "averageItemPrice": 50000.00,
    "inStockItems": 12,
    "outOfStockItems": 3,
    "highPriorityItems": 5,
    "mediumPriorityItems": 7,
    "lowPriorityItems": 3,
    "lastUpdated": "2025-01-15T11:00:00Z",
    "dateRangeStart": "2024-12-01T00:00:00Z",
    "dateRangeEnd": "2025-01-15T23:59:59Z"
  }
}
GET /api/ProductWishList/check/{productId} Auth Required

Check if a specific product is already in the customer's wishlist. This is useful for displaying wishlist status on product pages.

Path Parameters
Parameter Type Required Description
productId guid Yes The ID of the product to check
Request Example 
GET /api/ProductWishList/check/550e8400-e29b-41d4-a716-446655440000
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Product check completed",
  "data": true
}
GET /api/ProductWishList/count Auth Required

Get the total number of items in the customer's wishlist. This is useful for displaying wishlist badge counts in the UI.

Request Example 
GET /api/ProductWishList/count
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Wishlist count retrieved successfully",
  "data": 15
}
POST /api/ProductWishList/move-to-cart/{wishListItemId} Auth Required

Move a single item from the wishlist to the shopping cart. The item will be removed from the wishlist and added to the cart with a default quantity of 1.

Path Parameters
Parameter Type Required Description
wishListItemId guid Yes The ID of the wishlist item to move to cart
Request Example 
POST /api/ProductWishList/move-to-cart/a1b2c3d4-e5f6-7890-1234-567890abcdef
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Item moved to cart successfully",
  "data": true
}
POST /api/ProductWishList/move-to-cart Auth Required

Move a single item from the wishlist to the shopping cart with a specified quantity. The item will be removed from the wishlist and added to the cart.

Request Body
Parameter Type Required Description
wishListItemId guid Yes The ID of the wishlist item to move to cart
quantity integer No The quantity to add to cart (default: 1, minimum: 1)
Request Example 
POST /api/ProductWishList/move-to-cart
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "wishListItemId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "quantity": 2
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Item moved to cart successfully",
  "data": true
}
DELETE /api/ProductWishList/clear Auth Required

Clear all items from the customer's wishlist. This operation cannot be undone, so use with caution.

Request Example 
DELETE /api/ProductWishList/clear
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Wishlist cleared successfully",
  "data": true
}
Warning
This operation permanently removes all items from the wishlist and cannot be undone.
POST /api/ProductWishList/bulk-operation Auth Required

Perform bulk operations on multiple wishlist items at once. Supported operations include: remove, update_priority, and move_to_cart.

Request Body
Parameter Type Required Description
wishListItemIds array of guid Yes List of wishlist item IDs to perform the operation on
operation string Yes Operation to perform: "remove", "update_priority", or "move_to_cart"
newPriority integer No New priority level (1-5) - Required for "update_priority" operation
quantity integer No Quantity to add to cart - Optional for "move_to_cart" operation (default: 1)
Request Example - Remove Multiple Items 
POST /api/ProductWishList/bulk-operation
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "wishListItemIds": [
    "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "b2c3d4e5-f6a7-8901-2345-678901bcdefg"
  ],
  "operation": "remove"
}
Request Example - Update Priority 
POST /api/ProductWishList/bulk-operation
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "wishListItemIds": [
    "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "b2c3d4e5-f6a7-8901-2345-678901bcdefg"
  ],
  "operation": "update_priority",
  "newPriority": 1
}
Request Example - Move to Cart 
POST /api/ProductWishList/bulk-operation
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "wishListItemIds": [
    "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "b2c3d4e5-f6a7-8901-2345-678901bcdefg"
  ],
  "operation": "move_to_cart",
  "quantity": 1
}
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Bulk operation completed successfully",
  "data": true
}
Supported Operations
  • remove: Remove all specified items from the wishlist
  • update_priority: Update priority level for all specified items (requires newPriority)
  • move_to_cart: Move all specified items to the shopping cart (optionally specify quantity)

Customer Transactions

View and manage customer transactions and orders. All endpoints in this section require authentication via JWT Bearer token and API key. The customer ID is automatically extracted from the JWT token.

GET /api/customer/transaction/list Auth Required

Get a paginated list of transactions for the authenticated customer with optional filtering by status, transaction type, and date range.

Query Parameters
Parameter Type Required Description
pageNumber integer No Page number for pagination (default: 1, min: 1)
pageSize integer No Number of items per page (default: 50, min: 1, max: 100)
status TransactionStatus No Filter by transaction status. Values: Pending (0), Successful (1), Failed (2)
transactionType string No Filter by transaction type (partial match, case-insensitive). Examples: "Payment", "Refund", "Wallet Credit", "Wallet Debit", "Bills Payment", "BNPL Payment", "Card Funding"
startDate DateTime No Filter transactions from this date (format: yyyy-MM-dd or ISO 8601)
endDate DateTime No Filter transactions until this date (format: yyyy-MM-dd or ISO 8601). Includes the entire end date.
Request Example 
GET /api/customer/transaction/list?pageNumber=1&pageSize=50&status=1&transactionType=Payment&startDate=2024-01-01&endDate=2024-12-31
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Successfully retrieved customer transactions",
  "data": {
    "transactions": [
      {
        "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "customerId": "customer-id-here",
        "platformId": "platform-id-here",
        "businessId": "business-id-here",
        "transactionReference": "TXN-2024-001234",
        "amount": 50000.00,
        "transactionType": "Payment",
        "status": 1,
        "description": "Order payment for Order #12345",
        "gateway": "Paystack",
        "gatewayTransactionId": "PS-TXN-ABC123",
        "environment": 1,
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:05Z",
        "customerFirstName": "John",
        "customerLastName": "Doe",
        "customerEmail": "john.doe@example.com",
        "statusDisplay": "Successful",
        "transactionTypeDisplay": "Payment",
        "amountDisplay": "-50000.00",
        "customerDisplayName": "John Doe"
      }
    ],
    "totalCount": 125,
    "pageNumber": 1,
    "pageSize": 50,
    "totalPages": 3,
    "currentBalance": 150000.00
  }
}
Transaction Balance
The currentBalance field represents the customer's current balance calculated from all successful transactions. Credits (Refunds, Wallet Credits) are added, while debits (Payments, Wallet Debits) are subtracted.
GET /api/customer/transaction/orders Auth Required

Get a paginated list of orders for the authenticated customer with optional filtering by order status and date range.

Query Parameters
Parameter Type Required Description
pageNumber integer No Page number for pagination (default: 1, min: 1)
pageSize integer No Number of items per page (default: 50, min: 1, max: 100)
orderStatus OrderStatus No Filter by order status. Values: Success, Pending, Failed, Confirmed, Returned, Accepted
startDate DateTime No Filter orders from this date (format: yyyy-MM-dd or ISO 8601)
endDate DateTime No Filter orders until this date (format: yyyy-MM-dd or ISO 8601). Includes the entire end date.
Request Example 
GET /api/customer/transaction/orders?pageNumber=1&pageSize=50&orderStatus=Success&startDate=2024-01-01&endDate=2024-12-31
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
Success Response (200 OK)
Status: 200 OK
{
  "success": true,
  "message": "Retrieved 25 orders successfully",
  "data": {
    "orders": [
      {
        "id": "order-id-here",
        "platformId": "platform-id-here",
        "businessId": "business-id-here",
        "customerId": "customer-id-here",
        "products": [
          {
            "productId": "product-id-here",
            "quantity": 2,
            "productName": "Smartphone X",
            "price": 50000.00,
            "productImage": "https://example.com/product.jpg"
          }
        ],
        "address": "123 Main Street, Lagos, Nigeria",
        "pickUpLocation": "store-location-id",
        "pickupLocationId": "store-location-id",
        "pickupLocationName": "Lagos - Victoria Island Store",
        "isAvailableForDelivery": true,
        "orderStatus": 0,
        "environmentType": 1,
        "transactionReference": "TXN-2024-001234",
        "totalAmount": 100000.00,
        "dateCreated": "2024-01-15T10:30:00Z",
        "dateUpdated": "2024-01-15T10:35:00Z",
        "orderStatusDisplay": "Success",
        "environmentTypeDisplay": "Test",
        "totalProducts": 2,
        "uniqueProducts": 1
      }
    ],
    "totalCount": 45,
    "pageNumber": 1,
    "pageSize": 50,
    "totalPages": 1
  }
}
Order Details
Each order includes enriched product information (name, price, image) and pickup location details if applicable. The totalProducts field represents the total quantity of items, while uniqueProducts represents the number of different products in the order.