Installment Plan Management - Admin/Shop Endpoints

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2025-10-18
Version: v1.0

Base URL: https://api.nextgate.com/api/v1/products/{shopId}/{productId}/installment-plans

Short Description: This API provides comprehensive endpoints for shop owners and administrators to create, manage, and configure installment plans for their products. Shop owners can define flexible payment terms including payment frequencies, interest rates, down payment requirements, grace periods, and fulfillment options. The API supports full CRUD operations, plan activation/deactivation, featured plan selection, and product-level installment enablement. All endpoints require authentication and validate shop ownership.

Hints:

All endpoints require authentication and shop ownership validation
Shop owners can only manage plans for their own products
Multiple plans can be created per product for different customer segments
Only one plan per product can be featured at a time
Plans can be deactivated without deletion to preserve historical data
Active plans are automatically available to customers on product pages
Inactive plans are hidden from customers but preserved for existing agreements
Payment frequencies support daily, weekly, bi-weekly, semi-monthly, monthly, quarterly, and custom intervals
APR (Annual Percentage Rate) must be between 0% and 36%
Down payment requirements: 10-50% range
Grace periods: 0-60 days before first payment
Fulfillment options: IMMEDIATE (ship after down payment) or AFTER_PAYMENT (ship after completion)
Display order determines plan sorting on product pages
Featured plans get "Most Popular" or "Recommended" badge
Enabling/disabling installments at product level affects all plans

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-10-18T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-10-18T10:30:45",
  "data": "Error description"
}

Standard Response Fields

Field	Type	Description
`success`	boolean	Always `true` for successful operations, `false` for errors
`httpStatus`	string	HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
`message`	string	Human-readable message describing the operation result
`action_time`	string	ISO 8601 timestamp of when the response was generated
`data`	object/string	Response payload for success, error details for failures

HTTP Method Badge Standards

For better visual clarity, all endpoints use colored badges for HTTP methods with the following standard colors:

GET - GET - Green (Safe, read-only operations)
POST - POST - Blue (Create new resources)
PUT - PUT - Yellow (Update/replace entire resource)
PATCH - PATCH - Orange (Partial updates)
DELETE - DELETE - Red (Remove resources)

Endpoints

1. Create Installment Plan

Purpose: Create a new installment plan for a specific product

Endpoint: POST {base_url}

Access Level: 🔒 Protected (Requires Authentication, Shop Owner Only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Valid UUID format, must be owned by authenticated user
productId	UUID	Yes	Unique identifier of the product	Valid UUID format, must belong to specified shop
planId	UUID	Yes	Unique identifier of the plan to deactivate	Valid UUID format, must belong to specified product

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Installment plan deactivated successfully",
  "action_time": "2025-10-18T10:30:45",
  "data": {
    "planId": "6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a",
    "planName": "Budget Friendly Plan",
    "isActive": false,
    "updatedAt": "2025-10-18T10:30:45"
  }
}

Success Response Fields:

Field	Description
planId	ID of the deactivated plan
planName	Name of the plan
isActive	Active status (false)
updatedAt	Update timestamp

Error Response Examples: Same as Activate Installment Plan endpoint

Important Notes:

Deactivated plans are hidden from customers on product pages
Existing agreements continue to use deactivated plans
Plan can be reactivated at any time
Deactivation is preferred over deletion for plans with existing agreements

2. Get Product Installment Plans

Purpose: Retrieve all installment plans for a specific product (including inactive plans for admin view)

Endpoint: GET {base_url}

Access Level: 🔒 Protected (Requires Authentication, Shop Owner Only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Valid UUID format, must be owned by authenticated user
productId	UUID	Yes	Unique identifier of the product	Valid UUID format, must belong to specified shop

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Installment plans retrieved successfully",
  "action_time": "2025-10-18T10:30:45",
  "data": [
    {
      "planId": "4b5c6d7e-8f9a-4b1c-9d2e-3f4a5b6c7d8e",
      "planName": "Quick Payment Plan",
      "paymentFrequency": "WEEKLY",
      "paymentFrequencyDisplay": "Weekly",
      "customFrequencyDays": null,
      "numberOfPayments": 8,
      "calculatedDurationDays": 56,
      "calculatedDurationDisplay": "8 weeks",
      "apr": 10.00,
      "minDownPaymentPercent": 20,
      "gracePeriodDays": 7,
      "fulfillmentTiming": "IMMEDIATE",
      "isActive": true,
      "isFeatured": false,
      "displayOrder": 1,
      "productId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "productName": "Samsung Galaxy S24 Ultra",
      "shopId": "8d3a7b12-9c4e-4f8a-b5d2-3e6f7a8b9c0d",
      "shopName": "Tech World Store",
      "createdAt": "2025-10-15T09:00:00",
      "updatedAt": "2025-10-15T09:00:00"
    },
    {
      "planId": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
      "planName": "12 Month Standard Plan",
      "paymentFrequency": "MONTHLY",
      "paymentFrequencyDisplay": "Monthly",
      "customFrequencyDays": null,
      "numberOfPayments": 12,
      "calculatedDurationDays": 360,
      "calculatedDurationDisplay": "12 months",
      "apr": 15.00,
      "minDownPaymentPercent": 20,
      "gracePeriodDays": 30,
      "fulfillmentTiming": "IMMEDIATE",
      "isActive": true,
      "isFeatured": true,
      "displayOrder": 2,
      "productId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "productName": "Samsung Galaxy S24 Ultra",
      "shopId": "8d3a7b12-9c4e-4f8a-b5d2-3e6f7a8b9c0d",
      "shopName": "Tech World Store",
      "createdAt": "2025-10-16T10:30:00",
      "updatedAt": "2025-10-16T10:30:00"
    },
    {
      "planId": "6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a",
      "planName": "Budget Friendly Plan",
      "paymentFrequency": "MONTHLY",
      "paymentFrequencyDisplay": "Monthly",
      "customFrequencyDays": null,
      "numberOfPayments": 24,
      "calculatedDurationDays": 720,
      "calculatedDurationDisplay": "24 months",
      "apr": 18.00,
      "minDownPaymentPercent": 10,
      "gracePeriodDays": 30,
      "fulfillmentTiming": "AFTER_PAYMENT",
      "isActive": false,
      "isFeatured": false,
      "displayOrder": 3,
      "productId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "productName": "Samsung Galaxy S24 Ultra",
      "shopId": "8d3a7b12-9c4e-4f8a-b5d2-3e6f7a8b9c0d",
      "shopName": "Tech World Store",
      "createdAt": "2025-10-17T14:00:00",
      "updatedAt": "2025-10-18T08:00:00"
    }
  ]
}

Success Response Fields: Same as Create Installment Plan endpoint, returned as array

Error Response Examples:

Forbidden (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "You do not have permission to view this shop's products",
  "action_time": "2025-10-18T10:30:45",
  "data": "You do not have permission to view this shop's products"
}

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Product not found",
  "action_time": "2025-10-18T10:30:45",
  "data": "Product not found"
}

3. Get Installment Plan By ID

Purpose: Retrieve detailed information about a specific installment plan

Endpoint: GET {base_url}/{planId}

Access Level: 🔒 Protected (Requires Authentication, Shop Owner Only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Valid UUID format, must be owned by authenticated user
productId	UUID	Yes	Unique identifier of the product	Valid UUID format, must belong to specified shop
planId	UUID	Yes	Unique identifier of the plan	Valid UUID format, must belong to specified product

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Installment plan retrieved successfully",
  "action_time": "2025-10-18T10:30:45",
  "data": {
    "planId": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
    "planName": "12 Month Standard Plan",
    "paymentFrequency": "MONTHLY",
    "paymentFrequencyDisplay": "Monthly",
    "customFrequencyDays": null,
    "numberOfPayments": 12,
    "calculatedDurationDays": 360,
    "calculatedDurationDisplay": "12 months",
    "apr": 15.00,
    "minDownPaymentPercent": 20,
    "gracePeriodDays": 30,
    "fulfillmentTiming": "IMMEDIATE",
    "isActive": true,
    "isFeatured": true,
    "displayOrder": 2,
    "productId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "productName": "Samsung Galaxy S24 Ultra",
    "shopId": "8d3a7b12-9c4e-4f8a-b5d2-3e6f7a8b9c0d",
    "shopName": "Tech World Store",
    "createdAt": "2025-10-16T10:30:00",
    "updatedAt": "2025-10-16T10:30:00",
    "metadata": {}
  }
}

Success Response Fields: Same as Create Installment Plan endpoint

Error Response Examples: Same as Get Product Installment Plans endpoint, plus:

Not Found - Plan (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Installment plan not found",
  "action_time": "2025-10-18T10:30:45",
  "data": "Installment plan not found"
}

4. Update Installment Plan

Purpose: Update an existing installment plan's configuration

Endpoint: PUT {base_url}/{planId}

Access Level: 🔒 Protected (Requires Authentication, Shop Owner Only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	application/json

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Valid UUID format, must be owned by authenticated user
productId	UUID	Yes	Unique identifier of the product	Valid UUID format, must belong to specified shop
planId	UUID	Yes	Unique identifier of the plan to update	Valid UUID format, must belong to specified product

Request JSON Sample:

{
  "planName": "12 Month Premium Plan",
  "paymentFrequency": "MONTHLY",
  "customFrequencyDays": null,
  "numberOfPayments": 12,
  "apr": 12.00,
  "minDownPaymentPercent": 25,
  "gracePeriodDays": 45,
  "fulfillmentTiming": "IMMEDIATE",
  "displayOrder": 1
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
planName	string	No	Updated display name	Min: 3, Max: 100 characters
paymentFrequency	string	No	Updated payment frequency	enum: DAILY, WEEKLY, BI_WEEKLY, SEMI_MONTHLY, MONTHLY, QUARTERLY, CUSTOM_DAYS
customFrequencyDays	integer	Conditional	Updated custom frequency	Required if paymentFrequency is CUSTOM_DAYS, Min: 1, Max: 365
numberOfPayments	integer	No	Updated number of payments	Min: 2, Max: 120
apr	decimal	No	Updated APR	Min: 0.00, Max: 36.00
minDownPaymentPercent	integer	No	Updated minimum down payment	Min: 10, Max: 50
gracePeriodDays	integer	No	Updated grace period	Min: 0, Max: 60
fulfillmentTiming	string	No	Updated fulfillment option	enum: IMMEDIATE, AFTER_PAYMENT
displayOrder	integer	No	Updated display order	Min: 0

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Installment plan updated successfully",
  "action_time": "2025-10-18T10:30:45",
  "data": {
    "planId": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
    "planName": "12 Month Premium Plan",
    "paymentFrequency": "MONTHLY",
    "paymentFrequencyDisplay": "Monthly",
    "customFrequencyDays": null,
    "numberOfPayments": 12,
    "calculatedDurationDays": 360,
    "calculatedDurationDisplay": "12 months",
    "apr": 12.00,
    "minDownPaymentPercent": 25,
    "gracePeriodDays": 45,
    "fulfillmentTiming": "IMMEDIATE",
    "isActive": true,
    "isFeatured": true,
    "displayOrder": 1,
    "productId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "productName": "Samsung Galaxy S24 Ultra",
    "shopId": "8d3a7b12-9c4e-4f8a-b5d2-3e6f7a8b9c0d",
    "shopName": "Tech World Store",
    "createdAt": "2025-10-16T10:30:00",
    "updatedAt": "2025-10-18T10:30:45"
  }
}

Success Response Fields: Same as Create Installment Plan endpoint

Error Response Examples: Same as Create Installment Plan endpoint

Important Notes:

Updating a plan only affects new agreements created after the update
Existing agreements continue using the original terms
Cannot update isActive or isFeatured via this endpoint (use dedicated endpoints)

5. Delete Installment Plan

Purpose: Permanently delete an installment plan (only if no active agreements exist)

Endpoint: DELETE {base_url}/{planId}

Access Level: 🔒 Protected (Requires Authentication, Shop Owner Only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Valid UUID format, must be owned by authenticated user
productId	UUID	Yes	Unique identifier of the product	Valid UUID format, must belong to specified shop
planId	UUID	Yes	Unique identifier of the plan to delete	Valid UUID format, must belong to specified product

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Installment plan deleted successfully",
  "action_time": "2025-10-18T10:30:45",
  "data": null
}

Success Response Fields: No data returned on successful deletion

Error Response Examples:

Bad Request - Has Active Agreements (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot delete plan with active agreements. Deactivate the plan instead.",
  "action_time": "2025-10-18T10:30:45",
  "data": "Cannot delete plan with active agreements. Deactivate the plan instead."
}

Forbidden (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "You do not have permission to delete this plan",
  "action_time": "2025-10-18T10:30:45",
  "data": "You do not have permission to delete this plan"
}

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Installment plan not found",
  "action_time": "2025-10-18T10:30:45",
  "data": "Installment plan not found"
}

6. Activate Installment Plan

Purpose: Activate an installment plan to make it available to customers

Endpoint: PATCH {base_url}/{planId}/activate

Access Level: 🔒 Protected (Requires Authentication, Shop Owner Only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Valid UUID format, must be owned by authenticated user
productId	UUID	Yes	Unique identifier of the product	Valid UUID format, must belong to specified shop
planId	UUID	Yes	Unique identifier of the plan to activate	Valid UUID format, must belong to specified product

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Installment plan activated successfully",
  "action_time": "2025-10-18T10:30:45",
  "data": {
    "planId": "6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a",
    "planName": "Budget Friendly Plan",
    "isActive": true,
    "updatedAt": "2025-10-18T10:30:45"
  }
}

Success Response Fields:

Field	Description
planId	ID of the activated plan
planName	Name of the plan
isActive	Active status (true)
updatedAt	Update timestamp

Error Response Examples: Same as Delete Installment Plan endpoint

7. Deactivate Installment Plan

Purpose: Deactivate an installment plan to hide it from customers (preserves data for existing agreements)

Endpoint: PATCH {base_url}/{planId}/deactivate

Access Level: 🔒 Protected (Requires Authentication, Shop Owner Only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token

8. Set Featured Plan

Purpose: Mark a plan as featured (recommended/most popular) - only one plan per product can be featured

Endpoint: PATCH {base_url}/{planId}/set-featured

Access Level: 🔒 Protected (Requires Authentication, Shop Owner Only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Valid UUID format, must be owned by authenticated user
productId	UUID	Yes	Unique identifier of the product	Valid UUID format, must belong to specified shop
planId	UUID	Yes	Unique identifier of the plan to feature	Valid UUID format, must belong to specified product

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Featured plan set successfully",
  "action_time": "2025-10-18T10:30:45",
  "data": {
    "planId": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
    "planName": "12 Month Premium Plan",
    "isFeatured": true,
    "previousFeaturedPlanId": "4b5c6d7e-8f9a-4b1c-9d2e-3f4a5b6c7d8e",
    "updatedAt": "2025-10-18T10:30:45"
  }
}

Success Response Fields:

Field	Description
planId	ID of the newly featured plan
planName	Name of the plan
isFeatured	Featured status (true)
previousFeaturedPlanId	ID of previously featured plan (null if none)
updatedAt	Update timestamp

Error Response Examples: Same as Activate Installment Plan endpoint

Important Notes:

Setting a plan as featured automatically un-features any previously featured plan
Only active plans should be featured
Featured plans typically display "Most Popular" or "Recommended" badge
Featured plans often appear first in plan listings

9. Enable Installments for Product

Purpose: Enable installment payment option for a product (makes all active plans available)

Endpoint: PATCH {base_url}/enable-installments

Access Level: 🔒 Protected (Requires Authentication, Shop Owner Only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Valid UUID format, must be owned by authenticated user
productId	UUID	Yes	Unique identifier of the product	Valid UUID format, must belong to specified shop

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Installments enabled successfully for product",
  "action_time": "2025-10-18T10:30:45",
  "data": {
    "productId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "productName": "Samsung Galaxy S24 Ultra",
    "installmentAvailable": true,
    "activePlansCount": 2,
    "updatedAt": "2025-10-18T10:30:45"
  }
}

Success Response Fields:

Field	Description
productId	ID of the product
productName	Name of the product
installmentAvailable	Installment availability status (true)
activePlansCount	Number of active plans for this product
updatedAt	Update timestamp

Error Response Examples:

Bad Request - No Plans (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot enable installments: No installment plans created for this product",
  "action_time": "2025-10-18T10:30:45",
  "data": "Cannot enable installments: No installment plans created for this product"
}

Forbidden (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "You do not have permission to modify this product",
  "action_time": "2025-10-18T10:30:45",
  "data": "You do not have permission to modify this product"
}

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Product not found",
  "action_time": "2025-10-18T10:30:45",
  "data": "Product not found"
}

10. Disable Installments for Product

Purpose: Disable installment payment option for a product (hides all plans from customers)

Endpoint: PATCH {base_url}/disable-installments

Access Level: 🔒 Protected (Requires Authentication, Shop Owner Only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Valid UUID format, must be owned by authenticated user
productId	UUID	Yes	Unique identifier of the product	Valid UUID format, must belong to specified shop

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Installments disabled successfully for product",
  "action_time": "2025-10-18T10:30:45",
  "data": {
    "productId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "productName": "Samsung Galaxy S24 Ultra",
    "installmentAvailable": false,
    "activePlansCount": 2,
    "updatedAt": "2025-10-18T10:30:45"
  }
}

Success Response Fields: Same as Enable Installments endpoint

Error Response Examples: Same as Enable Installments endpoint

Important Notes:

Disabling installments hides the option from product page
Existing agreements continue to function normally
Plans are preserved and can be reactivated
Customers with active agreements can still make payments

Common HTTP Status Codes

200 OK: Successful request
400 Bad Request: Invalid request data or business logic violation
401 Unauthorized: Authentication required/failed
403 Forbidden: Insufficient permissions or not shop owner
404 Not Found: Resource not found
422 Unprocessable Entity: Validation errors
500 Internal Server Error: Server error

Payment Frequency Options

DAILY: Payment every day (1 day)
WEEKLY: Payment every week (7 days)
BI_WEEKLY: Payment every 2 weeks (14 days)
SEMI_MONTHLY: Payment twice per month (~15 days)
MONTHLY: Payment every month (~30 days)
QUARTERLY: Payment every 3 months (~90 days)
CUSTOM_DAYS: Custom interval (1-365 days)

Fulfillment Timing Options

IMMEDIATE: Product ships after down payment, customer receives product while paying installments
AFTER_PAYMENT: Product ships after final payment (layaway model), inventory held during payment period

Plan Configuration Constraints

Parameter	Minimum	Maximum	Notes
APR	0%	36%	Platform-enforced limit
Down Payment	10%	50%	Minimum by plan, maximum platform-wide
Number of Payments	2	120	Typical range: 4-24 payments
Grace Period	0 days	60 days	Days before first payment
Custom Frequency	1 day	365 days	Only for CUSTOM_DAYS type
Plan Name	3 chars	100 chars	Must be unique per product

Plan States and Lifecycle

Active Plan

Visible to customers on product page
Can be selected during checkout
Creates new agreements
Appears in public API responses

Inactive Plan

Hidden from customers
Cannot be selected for new purchases
Existing agreements continue
Visible only to shop owner

Featured Plan

Displays "Most Popular" or "Recommended" badge
Only one plan per product can be featured
Typically listed first in plan options
Used for promoting preferred payment terms

Deleted Plan

Permanently removed from system
Only possible if no agreements exist
Cannot be recovered
Use deactivation instead for preservation

Business Rules Summary

One Featured Plan: Only one plan per product can be featured at a time
Shop Ownership: Only shop owners can manage their product plans
Active Plans Only: Customers only see active plans for products with installments enabled
No Deletion with Agreements: Plans with existing agreements cannot be deleted, only deactivated
Update Impact: Plan updates only affect new agreements, not existing ones
Product-Level Control: Disabling installments at product level hides all plans
Duration Calculation: System automatically calculates duration based on frequency and payment count
Validation: All parameters validated against platform constraints
Plan Minimum: At least one active plan required to enable installments on product
Historical Preservation: Deactivated plans preserved for agreement history

Common Workflows

Creating a New Installment Plan

Ensure product exists and you own the shop
POST /installment-plans with plan configuration
Verify plan appears in GET /installment-plans
Optionally set as featured via PATCH /set-featured
Enable installments on product if not already enabled

Managing Multiple Plans

Create multiple plans for different customer segments
- Quick payment plan (8 weeks, 10% APR)
- Standard plan (12 months, 15% APR)
- Budget plan (24 months, 18% APR)
Set most balanced plan as featured
Order by display priority (displayOrder field)
Monitor customer preferences and adjust

Temporarily Disabling Plans

PATCH /deactivate for specific plan
OR PATCH /disable-installments for all plans
Existing agreements continue normally
Reactivate when ready with PATCH /activate or /enable-installments

Updating Plan Terms

Analyze current agreement performance
PUT /installment-plans/{planId} with new terms
New terms apply only to future agreements
Consider creating new plan for major changes

Deleting Unused Plans

Check if plan has any agreements (attempt delete will fail if so)
DELETE /installment-plans/{planId}
Plan permanently removed
If has agreements, use deactivate instead

Client-Side Validation

Validate shop/product ownership before API call
Check APR within 0-36% range
Verify down payment within 10-50% range
Validate payment count between 2-120
Ensure customFrequencyDays present for CUSTOM_DAYS
Check plan name length (3-100 characters)

Server-Side Error Handling

400: Display user-friendly message, allow retry
403: Show "Insufficient permissions" message
404: Redirect to product list or show error
422: Display field-specific validation errors
500: Generic error message, log for investigation

Testing Scenarios

Happy Path

Create plan with valid parameters
Retrieve plan and verify all fields
Update plan configuration
Set as featured plan
Activate/deactivate plan
Enable/disable product installments

Edge Cases

Create multiple plans with same parameters
Set featured when no featured plan exists
Set featured when another plan is featured
Update plan to use custom frequency
Deactivate only active plan
Enable installments with no active plans

Error Cases

Invalid shop/product IDs → 404
Non-owner attempting management → 403
APR outside 0-36% range → 422
Down payment outside 10-50% → 422
Delete plan with agreements → 400
Missing required fields → 422
Invalid payment frequency → 422
Custom days without CUSTOM_DAYS → 422

Performance Considerations

Cache plan data at product level (TTL: 30 minutes)
Invalidate cache on plan create/update/delete
Batch operations when managing multiple plans
Use pagination for products with many plans
Index on productId for fast retrieval

Security Considerations

Always validate shop ownership
Verify product belongs to shop
Rate limiting: 100 requests/hour per user
Input validation on all parameters
SQL injection prevention (parameterized queries)
XSS prevention (sanitize all inputs)
Audit log all plan changes

Monitoring and Analytics

Track the following metrics:

Plans created per shop
Plan activation/deactivation frequency
Featured plan changes
Plans by payment frequency
Average APR across plans
Popular plan configurations
Plans with most agreements

Best Practices for Shop Owners

Plan Design Strategy

Offer 2-3 plans for different budgets
- Quick plan: Short term, low interest
- Standard plan: Medium term, moderate interest
- Budget plan: Long term, higher interest
Use clear naming: "8-Week Quick Pay", "12-Month Standard"
Set appropriate featured plan: Balance of affordability and profit
Adjust based on data: Monitor which plans customers choose

APR Configuration

Premium products: Lower APR (8-12%)
Standard products: Moderate APR (12-18%)
High-risk categories: Higher APR (18-24%)
Promotional periods: Reduced APR (0-10%)

Down Payment Strategy

High-value items: Higher down payment (25-40%)
Impulse purchases: Lower down payment (10-20%)
Luxury items: Flexible range (15-50%)
Clearance items: Fixed minimum (10-15%)

Grace Period Guidelines

Weekly payments: 7-14 days grace
Monthly payments: 30-45 days grace
Seasonal products: Align with customer cash flow
New customers: Shorter grace (7-15 days)

Common Mistakes to Avoid

Too many plans (confuses customers) - stick to 2-4
Too high APR (customers avoid) - keep competitive
Too low down payment (higher default risk) - minimum 15-20%
Deleting active plans - deactivate instead
Not setting featured plan - customers want guidance
Inconsistent plan naming - use clear conventions
Not updating based on performance - review quarterly
Enabling without active plans - create plans first

Support & Resources

API Documentation: https://docs.nextgate.com/api/installment-plans
Shop Owner Guide: https://help.nextgate.com/shop/installments
Developer Portal: https://developers.nextgate.com
Support Email: shop-support@nextgate.com
Status Page: https://status.nextgate.com
Video Tutorials: https://academy.nextgate.com/installments

Version 1.0 (2025-10-18)

Initial release
Full CRUD operations for installment plans
Plan activation/deactivation
Featured plan management
Product-level installment control
Shop ownership validation
Comprehensive error handling
Audit logging support for authentication | | Content-Type | string | Yes | application/json |

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Valid UUID format, must be owned by authenticated user
productId	UUID	Yes	Unique identifier of the product	Valid UUID format, must belong to specified shop

Request JSON Sample:

{
  "planName": "12 Month Standard Plan",
  "paymentFrequency": "MONTHLY",
  "customFrequencyDays": null,
  "numberOfPayments": 12,
  "apr": 15.00,
  "minDownPaymentPercent": 20,
  "gracePeriodDays": 30,
  "fulfillmentTiming": "IMMEDIATE",
  "isActive": true,
  "isFeatured": false,
  "displayOrder": 1
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
planName	string	Yes	Display name for the plan	Min: 3, Max: 100 characters
paymentFrequency	string	Yes	Payment frequency type	enum: DAILY, WEEKLY, BI_WEEKLY, SEMI_MONTHLY, MONTHLY, QUARTERLY, CUSTOM_DAYS
customFrequencyDays	integer	Conditional	Custom frequency in days	Required if paymentFrequency is CUSTOM_DAYS, Min: 1, Max: 365
numberOfPayments	integer	Yes	Total number of payments	Min: 2, Max: 120
apr	decimal	Yes	Annual Percentage Rate	Min: 0.00, Max: 36.00
minDownPaymentPercent	integer	Yes	Minimum down payment percentage	Min: 10, Max: 50
gracePeriodDays	integer	Yes	Days before first payment due	Min: 0, Max: 60
fulfillmentTiming	string	Yes	When to ship product	enum: IMMEDIATE, AFTER_PAYMENT
isActive	boolean	No	Whether plan is active	Default: true
isFeatured	boolean	No	Whether plan is featured	Default: false
displayOrder	integer	No	Display order on product page	Min: 0, Default: 0

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Installment plan created successfully",
  "action_time": "2025-10-18T10:30:45",
  "data": {
    "planId": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
    "planName": "12 Month Standard Plan",
    "paymentFrequency": "MONTHLY",
    "paymentFrequencyDisplay": "Monthly",
    "customFrequencyDays": null,
    "numberOfPayments": 12,
    "calculatedDurationDays": 360,
    "calculatedDurationDisplay": "12 months",
    "apr": 15.00,
    "minDownPaymentPercent": 20,
    "gracePeriodDays": 30,
    "fulfillmentTiming": "IMMEDIATE",
    "isActive": true,
    "isFeatured": false,
    "displayOrder": 1,
    "productId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "productName": "Samsung Galaxy S24 Ultra",
    "shopId": "8d3a7b12-9c4e-4f8a-b5d2-3e6f7a8b9c0d",
    "shopName": "Tech World Store",
    "createdAt": "2025-10-18T10:30:45",
    "updatedAt": "2025-10-18T10:30:45"
  }
}

Success Response Fields:

Field	Description
planId	Unique identifier for the created plan
planName	Name of the plan
paymentFrequency	Payment frequency enum value
paymentFrequencyDisplay	Human-readable frequency
customFrequencyDays	Custom days (if CUSTOM_DAYS type)
numberOfPayments	Total number of payments
calculatedDurationDays	Auto-calculated total duration in days
calculatedDurationDisplay	Human-readable duration
apr	Annual Percentage Rate
minDownPaymentPercent	Minimum down payment percentage
gracePeriodDays	Grace period in days
fulfillmentTiming	Fulfillment option
isActive	Active status
isFeatured	Featured status
displayOrder	Display order
productId	Associated product ID
productName	Associated product name
shopId	Associated shop ID
shopName	Associated shop name
createdAt	Creation timestamp
updatedAt	Last update timestamp

Error Response Examples:

Bad Request - Invalid APR (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "APR must be between 0% and 36%",
  "action_time": "2025-10-18T10:30:45",
  "data": "APR must be between 0% and 36%"
}

Bad Request - Invalid Payment Count (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Number of payments must be between 2 and 120",
  "action_time": "2025-10-18T10:30:45",
  "data": "Number of payments must be between 2 and 120"
}

Validation Error (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-10-18T10:30:45",
  "data": {
    "planName": "Plan name is required",
    "apr": "must be between 0 and 36",
    "minDownPaymentPercent": "must be between 10 and 50"
  }
}

Forbidden - Not Shop Owner (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "You do not have permission to manage this shop's products",
  "action_time": "2025-10-18T10:30:45",
  "data": "You do not have permission to manage this shop's products"
}

Not Found - Product (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Product not found",
  "action_time": "2025-10-18T10:30:45",
  "data": "Product not found"
}

Shop Categories Management

Shop Management

Shop Rating

Shop Review

Product Management

Cart Management

Wishlist Management

Wallet

Transaction History

Installment Purchase - Customer Endpoints

Installment Purchase - Public & Plan Endpoints

Installment Plan Management - Admin/Shop Endpoints

Installment Plan Management - Admin/Shop Endpoints

Standard Response Format

Success Response Structure

Error Response Structure

Standard Response Fields

HTTP Method Badge Standards

Endpoints

1. Create Installment Plan

2. Get Product Installment Plans

3. Get Installment Plan By ID

4. Update Installment Plan

5. Delete Installment Plan

6. Activate Installment Plan

7. Deactivate Installment Plan

8. Set Featured Plan

9. Enable Installments for Product

10. Disable Installments for Product

Common HTTP Status Codes

Payment Frequency Options

Fulfillment Timing Options

Plan Configuration Constraints

Plan States and Lifecycle

Active Plan

Inactive Plan

Featured Plan

Deleted Plan

Business Rules Summary

Common Workflows

Creating a New Installment Plan

Managing Multiple Plans

Temporarily Disabling Plans

Updating Plan Terms

Deleting Unused Plans

Client-Side Validation

Server-Side Error Handling

Testing Scenarios

Happy Path

Edge Cases

Error Cases

Performance Considerations

Security Considerations

Monitoring and Analytics

Best Practices for Shop Owners

Plan Design Strategy

APR Configuration

Down Payment Strategy

Grace Period Guidelines

Common Mistakes to Avoid

Support & Resources

Version 1.0 (2025-10-18)