subbyAccount & usage
Your Subby account, API usage and Subby invoices.
https://sandbox-api.mysubbyapp.com/v1
GET
/accountRetrieve your account
Not metered
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/account' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Responses
200 Your account.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "acct_2Xm9"
},
"object": {
"const": "account"
},
"business_name": {
"type": "string"
},
"api_plan": {
"type": "string",
"enum": [
"starter",
"growth",
"scale",
"enterprise"
]
},
"live_access": {
"type": "string",
"enum": [
"not_requested",
"pending_review",
"approved",
"rejected",
"suspended"
]
},
"livemode": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}401 Missing, invalid, revoked or wrong-environment key.
{
"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
/usageRetrieve current period usage
Write requests, read requests and nudges for the current billing period. Updates in real time.
Not meteredusage:read
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/usage' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Responses
200 Usage for the current period.
{
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"object": {
"const": "usage"
},
"livemode": {
"type": "boolean"
},
"plan": {
"type": "string",
"enum": [
"starter",
"growth",
"scale",
"enterprise"
]
},
"period": {
"type": "object",
"properties": {
"start": {
"type": "string",
"format": "date-time"
},
"end": {
"type": "string",
"format": "date-time"
}
}
},
"write_requests": {
"type": "object",
"properties": {
"used": {
"type": "integer"
},
"included": {
"type": [
"integer",
"null"
],
"description": "null means unlimited."
},
"remaining": {
"type": [
"integer",
"null"
]
},
"overage": {
"type": "integer"
},
"overage_rate_per_1000": {
"type": [
"integer",
"null"
],
"description": "Kobo per 1,000 write requests."
},
"projected_overage_amount": {
"type": "integer",
"description": "Kobo. Final amount is on your invoice."
}
}
},
"read_requests": {
"type": "object",
"properties": {
"used": {
"type": "integer"
},
"metered": {
"const": false
}
}
},
"nudges": {
"type": "object",
"properties": {
"used": {
"type": "integer"
},
"included": {
"type": [
"integer",
"null"
]
},
"overage": {
"type": "integer"
},
"overage_rate": {
"type": [
"integer",
"null"
],
"description": "Kobo per nudge."
},
"overage_amount": {
"type": "integer"
},
"overage_cap": {
"type": [
"integer",
"null"
]
}
}
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}401 Missing, invalid, revoked or wrong-environment key.
{
"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"
}
}
}
}
}
}
}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"
}
}
}
}
}
}
}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
/usage/historyList usage for past periods
Not meteredusage:read
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/usage/history' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
limitquery · integer starting_afterquery · string Responses
200 Past periods, newest first.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"object": {
"const": "usage"
},
"livemode": {
"type": "boolean"
},
"plan": {
"type": "string",
"enum": [
"starter",
"growth",
"scale",
"enterprise"
]
},
"period": {
"type": "object",
"properties": {
"start": {
"type": "string",
"format": "date-time"
},
"end": {
"type": "string",
"format": "date-time"
}
}
},
"write_requests": {
"type": "object",
"properties": {
"used": {
"type": "integer"
},
"included": {
"type": [
"integer",
"null"
],
"description": "null means unlimited."
},
"remaining": {
"type": [
"integer",
"null"
]
},
"overage": {
"type": "integer"
},
"overage_rate_per_1000": {
"type": [
"integer",
"null"
],
"description": "Kobo per 1,000 write requests."
},
"projected_overage_amount": {
"type": "integer",
"description": "Kobo. Final amount is on your invoice."
}
}
},
"read_requests": {
"type": "object",
"properties": {
"used": {
"type": "integer"
},
"metered": {
"const": false
}
}
},
"nudges": {
"type": "object",
"properties": {
"used": {
"type": "integer"
},
"included": {
"type": [
"integer",
"null"
]
},
"overage": {
"type": "integer"
},
"overage_rate": {
"type": [
"integer",
"null"
],
"description": "Kobo per nudge."
},
"overage_amount": {
"type": "integer"
},
"overage_cap": {
"type": [
"integer",
"null"
]
}
}
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"meta": {
"type": "object",
"required": [
"has_more",
"limit"
],
"properties": {
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"limit": {
"type": "integer"
}
}
}
}
}
}
}401 Missing, invalid, revoked or wrong-environment key.
{
"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
/account/invoicesList your Subby invoices
Not meteredusage:read
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/account/invoices' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
limitquery · integer starting_afterquery · string ending_beforequery · string statusquery · string Responses
200 Invoices, newest first.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "inv_2026_09_8k1"
},
"object": {
"const": "invoice"
},
"status": {
"type": "string",
"enum": [
"open",
"paid",
"overdue",
"void"
]
},
"period_start": {
"type": "string",
"format": "date-time"
},
"period_end": {
"type": "string",
"format": "date-time"
},
"currency": {
"const": "NGN"
},
"lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"plan_fee",
"write_request_overage",
"nudge_overage",
"proration",
"credit"
]
},
"description": {
"type": "string"
},
"quantity": {
"type": "integer"
},
"unit_amount": {
"type": "integer"
},
"amount": {
"type": "integer"
}
}
}
},
"total": {
"type": "integer"
},
"due_at": {
"type": "string",
"format": "date-time"
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"pdf_url": {
"type": "string",
"format": "uri"
}
}
}
},
"meta": {
"type": "object",
"required": [
"has_more",
"limit"
],
"properties": {
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"limit": {
"type": "integer"
}
}
}
}
}
}
}401 Missing, invalid, revoked or wrong-environment key.
{
"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
/account/invoices/{id}Retrieve a Subby invoice
Not meteredusage:read
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/account/invoices/{id}' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
idpath · string · requiredResponses
200 The invoice.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "inv_2026_09_8k1"
},
"object": {
"const": "invoice"
},
"status": {
"type": "string",
"enum": [
"open",
"paid",
"overdue",
"void"
]
},
"period_start": {
"type": "string",
"format": "date-time"
},
"period_end": {
"type": "string",
"format": "date-time"
},
"currency": {
"const": "NGN"
},
"lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"plan_fee",
"write_request_overage",
"nudge_overage",
"proration",
"credit"
]
},
"description": {
"type": "string"
},
"quantity": {
"type": "integer"
},
"unit_amount": {
"type": "integer"
},
"amount": {
"type": "integer"
}
}
}
},
"total": {
"type": "integer"
},
"due_at": {
"type": "string",
"format": "date-time"
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"pdf_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}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
/webhook-ipsList webhook source IP addresses
Not metered
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/webhook-ips' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Responses
200 IP addresses Subby sends webhooks from.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"ipv4": {
"type": "array",
"items": {
"type": "string"
}
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}