API Documentation

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"
  }'

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/customerprofile/profile \
  -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)

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"
}

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",
    "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",
    "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 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",
    "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",
    "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, it must meet the password 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.

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",
    "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"}.

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.

Per-branch carts

Each store branch has its own cart. Pass locationItemId and storeLocationId when adding items (from GET /api/PickUpLocation). Pass optional query locationItemId on summary, items, count, and clear to scope those calls to that branch. Switching branches does not delete other branches' carts — items reappear when the customer returns to that branch. Stock is checked against the product's stock at that locationItemId.

POST /api/customer/cart/add Auth Required

Add a product to the customer's cart for a specific store branch. If the same product already exists for that branch, the quantity is increased. The same product can exist separately in another branch's cart.

Request Body

Parameter	Type	Required	Description
`productId`	guid	Yes	Product ID to add to cart
`quantity`	integer	Yes	Quantity to add (minimum: 1)
`locationItemId`	guid	Yes	Branch ID (`locationItemId` from pickup locations). Used for per-branch cart and stock.
`storeLocationId`	guid	Yes	Parent store location ID (`storeLocationId` from pickup locations).
`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,
  "locationItemId": "aa0e8400-e29b-41d4-a716-446655440001",
  "storeLocationId": "770e8400-e29b-41d4-a716-446655440000"
}

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,
    "locationItemId": "aa0e8400-e29b-41d4-a716-446655440001",
    "storeLocationId": "770e8400-e29b-41d4-a716-446655440000",
    "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 cart items. Pass optional locationItemId to clear only that branch's cart; omit it to clear all branches for this customer/platform.

Query Parameters

Parameter	Type	Required	Description
`locationItemId`	guid	No	When set, clears only the cart for this branch

Request Example

DELETE /api/customer/cart/clear?locationItemId=aa0e8400-e29b-41d4-a716-446655440001
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 items, totals, and branch IDs. Pass locationItemId to return only that branch's cart (recommended for multi-location stores).

Query Parameters

Parameter	Type	Required	Description
`locationItemId`	guid	No	Filter cart to this store branch

Request Example

GET /api/customer/cart/summary?locationItemId=aa0e8400-e29b-41d4-a716-446655440001
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,
        "locationItemId": "aa0e8400-e29b-41d4-a716-446655440001",
        "storeLocationId": "770e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "totalItems": 2,
    "subTotal": 199.98,
    "taxAmount": 0,
    "shippingAmount": 0,
    "totalAmount": 199.98,
    "hasOutOfStockItems": false,
    "locationItemId": "aa0e8400-e29b-41d4-a716-446655440001",
    "storeLocationId": "770e8400-e29b-41d4-a716-446655440000",
    "lastUpdated": "2025-01-15T10:30:00Z"
  }
}

GET /api/customer/cart/items Auth Required

Get cart line items. Pass locationItemId to return only that branch's items.

Query Parameters

Parameter	Type	Required	Description
`locationItemId`	guid	No	Filter items to this store branch

Request Example

GET /api/customer/cart/items?locationItemId=aa0e8400-e29b-41d4-a716-446655440001
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,
      "locationItemId": "aa0e8400-e29b-41d4-a716-446655440001",
      "storeLocationId": "770e8400-e29b-41d4-a716-446655440000",
      "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 number of cart line items. Pass locationItemId to count only that branch's cart.

Query Parameters

Parameter	Type	Required	Description
`locationItemId`	guid	No	Count only items for this store branch

Request Example

GET /api/customer/cart/count?locationItemId=aa0e8400-e29b-41d4-a716-446655440001
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 a 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.

Branch required at checkout

Checkout requires both storeLocationId (parent store locations row) and locationItemId (the branch from GET /api/PickUpLocation). Stock is validated against that branch. Use the same IDs as when the customer added items to cart. Recommended flow: pick branch → add to cart with both IDs → load cart with ?locationItemId= → checkout with both IDs.

POST /api/checkout Auth Required

Process checkout using a payment gateway. Set paymentMethod to PaymentGateway and provide a redirectUrl.

Automatic Routing

Prefer POST /api/checkout/payment-gateway for explicit payment-gateway checkout, or use this endpoint with paymentMethod set to PaymentGateway.

Request Body

Parameter	Type	Required	Description
`totalAmount`	decimal	Yes	Total amount for the order (minimum: 0.01)
`paymentMethod`	enum	Yes	Payment method: `PaymentGateway`
`products`	array	Yes	List of products with quantities (at least 1 product required)
`storeLocationId`	guid	Yes	Parent store location ID (from pickup locations)
`locationItemId`	guid	Yes	Branch ID for stock validation and order audit (from pickup locations)
`address`	string	No	Delivery address (required when `deliveryOption` is Delivery)
`redirectUrl`	string	Yes	Redirect URL after payment gateway checkout completes

* Conditional: redirectUrl is required for payment gateway checkout.

Products Array Item

Parameter	Type	Required	Description
`productId`	guid	Yes	Product ID (GUID)
`quantity`	integer	Yes	Quantity of the product (minimum: 1)

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",
  "locationItemId": "aa0e8400-e29b-41d4-a716-446655440001",
  "redirectUrl": "https://yourapp.com/payment/callback"
}

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/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",
  "locationItemId": "aa0e8400-e29b-41d4-a716-446655440001",
  "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:

Display the available companies to the customer
Allow the customer to select a delivery company
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": "PaymentGateway",
  "products": [
    {
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "quantity": 2
    }
  ],
  "storeLocationId": "770e8400-e29b-41d4-a716-446655440000",
  "locationItemId": "aa0e8400-e29b-41d4-a716-446655440001",
  "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",
  "redirectUrl": "https://your-store.com/checkout/callback"
}

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

Parameter	Type	Required	Description
`providerAddressId`	string	Yes	ID of the address to update (from get response)
`line1`	string	Yes	Street address
`line2`	string	No	Address line 2
`city`	string	Yes	City
`state`	string	Yes	State
`country`	string	Yes	Country code (e.g. NG), max 2 chars
`zip`	string	No	Postal code
`firstName`	string	No	First name
`lastName`	string	No	Last name
`email`	string	No	Email
`phone`	string	No	Phone
`isResidential`	boolean	No	Residential 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

Parameter	Type	Required	Description
`providerAddressId`	string	Yes	ID 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 / store branches for the platform. Use locationItemId and storeLocationId from each item when adding to cart and at checkout.

Request Example

GET /api/PickUpLocation
Headers:
  x-api-key: your-api-key-here

Success Response (200 OK)

Status: 200 OK

{
  "success": true,
  "message": "Store locations retrieved successfully",
  "data": [
    {
      "storeLocationId": "770e8400-e29b-41d4-a716-446655440000",
      "locationItemId": "aa0e8400-e29b-41d4-a716-446655440001",
      "name": "Lagos — 123 Main Street, Lagos",
      "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",
      "locationItemId": "aa0e8400-e29b-41d4-a716-446655440001",
      "name": "Lagos — 123 Main Street, Lagos",
      "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",
    "locationItemId": "aa0e8400-e29b-41d4-a716-446655440001",
    "name": "Lagos — 123 Main Street, Lagos",
    "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
}

Transactions

Verify payment transaction status after checkout. Requires authentication via JWT Bearer token.

POST /api/transaction/verify-transaction Auth Required

Verify the status of a checkout payment transaction using the transaction reference returned by the payment gateway.

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. All endpoints require authentication via JWT Bearer token and API key. The customer ID is extracted from the JWT.

Payment gateway (Paystack)

Store bills are paid via payment gateway, not shopping card or transaction PIN. Flow: load services/plans → validate (electricity/cable) → POST /api/BillsPayment/checkout/create-and-pay → redirect customer to authorizationUrl → on return call POST /api/BillsPayment/checkout/complete with the Paystack reference. Amount must be between 50 and 500000. A callbackUrl is required on create-and-pay.

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)
`packageSlug`	string	Yes	Selected meter plan slug from disco plans

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,
  "packageSlug": "ekedc-prepaid"
}

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"
  }
}

Pay via Payment Gateway

POST /api/BillsPayment/checkout/create-and-pay Auth Required

Create a pending store bill payment and initialize Paystack checkout. Returns an authorizationUrl to redirect the customer. After payment, call complete with the same reference.

Request Body

Parameter	Type	Required	Description
`billType`	string	Yes	One of: `Airtime`, `Data`, `Electricity`, `Cable`
`serviceName`	string	No	Provider display name (e.g. MTN, EKEDC, DSTV)
`serviceId`	guid	Conditional	Required for fulfillment (from services endpoints)
`phoneNumber`	string	Conditional	Required for Airtime and Data
`customerIdentifier`	string	Conditional	Meter number (Electricity) or smart card number (Cable)
`packageSlug`	string	Conditional	Required for Data, Electricity, and Cable plans
`billerId`	integer	Conditional	Required for Data, Electricity, and Cable (from plans response)
`billerSlug`	string	Conditional	Required for Electricity and Cable
`period`	string	No	Optional period for Data (Daily, Weekly, Monthly)
`amount`	decimal	Yes	Bill amount (min 50, max 500000). Fee is added server-side.
`callbackUrl`	string	Yes	Frontend URL Paystack redirects to after payment

Request Example (Airtime)

POST /api/BillsPayment/checkout/create-and-pay
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "billType": "Airtime",
  "serviceName": "MTN",
  "serviceId": "550e8400-e29b-41d4-a716-446655440001",
  "phoneNumber": "08012345678",
  "amount": 1000.00,
  "callbackUrl": "https://yourstore.example/bills"
}

Request Example (Electricity)

POST /api/BillsPayment/checkout/create-and-pay
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "billType": "Electricity",
  "serviceName": "EKEDC",
  "serviceId": "550e8400-e29b-41d4-a716-446655440005",
  "customerIdentifier": "12345678901",
  "packageSlug": "ekedc-prepaid",
  "billerId": 201,
  "billerSlug": "ekedc",
  "amount": 5000.00,
  "callbackUrl": "https://yourstore.example/bills"
}

Success Response (200 OK)

Status: 200 OK

{
  "success": true,
  "message": "Checkout initialized",
  "data": {
    "storeBillPaymentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "authorizationUrl": "https://checkout.paystack.com/abc123",
    "accessCode": "access_code_here",
    "reference": "SBILL_abc123xyz",
    "amount": 1000.00,
    "fee": 50.00,
    "totalAmount": 1050.00
  }
}

Next step

Redirect the customer to authorizationUrl. When they return to your callbackUrl, read the Paystack reference (query/param) and call complete.

POST /api/BillsPayment/checkout/complete Auth Required

After Paystack redirect, verify the payment and fulfill the bill (CoralPay). Returns gateway and fulfillment status, plus token/reference when available (e.g. electricity token).

Request Body

Parameter	Type	Required	Description
`reference`	string	Yes	Paystack payment reference from create-and-pay / callback

Request Example

POST /api/BillsPayment/checkout/complete
Headers:
  x-api-key: your-api-key-here
  Authorization: Bearer your-jwt-token-here
  Content-Type: application/json

Body:
{
  "reference": "SBILL_abc123xyz"
}

Success Response (200 OK)

Status: 200 OK

{
  "success": true,
  "message": "Bill fulfilled successfully",
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "platformId": "550e8400-e29b-41d4-a716-446655440000",
    "businessId": "550e8400-e29b-41d4-a716-446655440010",
    "customerId": "550e8400-e29b-41d4-a716-446655440020",
    "billType": "Electricity",
    "serviceName": "EKEDC",
    "amount": 5000.00,
    "fee": 50.00,
    "totalAmount": 5050.00,
    "paystackReference": "SBILL_abc123xyz",
    "gatewayStatus": "Success",
    "fulfillmentStatus": "Success",
    "errorMessage": null,
    "coralPayTransactionReference": "CPAY_REF_123",
    "coralPayToken": "TOKEN_OR_PIN_12345",
    "createdAt": "2026-08-02T10:00:00Z",
    "paidAt": "2026-08-02T10:01:00Z",
    "fulfilledAt": "2026-08-02T10:01:05Z"
  }
}

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). Example: "Payment"
`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 is included for reference. Filter transactions with type Payment for order payments.

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.

Quick Navigation

Getting Started

Required Headers

Authentication

Register Customer

Login Customer

Email Verification

Forgot Password

Get Customer By ID

Customer Profile

Products

Cart Management

Checkout & Payment

Delivery Quotes

Saved Delivery Addresses

Pickup Locations

Transactions

Bills Payment

Categories

Services

Plans

Customer Validation

Pay via Payment Gateway

Wishlist

Customer Transactions