Update Subscription

Updates an existing subscription. All fields are optional; only provided fields will be updated.

Business Rules

• Subscription must exist and be active (not cancelled).

• planIdentifier must reference an existing, active plan.

• planPrice must match the plan's configured amount.

• endDate or endDateTime must be after startDate if provided.

• If endDate/endDateTime is set, subscription will end on that date.

• If endDate/endDateTime is null, subscription continues indefinitely.

• Changes take effect in the next billing cycle.

Update a subscription

PUT /payments/subscriptions/{SubscriptionIdentifier}

Resource URL:

Test

https://api.sandbox.irembopay.com/subscriptions/{subscription_identifier}

Production

Headers

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

Request path parameters

Name	Type	Mandatory?	Comment
subscriptionIdentifier	string	Yes	Subscription identifier (e.g., SU-ABC12345).

Request body

Data representation: JSON

Field	Type	Mandatory	Comment (Description)
planIdentifier	string	Yes	Plan identifier (e.g., PL-2A1YFJVI).
planPrice	string	Yes	Plan price with currency (e.g., "30,000.00 RWF").
occurrence	number	No	Number of billing cycles (occurrences) for the subscription.
endDate	datetime	No	Subscription end date (can be null for indefinite).
endDateTime	datetime	No	Subscription end datetime (can be null for indefinite).

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.
nextDueDate	datetime	Yes	Next invoice due date (recalculated if frequency changed).
subscriptionLinkUrl	string	Yes	Link to subscription checkout/manage page.
remindAfter	number	Yes	Reminder days setting.
createdAt	datetime	Yes	Creation timestamp.
updatedAt	datetime	Yes	Last update timestamp.
subscriptionItems	array	Yes	Updated items attached to the subscription.

---

Error codes

HTTP Status	Code/Key	Comment (Description)
400	VALIDATION_ERROR	Missing/invalid fields, invalid planIdentifier or planPrice format.
400	BAD_DATA	Bad data provided (plan not found, invalid dates, plan price mismatch).
401	UNAUTHORIZED	Missing or invalid authentication token.
403	FORBIDDEN	Insufficient permissions
404	NOT_FOUND	Subscription not found, plan not found, or subscription already cancelled.
409	DUPLICATE_RESOURCE	Conflicting unique fields.
500	INTERNAL_SERVER_ERROR	Unexpected server error.

---

Open API Sample

Update subscription (v2)

put

Updates an existing subscription. All fields are optional; only provided fields will be updated. Changes take effect in the next billing cycle.

Authorizations

apiKeyAuth

X-IREMBOPAY-AUTHORIZATIONstringRequired

Path parameters

identifierstringRequired

Subscription identifier (e.g., SU-ABC12345)

Header parameters

X-API-VersionstringRequired

API version number (e.g., 2)

Default: 2

Body

application/json

planIdentifierstringRequired

Plan identifier (e.g., PL-2A1YFJVI)

Example: PL-2A1YFJVI

planPricestringRequired

Plan price with currency (e.g., "30,000.00 RWF")

Example: 30,000.00 RWF

occurrenceinteger · nullableOptional

Number of billing cycles (occurrences) for the subscription

endDatestring · date · nullableOptional

Subscription end date (can be null for indefinite). Either endDate or endDateTime can be provided, but not both.

Example: 2024-12-31

endDateTimestring · date-time · nullableOptional

Subscription end datetime (can be null for indefinite). Either endDate or endDateTime can be provided, but not both.

Example: 2024-12-31T23:59:59

Responses

200

Subscription updated successfully

application/json

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

409

Conflict

application/json

500

Internal server error

application/json

put

/subscriptions/{identifier}

JSONJavaJavaScriptPython

{
  "planIdentifier": "PL-2A1YFJVI",
  "planPrice": "30,000.00 RWF",
  "occurrence": null,
  "endDate": null,
  "endDateTime": null
}

{
  "message": "Subscription updated successfully",
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "identifier": "SU-ABC12345",
    "merchantAccountId": "660e8400-e29b-41d4-a716-446655440000",
    "customerId": "4380539a-a689-4552-a982-119f1dff1ce3",
    "customerName": "John Doe",
    "customerEmail": "[e-mail]",
    "customerPhoneNumber": "0781234567",
    "notificationPreference": "EMAIL",
    "startDate": "2024-09-01T00:00:00Z",
    "endDate": "2024-12-31T23:59:59Z",
    "frequency": "QUARTERLY",
    "amount": 30000,
    "currency": "RWF",
    "status": "ACTIVE",
    "paymentStatus": "SCHEDULED",
    "nextDueDate": "2024-12-01T00:00:00Z",
    "subscriptionLinkUrl": "https://checkout.dev.irembopay.com/subscriptions/SU-ABC12345",
    "remindAfter": 5,
    "createdAt": "2024-09-01T10:30:00Z",
    "updatedAt": "2024-09-15T10:30:00Z",
    "subscriptionItems": []
  }
}