REIS API Documentation

Complete integration guide for Bills and Subscriptions

Version 1.0.0

API Overview

Welcome to our API documentation. This API allows you to integrate your system with our billing and subscription management platform.

Base URL: All API requests should be made to: https://yourdomain.com/{username}/

Available Endpoints

Method Endpoint Description
POST /v1/add/bill Create a new bill
POST /v1/add/subscription Create a new subscription

Key Features

  • Simple API key authentication
  • JSON request and response format
  • Support for 3 subscription types
  • Automatic invoice generation
  • Rate limiting for security

Authentication

All API requests require authentication using an API key sent in the request header.

Header Format

Request Header 
X-API-Key: your-api-key-here
Security Note: Keep your API key secure. Never expose it in client-side code or commit it to version control.

Rate Limits

Endpoint Rate Limit
/v1/add/bill 100 requests/hour
/v1/add/subscription 50 requests/hour

Create Bill

POST {route_path}/v1/add/bill

Create a new bill for a customer. This endpoint allows you to generate bills that can be paid through the system.

Request Parameters

Parameter Type Required Description Example
customerName string Required Customer's full name "Razzbery Solutions"
customerPhone string Required Phone (07xxxxxxxx) "0777839071"
customerEmail string Optional Customer's email "test@razzbery.com"
customerNationalId string Optional National ID (10 digits) "9876543210"
customerAddress string Optional Customer's address "Amman, Jordan"
serviceType string Required Type of service "Water Bill"
dueAmount number Required Amount in JOD (> 0) 150.50
dueDate string Required Date (YYYY-MM-DD) "2025-12-31"
description string Optional Additional details "Monthly bill"
notes string Optional Internal notes "Priority customer"

Request Example

Request Body 
{
    "customerName": "Razzbery Solutions",
    "customerPhone": "0777839071",
    "customerEmail": "info@razzbery.com",
    "customerNationalId": "9876543210",
    "customerAddress": "123 Main St, Amman, Jordan",
    "serviceType": "Water Bill",
    "dueAmount": 150.50,
    "dueDate": "2025-12-31",
    "description": "Monthly water consumption bill",
    "notes": "Customer prefers email notifications"
}

Success Response (200 OK)

Response Body 
{
  "success": true,
  "message": "Bill created successfully",
  "data": {
    "_id": "674a1b2c3d4e5f6a7b8c9d0e",
    "billingNo": "BILL-20251201-0001",
    "billNo": "BN-20251201-0001",
    "customerName": "Razzbery Solutions",
    "customerPhone": "0777839071",
    "customerEmail": "info@razzbery.com",
    "serviceType": "Water Bill",
    "dueAmount": 150.50,
    "dueDate": "2025-12-31T00:00:00.000Z",
    "status": "PENDING",
    "createdAt": "2025-12-01T10:30:00.000Z"
  }
}
Success! The bill has been created and is ready for payment. The customer will receive notifications based on their contact information.

Create Subscription

POST {route_path}/v1/add/subscription

Create a new subscription with support for 3 types: Fixed Monthly, Custom Schedule, or Open-Ended.

Subscription Types

FIXED_MONTHLY

Fixed amount paid monthly until completed (e.g., phone installment)

CUSTOM_SCHEDULE

Custom payment dates and amounts (e.g., quarterly payments)

OPEN_ENDED

Recurring monthly until cancelled (e.g., gym membership)

Common Parameters (All Types)

Parameter Type Required Description
subscriptionType string Required FIXED_MONTHLY, CUSTOM_SCHEDULE, or OPEN_ENDED
customerName string Required Customer's full name
customerPhone string Required Phone (07xxxxxxxx)
productName string Required Product or service name
customerEmail string Optional Customer's email
autoGenerateInvoices boolean Optional Auto-create invoices (default: true)

Type-Specific Parameters

FIXED_MONTHLY

Parameter Type Required Description Example
totalAmount number Required Total amount (JOD) 1200
monthlyPayment number Required Monthly installment 100
paymentDay number Required Day of month (1-28) 5

CUSTOM_SCHEDULE

Parameter Type Required Description
totalAmount number Required Total amount (JOD)
customInstallments array Required Array of payment objects (see below)
customInstallments Array Format: 
[
  {
    "dueDate": "2025-12-10",
    "amount": 300,
    "description": "First payment"
  }
]

OPEN_ENDED

Parameter Type Required Description Example
recurringAmount number Required Monthly recurring amount 25
paymentDay number Required Day of month (1-28) 1

Request Examples

Example 1: Fixed Monthly Subscription

Request Body 
{
  "subscriptionType": "FIXED_MONTHLY",
  "customerName": "Razzbery Solutions",
  "customerPhone": "0777839071",
  "customerEmail": "info@razzbery.com",
  "productName": "iPhone 15 Pro Max",
  "totalAmount": 1200,
  "monthlyPayment": 100,
  "paymentDay": 5,
  "autoGenerateInvoices": true,
  "description": "iPhone 15 Pro Max 256GB Black"
}

Example 2: Custom Schedule Subscription

Request Body 
{
  "subscriptionType": "CUSTOM_SCHEDULE",
  "customerName": "Ahmad Ali",
  "customerPhone": "0791234567",
  "customerEmail": "ahmad@razzbery.com",
  "productName": "Laptop Dell XPS 15",
  "totalAmount": 900,
  "customInstallments": [
    {
      "dueDate": "2025-12-10",
      "amount": 300,
      "description": "First payment"
    },
    {
      "dueDate": "2026-03-10",
      "amount": 300,
      "description": "Second payment"
    },
    {
      "dueDate": "2026-06-10",
      "amount": 300,
      "description": "Final payment"
    }
  ],
  "autoGenerateInvoices": true
}

Example 3: Open-Ended Subscription

Request Body 
{
  "subscriptionType": "OPEN_ENDED",
  "customerName": "Razzbery Solutions",
  "customerPhone": "0777839071",
  "customerEmail": "info@razzbery.com",
  "productName": "Gym Membership - Premium",
  "recurringAmount": 25,
  "paymentDay": 1,
  "autoGenerateInvoices": true,
  "description": "Premium gym membership"
}

Success Response (200 OK)

Response Body 
{
  "success": true,
  "message": "Subscription created successfully",
  "data": {
    "_id": "674a1b2c3d4e5f6a7b8c9d0e",
    "subscriptionNo": "SUB-20251201-0001",
    "subscriptionType": "FIXED_MONTHLY",
    "customerName": "Razzbery Solutions",
    "customerPhone": "0777839071",
    "productName": "iPhone 15 Pro Max",
    "totalAmount": 1200,
    "monthlyPayment": 100,
    "recurringAmount": null,
    "numberOfInstallments": 12,
    "status": "ACTIVE",
    "createdAt": "2025-12-01T10:30:00.000Z"
  }
}

Error Codes

All error responses follow the same format and include a descriptive error code and message.

Error Response Format

Error Structure 
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message"
  }
}

Common Error Codes

401 - Authentication Errors

NO_API_KEY

API key is missing from the request headers.

Response Example 
{
  "success": false,
  "error": {
    "code": "NO_API_KEY",
    "message": "API key is required. Please provide X-API-Key header."
  }
}
INVALID_API_KEY

The provided API key is invalid or expired.

Response Example 
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key provided."
  }
}

400 - Validation Errors

VALIDATION_ERROR

Required fields are missing from the request.

Response Example 
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required fields",
    "required": [
      "customerName",
      "customerPhone",
      "serviceType",
      "dueAmount",
      "dueDate"
    ]
  }
}
INVALID_PHONE

Phone number doesn't match the required format.

Response Example 
{
  "success": false,
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must match pattern: 07xxxxxxxx"
  }
}
INVALID_AMOUNT

Amount must be greater than zero.

Response Example 
{
  "success": false,
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Due amount must be greater than 0"
  }
}
INVALID_TYPE

Subscription type is not valid.

Response Example 
{
  "success": false,
  "error": {
    "code": "INVALID_TYPE",
    "message": "Invalid subscription type",
    "validTypes": [
      "FIXED_MONTHLY",
      "CUSTOM_SCHEDULE",
      "OPEN_ENDED"
    ]
  }
}

500 - Server Errors

SERVER_ERROR

An unexpected error occurred on the server.

Response Example 
{
  "success": false,
  "error": {
    "code": "SERVER_ERROR",
    "message": "An error occurred while creating the bill",
    "details": "Database connection timeout"
  }
}

HTTP Status Codes

Status Code Meaning Description
200 OK Request succeeded
400 Bad Request Invalid request data
401 Unauthorized Authentication failed
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server encountered an error

Need Help?

support@razzbery.com Full Documentation Website

© 2025 Razzbery Solutions. All rights reserved. | REIS API Version 1.0.0