subbySave to Buy
Instalment purchase plans for eligible e-commerce merchants and their buyers.
https://sandbox-api.mysubbyapp.com/v1
GET
/provider-savingsList Save to Buy plans
Lists buyer plans for the authenticated e-commerce merchant. Returns 404 when Save to Buy is unavailable for the account.
Not metered
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/provider-savings' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
statusquery · string familyIdquery · string pagequery · integer limitquery · integer Responses
200 A page of Save to Buy plans.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "SB-7F3K9Q"
},
"object": {
"const": "savings_plan"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"overdue",
"completed",
"shipped",
"delivered",
"cancelled"
]
},
"productName": {
"type": "string"
},
"productImage": {
"type": [
"string",
"null"
],
"format": "uri"
},
"mode": {
"type": "string",
"enum": [
"fixed",
"flexible"
]
},
"frequency": {
"type": [
"string",
"null"
],
"enum": [
"daily",
"weekly",
"biweekly",
"monthly",
null
]
},
"currency": {
"const": "NGN"
},
"targetAmount": {
"type": "integer",
"description": "Whole naira."
},
"amountPaid": {
"type": "integer",
"description": "Whole naira."
},
"outstanding": {
"type": "integer",
"description": "Whole naira."
},
"instalmentAmount": {
"type": [
"integer",
"null"
],
"description": "Whole naira."
},
"instalmentCount": {
"type": [
"integer",
"null"
]
},
"instalmentsPaid": {
"type": "integer"
},
"nextDue": {
"type": [
"object",
"null"
],
"properties": {
"index": {
"type": "integer"
},
"dueAt": {
"type": "string",
"format": "date-time"
},
"amount": {
"type": "integer",
"description": "Whole naira."
}
}
},
"deadline": {
"type": "string",
"format": "date-time"
},
"instalments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 1
},
"dueAt": {
"type": "string",
"format": "date-time"
},
"amount": {
"type": "integer",
"minimum": 200,
"description": "Whole naira."
},
"status": {
"type": "string",
"enum": [
"scheduled",
"paid",
"paid_early",
"missed"
]
},
"paidAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
},
"pendingFee": {
"type": "integer",
"description": "Whole naira."
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"shippedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"deliveredAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"refundWindowEndsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
},
"total": {
"type": "integer"
},
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
}
}
}
}
}
}
}404 Object or route not found in this environment.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}GET
/provider-savings/summaryRetrieve Save to Buy dashboard metrics
Not metered
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/provider-savings/summary' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
periodquery · string Responses
200 Save to Buy dashboard metrics.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"additionalProperties": true,
"description": "Dashboard metrics including series, outstanding balances, fulfilment queues, completion rate and product performance."
}
}
}
}
}404 Object or route not found in this environment.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}GET
/provider-savings/productsList Save to Buy products
Not metered
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/provider-savings/products' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Responses
200 Save to Buy products and sales metrics.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price": {
"type": "integer",
"description": "Whole naira."
},
"isActive": {
"type": "boolean"
},
"image": {
"type": [
"string",
"null"
],
"format": "uri"
},
"cycleMonths": {
"type": "integer"
},
"mode": {
"type": "string",
"enum": [
"fixed",
"flexible"
]
},
"allowedFrequencies": {
"type": "array",
"items": {
"type": "string",
"enum": [
"daily",
"weekly",
"biweekly",
"monthly"
]
}
},
"slots": {
"type": "object",
"properties": {
"total": {
"type": [
"integer",
"null"
]
},
"used": {
"type": "integer"
},
"remaining": {
"type": [
"integer",
"null"
]
}
}
},
"views": {
"type": "integer"
},
"saving": {
"type": "integer"
},
"overdue": {
"type": "integer"
},
"readyToDeliver": {
"type": "integer"
},
"delivered": {
"type": "integer"
},
"collected": {
"type": "integer",
"description": "Whole naira."
}
}
}
}
}
}
}
}404 Object or route not found in this environment.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}GET
/provider-savings/{id}Retrieve a Save to Buy plan
Not metered
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/provider-savings/{id}' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
idpath · string · requiredResponses
200 The buyer's Save to Buy plan.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "SB-7F3K9Q"
},
"object": {
"const": "savings_plan"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"overdue",
"completed",
"shipped",
"delivered",
"cancelled"
]
},
"productName": {
"type": "string"
},
"productImage": {
"type": [
"string",
"null"
],
"format": "uri"
},
"mode": {
"type": "string",
"enum": [
"fixed",
"flexible"
]
},
"frequency": {
"type": [
"string",
"null"
],
"enum": [
"daily",
"weekly",
"biweekly",
"monthly",
null
]
},
"currency": {
"const": "NGN"
},
"targetAmount": {
"type": "integer",
"description": "Whole naira."
},
"amountPaid": {
"type": "integer",
"description": "Whole naira."
},
"outstanding": {
"type": "integer",
"description": "Whole naira."
},
"instalmentAmount": {
"type": [
"integer",
"null"
],
"description": "Whole naira."
},
"instalmentCount": {
"type": [
"integer",
"null"
]
},
"instalmentsPaid": {
"type": "integer"
},
"nextDue": {
"type": [
"object",
"null"
],
"properties": {
"index": {
"type": "integer"
},
"dueAt": {
"type": "string",
"format": "date-time"
},
"amount": {
"type": "integer",
"description": "Whole naira."
}
}
},
"deadline": {
"type": "string",
"format": "date-time"
},
"instalments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 1
},
"dueAt": {
"type": "string",
"format": "date-time"
},
"amount": {
"type": "integer",
"minimum": 200,
"description": "Whole naira."
},
"status": {
"type": "string",
"enum": [
"scheduled",
"paid",
"paid_early",
"missed"
]
},
"paidAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
},
"pendingFee": {
"type": "integer",
"description": "Whole naira."
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"shippedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"deliveredAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"refundWindowEndsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
}
}
}
}404 Object or route not found in this environment.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}POST
/provider-savings/{id}/extendExtend a Save to Buy plan
Moves unpaid instalments and the deadline. Only active or overdue plans can be extended.
Metered on successful live writes
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/provider-savings/{id}/extend' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Add a JSON body matching the request schema below and a Content-Type: application/json header.
Parameters
idpath · string · requiredRequest body schema
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"days"
],
"properties": {
"days": {
"type": "integer",
"minimum": 1,
"maximum": 60
}
}
}
}
}
}Responses
200 Extended plan and the buyer's extension fee.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "SB-7F3K9Q"
},
"object": {
"const": "savings_plan"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"overdue",
"completed",
"shipped",
"delivered",
"cancelled"
]
},
"productName": {
"type": "string"
},
"productImage": {
"type": [
"string",
"null"
],
"format": "uri"
},
"mode": {
"type": "string",
"enum": [
"fixed",
"flexible"
]
},
"frequency": {
"type": [
"string",
"null"
],
"enum": [
"daily",
"weekly",
"biweekly",
"monthly",
null
]
},
"currency": {
"const": "NGN"
},
"targetAmount": {
"type": "integer",
"description": "Whole naira."
},
"amountPaid": {
"type": "integer",
"description": "Whole naira."
},
"outstanding": {
"type": "integer",
"description": "Whole naira."
},
"instalmentAmount": {
"type": [
"integer",
"null"
],
"description": "Whole naira."
},
"instalmentCount": {
"type": [
"integer",
"null"
]
},
"instalmentsPaid": {
"type": "integer"
},
"nextDue": {
"type": [
"object",
"null"
],
"properties": {
"index": {
"type": "integer"
},
"dueAt": {
"type": "string",
"format": "date-time"
},
"amount": {
"type": "integer",
"description": "Whole naira."
}
}
},
"deadline": {
"type": "string",
"format": "date-time"
},
"instalments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 1
},
"dueAt": {
"type": "string",
"format": "date-time"
},
"amount": {
"type": "integer",
"minimum": 200,
"description": "Whole naira."
},
"status": {
"type": "string",
"enum": [
"scheduled",
"paid",
"paid_early",
"missed"
]
},
"paidAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
},
"pendingFee": {
"type": "integer",
"description": "Whole naira."
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"shippedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"deliveredAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"refundWindowEndsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
}
}
}
}404 Object or route not found in this environment.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}422 Valid request that conflicts with the object's state.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}POST
/provider-savings/{id}/shipMark a paid product shipped
Metered on successful live writes
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/provider-savings/{id}/ship' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Add a JSON body matching the request schema below and a Content-Type: application/json header.
Parameters
idpath · string · requiredRequest body schema
{
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"note": {
"type": "string",
"maxLength": 250
}
}
}
}
}
}Responses
200 The updated plan.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "SB-7F3K9Q"
},
"object": {
"const": "savings_plan"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"overdue",
"completed",
"shipped",
"delivered",
"cancelled"
]
},
"productName": {
"type": "string"
},
"productImage": {
"type": [
"string",
"null"
],
"format": "uri"
},
"mode": {
"type": "string",
"enum": [
"fixed",
"flexible"
]
},
"frequency": {
"type": [
"string",
"null"
],
"enum": [
"daily",
"weekly",
"biweekly",
"monthly",
null
]
},
"currency": {
"const": "NGN"
},
"targetAmount": {
"type": "integer",
"description": "Whole naira."
},
"amountPaid": {
"type": "integer",
"description": "Whole naira."
},
"outstanding": {
"type": "integer",
"description": "Whole naira."
},
"instalmentAmount": {
"type": [
"integer",
"null"
],
"description": "Whole naira."
},
"instalmentCount": {
"type": [
"integer",
"null"
]
},
"instalmentsPaid": {
"type": "integer"
},
"nextDue": {
"type": [
"object",
"null"
],
"properties": {
"index": {
"type": "integer"
},
"dueAt": {
"type": "string",
"format": "date-time"
},
"amount": {
"type": "integer",
"description": "Whole naira."
}
}
},
"deadline": {
"type": "string",
"format": "date-time"
},
"instalments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 1
},
"dueAt": {
"type": "string",
"format": "date-time"
},
"amount": {
"type": "integer",
"minimum": 200,
"description": "Whole naira."
},
"status": {
"type": "string",
"enum": [
"scheduled",
"paid",
"paid_early",
"missed"
]
},
"paidAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
},
"pendingFee": {
"type": "integer",
"description": "Whole naira."
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"shippedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"deliveredAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"refundWindowEndsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
}
}
}
}422 Valid request that conflicts with the object's state.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}POST
/provider-savings/{id}/deliverMark a paid product delivered
Metered on successful live writes
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/provider-savings/{id}/deliver' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Add a JSON body matching the request schema below and a Content-Type: application/json header.
Parameters
idpath · string · requiredRequest body schema
{
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"note": {
"type": "string",
"maxLength": 250
}
}
}
}
}
}Responses
200 The delivered plan. Sends savings_plan.fulfilled.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "SB-7F3K9Q"
},
"object": {
"const": "savings_plan"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"overdue",
"completed",
"shipped",
"delivered",
"cancelled"
]
},
"productName": {
"type": "string"
},
"productImage": {
"type": [
"string",
"null"
],
"format": "uri"
},
"mode": {
"type": "string",
"enum": [
"fixed",
"flexible"
]
},
"frequency": {
"type": [
"string",
"null"
],
"enum": [
"daily",
"weekly",
"biweekly",
"monthly",
null
]
},
"currency": {
"const": "NGN"
},
"targetAmount": {
"type": "integer",
"description": "Whole naira."
},
"amountPaid": {
"type": "integer",
"description": "Whole naira."
},
"outstanding": {
"type": "integer",
"description": "Whole naira."
},
"instalmentAmount": {
"type": [
"integer",
"null"
],
"description": "Whole naira."
},
"instalmentCount": {
"type": [
"integer",
"null"
]
},
"instalmentsPaid": {
"type": "integer"
},
"nextDue": {
"type": [
"object",
"null"
],
"properties": {
"index": {
"type": "integer"
},
"dueAt": {
"type": "string",
"format": "date-time"
},
"amount": {
"type": "integer",
"description": "Whole naira."
}
}
},
"deadline": {
"type": "string",
"format": "date-time"
},
"instalments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 1
},
"dueAt": {
"type": "string",
"format": "date-time"
},
"amount": {
"type": "integer",
"minimum": 200,
"description": "Whole naira."
},
"status": {
"type": "string",
"enum": [
"scheduled",
"paid",
"paid_early",
"missed"
]
},
"paidAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
},
"pendingFee": {
"type": "integer",
"description": "Whole naira."
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"shippedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"deliveredAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"refundWindowEndsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
}
}
}
}422 Valid request that conflicts with the object's state.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}POST
/provider-savings/{id}/cancelCancel a Save to Buy plan
Metered on successful live writes
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/provider-savings/{id}/cancel' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Add a JSON body matching the request schema below and a Content-Type: application/json header.
Parameters
idpath · string · requiredRequest body schema
{
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 250
}
}
}
}
}
}Responses
200 The cancelled plan. Any limited slot is released.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "SB-7F3K9Q"
},
"object": {
"const": "savings_plan"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"overdue",
"completed",
"shipped",
"delivered",
"cancelled"
]
},
"productName": {
"type": "string"
},
"productImage": {
"type": [
"string",
"null"
],
"format": "uri"
},
"mode": {
"type": "string",
"enum": [
"fixed",
"flexible"
]
},
"frequency": {
"type": [
"string",
"null"
],
"enum": [
"daily",
"weekly",
"biweekly",
"monthly",
null
]
},
"currency": {
"const": "NGN"
},
"targetAmount": {
"type": "integer",
"description": "Whole naira."
},
"amountPaid": {
"type": "integer",
"description": "Whole naira."
},
"outstanding": {
"type": "integer",
"description": "Whole naira."
},
"instalmentAmount": {
"type": [
"integer",
"null"
],
"description": "Whole naira."
},
"instalmentCount": {
"type": [
"integer",
"null"
]
},
"instalmentsPaid": {
"type": "integer"
},
"nextDue": {
"type": [
"object",
"null"
],
"properties": {
"index": {
"type": "integer"
},
"dueAt": {
"type": "string",
"format": "date-time"
},
"amount": {
"type": "integer",
"description": "Whole naira."
}
}
},
"deadline": {
"type": "string",
"format": "date-time"
},
"instalments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 1
},
"dueAt": {
"type": "string",
"format": "date-time"
},
"amount": {
"type": "integer",
"minimum": 200,
"description": "Whole naira."
},
"status": {
"type": "string",
"enum": [
"scheduled",
"paid",
"paid_early",
"missed"
]
},
"paidAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
},
"pendingFee": {
"type": "integer",
"description": "Whole naira."
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"shippedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"deliveredAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"refundWindowEndsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
}
}
}
}403 Insufficient scope, or live access not enabled.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}GET
/public/save-to-buy/plans/{planId}Retrieve public Save to Buy terms
Not metered
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/public/save-to-buy/plans/{planId}' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
planIdpath · string · requiredResponses
200 Product terms and available instalment options.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"planId": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"image": {
"type": [
"string",
"null"
],
"format": "uri"
},
"merchant": {
"type": "string"
},
"currency": {
"const": "NGN"
},
"targetAmount": {
"type": "integer",
"description": "Whole naira."
},
"cycleMonths": {
"type": "integer"
},
"mode": {
"type": "string",
"enum": [
"fixed",
"flexible"
]
},
"allowedFrequencies": {
"type": "array",
"items": {
"type": "string",
"enum": [
"daily",
"weekly",
"biweekly",
"monthly"
]
}
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"frequency": {
"type": "string"
},
"count": {
"type": "integer"
},
"amount": {
"type": "integer"
},
"finalAmount": {
"type": "integer"
},
"total": {
"type": "integer"
},
"valid": {
"type": "boolean"
}
}
}
},
"slots": {
"type": "object",
"properties": {
"total": {
"type": [
"integer",
"null"
]
},
"remaining": {
"type": [
"integer",
"null"
]
},
"soldOut": {
"type": "boolean"
}
}
},
"minPayment": {
"const": 200
}
}
}
}
}
}
}404 Object or route not found in this environment.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}POST
/public/save-to-buy/plans/{planId}/startStart a Save to Buy plan
Not metered
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/public/save-to-buy/plans/{planId}/start' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Add a JSON body matching the request schema below and a Content-Type: application/json header.
Parameters
planIdpath · string · requiredRequest body schema
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"frequency",
"name",
"email",
"phone"
],
"properties": {
"frequency": {
"type": "string",
"enum": [
"daily",
"weekly",
"biweekly",
"monthly"
]
},
"name": {
"type": "string",
"minLength": 2,
"maxLength": 100
},
"email": {
"type": "string",
"format": "email"
},
"phone": {
"type": "string",
"description": "Nigerian phone number in local or +234 format."
},
"delivery": {
"type": "object",
"properties": {
"address": {
"type": "string",
"maxLength": 250
},
"city": {
"type": "string",
"maxLength": 80
},
"state": {
"type": "string",
"maxLength": 80
},
"note": {
"type": "string",
"maxLength": 250
}
}
},
"amount": {
"type": "integer",
"minimum": 200,
"description": "Whole naira; flexible plans only."
}
}
}
}
}
}Responses
201 Plan created with the first payment link.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"publicId": {
"type": "string",
"example": "SB-7F3K9Q"
},
"accessToken": {
"type": "string",
"description": "Secret buyer token. Never expose it in merchant systems or logs."
},
"pageUrl": {
"type": "string",
"format": "uri"
},
"paymentUrl": {
"type": "string",
"format": "uri"
},
"amountDue": {
"type": "integer",
"description": "Whole naira."
}
}
}
}
}
}
}400 Invalid request.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}422 Valid request that conflicts with the object's state.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}429 Too many requests.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}GET
/public/save-to-buy/p/{token}Retrieve a buyer's private plan
The token is secret. Treat this URL like a password-reset link.
Not metered
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/public/save-to-buy/p/{token}' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
tokenpath · string · requiredResponses
200 The buyer's private plan.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "SB-7F3K9Q"
},
"object": {
"const": "savings_plan"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"overdue",
"completed",
"shipped",
"delivered",
"cancelled"
]
},
"productName": {
"type": "string"
},
"productImage": {
"type": [
"string",
"null"
],
"format": "uri"
},
"mode": {
"type": "string",
"enum": [
"fixed",
"flexible"
]
},
"frequency": {
"type": [
"string",
"null"
],
"enum": [
"daily",
"weekly",
"biweekly",
"monthly",
null
]
},
"currency": {
"const": "NGN"
},
"targetAmount": {
"type": "integer",
"description": "Whole naira."
},
"amountPaid": {
"type": "integer",
"description": "Whole naira."
},
"outstanding": {
"type": "integer",
"description": "Whole naira."
},
"instalmentAmount": {
"type": [
"integer",
"null"
],
"description": "Whole naira."
},
"instalmentCount": {
"type": [
"integer",
"null"
]
},
"instalmentsPaid": {
"type": "integer"
},
"nextDue": {
"type": [
"object",
"null"
],
"properties": {
"index": {
"type": "integer"
},
"dueAt": {
"type": "string",
"format": "date-time"
},
"amount": {
"type": "integer",
"description": "Whole naira."
}
}
},
"deadline": {
"type": "string",
"format": "date-time"
},
"instalments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 1
},
"dueAt": {
"type": "string",
"format": "date-time"
},
"amount": {
"type": "integer",
"minimum": 200,
"description": "Whole naira."
},
"status": {
"type": "string",
"enum": [
"scheduled",
"paid",
"paid_early",
"missed"
]
},
"paidAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
},
"pendingFee": {
"type": "integer",
"description": "Whole naira."
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"shippedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"deliveredAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"refundWindowEndsAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
}
}
}
}404 Object or route not found in this environment.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}POST
/public/save-to-buy/p/{token}/payCreate a Save to Buy payment link
Not metered
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/public/save-to-buy/p/{token}/pay' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Add a JSON body matching the request schema below and a Content-Type: application/json header.
Parameters
tokenpath · string · requiredRequest body schema
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"instalments": {
"type": "integer",
"minimum": 1
},
"payBalance": {
"type": "boolean"
},
"amount": {
"type": "integer",
"minimum": 200,
"description": "Whole naira; flexible plans only."
}
}
}
}
}
}Responses
200 Payment link.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"paymentUrl": {
"type": "string",
"format": "uri"
},
"amountDue": {
"type": "integer"
}
}
}
}
}
}
}422 Valid request that conflicts with the object's state.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}429 Too many requests.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}POST
/public/save-to-buy/p/{token}/pay-feeCreate an extension-fee payment link
Not metered
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/public/save-to-buy/p/{token}/pay-fee' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
tokenpath · string · requiredResponses
200 Extension-fee payment link.
{
"description": "Extension-fee payment link."
}429 Too many requests.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}POST
/public/save-to-buy/p/{token}/cancelCancel a buyer's Save to Buy plan
Not metered
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/public/save-to-buy/p/{token}/cancel' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
tokenpath · string · requiredResponses
200 The cancelled plan and released slot.
{
"description": "The cancelled plan and released slot."
}429 Too many requests.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"request_id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"authentication_error",
"permission_error",
"invalid_request_error",
"state_error",
"idempotency_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}