Create Subscription

Key details of the API

1. Resource URL

Test

https://api.sandbox.irembopay.com/subscritpions

Production

1. Method: POST

2. Headers

irembopay-secretKey: secreKey
X-API-Version: 2

Create a subscription api reference

POST /subscriptions

Headers

Name	Value
Content-Type	application/json
irembopay-secretKey	secretKey
X-API-Version	2

Body

Data representation: JSON

Field	Type	Mandatory	Comment (Description)
paymentAccountIdentifier	string	Yes	Payment account where funds will be deposited.
customerId	uuid	Yes	Existing customer UUID.
customerEmail	string	No	Customer email (required if notificationPreference includes EMAIL).
customerPhoneNumber	string	No	Customer phone (required if notificationPreference includes SMS).
startDate	datetime	Yes	Subscription start datetime (ISO 8601).
endDate	datetime	No	Subscription end datetime (optional).
frequency	enum	Yes	Billing frequency: WEEKLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY.
amount	number	Yes	Total amount (must equal sum of items).
remindAfter	number	Yes	Days after failed invoice to send reminder (must obey frequency rule).
notificationPreference	enum	Yes	ALL, EMAIL, or SMS.
items	array	Yes	List of subscription items.
items[].productCode	string	Yes	Product code; must exist and belong to the merchant.
items[].unitPrice	number	Yes	Unit price (>= 1).
items[].quantity	number	Yes	Quantity (>= 1).
items[].discountType	enum	No	FLAT or PERCENTAGE.
items[].discountValue	number	No	Discount value (required if discountType provided).

---

Response body payload

For this endpoint, the "data" payload in the response will have the fields below:

Field	Type	Mandatory	Comment (Description)
id	uuid	Yes	Subscription identifier (UUID).
identifier	string	Yes	Human-friendly subscription code (SU-...).
merchantAccountId	uuid	Yes	Merchant account UUID.
customerId	uuid	Yes	Customer UUID.
customerName	string	Yes	Customer full name.
customerEmail	string	No	Customer email.
customerPhoneNumber	string	No	Customer phone.
notificationPreference	enum	Yes	ALL, EMAIL, SMS.
startDate	datetime	Yes	Start datetime.
endDate	datetime	No	End datetime.
frequency	enum	Yes	Billing frequency.
amount	number	Yes	Subscription amount.
currency	enum	Yes	Currency code.
status	enum	Yes	Subscription status.
paymentStatus	enum	Yes	Payment status (e.g., SCHEDULED).
nextDueDate	datetime	Yes	Next invoice due date.
subscriptionLinkUrl	string	Yes	Link to the subscription checkout/manage page.
remindAfter	number	Yes	Reminder days setting.
createdAt	datetime	Yes	Creation timestamp.
updatedAt	datetime	Yes	Last update timestamp.
origin	enum	Yes	Origin (API or PORTAL).
createdBy	uuid	Yes	Creator user/account ID.
subscriptionItems	array	Yes	Items attached to the subscription.

---

Error codes

HTTP Status	Code/Key	Comment (Description)
400	VALIDATION_ERROR	Missing/invalid fields (items, frequency, amount mismatch, remindAfter rule).
400	BAD_DATA	Business rule violation (product currency/merchant mismatch, invalid contact).
401	UNAUTHORIZED	Missing or invalid authentication token.
403	FORBIDDEN	Insufficient permissions (requires SUBSCRIPTION_WRITE).
404	NOT_FOUND	Related resource not found (e.g., customer or product not found).
409	DUPLICATE_RESOURCE	Duplicate subscription identifier or conflicting unique fields.
500	INTERNAL_SERVER_ERROR	Unexpected server error.

---

Open API Sample

Create subscription (v2)

post

Creates a new subscription with the specified details on API version 2.

Authorizations

apiKeyAuth

X-IREMBOPAY-AUTHORIZATIONstringRequired

Header parameters

X-API-VersionstringRequired

API version number (e.g., 2)

Default: 2

Body

application/json

paymentAccountIdentifierstringRequired

Identifier of the Payment Account where the money will be Deposited

Example: 1234567890

customerIdstring · uuidOptional

Customer UUID

Example: 4380539a-a689-4552-a982-119f1dff1ce3

customerEmailstring · emailOptional

Customer email

Example: [e-mail]

customerPhoneNumberstringOptional

A valid Phone Number of the Customer

Example: 0781234567

startDatestring · date-timeRequired

Subscription start date

Example: 2024-09-01T10:00:00.000+02

endDatestring · date-timeOptional

Subscription end date (optional)

Example: 2024-12-31T23:59:59.000+02

frequencystring · enumRequired

Billing frequency

Example: MONTHLYPossible values:

amountnumber · min: 1Required

Total subscription amount

Example: 10000

remindAfterinteger · min: 1Required

Number of days after failed invoice to send a reminder

Example: 2

notificationPreferencestring · enumRequired

Preference of notifications to be sent

Example: ALLPossible values:

Responses

201

Subscription created successfully

application/json

400

Bad request

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

post

/subscriptions

JSONJavaJavaScriptPython

{
  "paymentAccountIdentifier": "1234567890",
  "customerId": "4380539a-a689-4552-a982-119f1dff1ce3",
  "customerEmail": "[e-mail]",
  "customerPhoneNumber": "0781234567",
  "startDate": "2024-09-01T10:00:00.000+02",
  "endDate": "2024-12-31T23:59:59.000+02",
  "frequency": "MONTHLY",
  "amount": 10000,
  "remindAfter": 2,
  "notificationPreference": "ALL",
  "items": [
    {
      "productCode": "IR2.PLC",
      "unitPrice": 2000,
      "quantity": 3,
      "discountType": "FLAT",
      "discountValue": 10.00
    }
  ]
}

{
  "message": "Subscription created successfully",
  "success": true,
  "data": {
    "id": "9a946f53-3fef-4a53-8fb6-3ada27c38796",
    "identifier": "SU-25128SP1",
    "merchantAccountId": "7d5636a5-9cec-4145-97fb-920d01e1c5ac",
    "customerId": "4380539a-a689-4552-a982-119f1dff1ce3",
    "customerName": "John Doe",
    "customerEmail": "[e-mail]",
    "customerPhoneNumber": "0781234567",
    "notificationPreference": "ALL",
    "startDate": "2024-09-01T10:00:00.000+02",
    "endDate": "2024-12-31T23:59:59.000+02",
    "status": "PENDING",
    "frequency": "MONTHLY",
    "amount": 10000,
    "currency": "RWF",
    "paymentStatus": "NEW",
    "nextDueDate": "2024-10-01T10:00:00.000+02",
    "remindAfter": 2,
    "createdAt": "2024-09-01T10:00:00.000+02",
    "updatedAt": "2024-09-01T10:00:00.000+02",
    "subscriptionItems": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "productId": "660e8400-e29b-41d4-a716-446655440000",
        "unitPrice": 2000,
        "quantity": 3,
        "totalPrice": 6000,
        "discountType": "FLAT",
        "discountValue": 10
      }
    ]
  }
}