subbyCustomers
The people or businesses you bill.
https://sandbox-api.mysubbyapp.com/v1
POST
/customersCreate a customer
Metered on successful live writescustomers:write
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/customers' \
--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
Idempotency-Keyheader · string Makes retries safe. Replays return the original response and are not metered.
Request body schema
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 120
},
"email": {
"type": "string",
"format": "email"
},
"phone": {
"type": "string",
"description": "E.164, e.g. +2348012345678."
},
"metadata": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"maxLength": 40
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"test_clock": {
"type": "string",
"description": "Sandbox only."
}
}
},
"example": {
"name": "Ada Okafor",
"email": "ada@example.com",
"phone": "+2348000000001",
"metadata": {
"your_user_id": "u_1024"
}
}
}
}
}Responses
201 The created customer.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cus_4kQ2mT"
},
"object": {
"const": "customer"
},
"name": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
]
},
"phone": {
"type": [
"string",
"null"
]
},
"default_payment_method": {
"oneOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "pm_2Hx9"
},
"type": {
"type": "string",
"enum": [
"card",
"bank_account",
"ussd"
]
},
"brand": {
"type": [
"string",
"null"
],
"example": "verve"
},
"last4": {
"type": [
"string",
"null"
]
},
"bank_name": {
"type": [
"string",
"null"
]
},
"exp_month": {
"type": [
"integer",
"null"
]
},
"exp_year": {
"type": [
"integer",
"null"
]
}
}
}
]
},
"test_clock": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"maxLength": 40
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"livemode": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}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"
}
}
}
}
}
}
}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"
}
}
}
}
}
}
}409 Idempotency conflict.
{
"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
/customersList customers
Not meteredcustomers:read
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/customers' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
limitquery · integer starting_afterquery · string ending_beforequery · string emailquery · string phonequery · string metadataquery · object Filter by one metadata key, e.g. `metadata[your_user_id]=u_1024`.
Responses
200 Customers, newest first.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cus_4kQ2mT"
},
"object": {
"const": "customer"
},
"name": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
]
},
"phone": {
"type": [
"string",
"null"
]
},
"default_payment_method": {
"oneOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "pm_2Hx9"
},
"type": {
"type": "string",
"enum": [
"card",
"bank_account",
"ussd"
]
},
"brand": {
"type": [
"string",
"null"
],
"example": "verve"
},
"last4": {
"type": [
"string",
"null"
]
},
"bank_name": {
"type": [
"string",
"null"
]
},
"exp_month": {
"type": [
"integer",
"null"
]
},
"exp_year": {
"type": [
"integer",
"null"
]
}
}
}
]
},
"test_clock": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"maxLength": 40
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"livemode": {
"type": "boolean"
},
"created_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"
}
}
}
}
}
}
}GET
/customers/{id}Retrieve a customer
Not meteredcustomers:read
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/customers/{id}' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
idpath · string · requiredexpand[]query · array Related fields to expand, up to 4.
Responses
200 The customer.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cus_4kQ2mT"
},
"object": {
"const": "customer"
},
"name": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
]
},
"phone": {
"type": [
"string",
"null"
]
},
"default_payment_method": {
"oneOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "pm_2Hx9"
},
"type": {
"type": "string",
"enum": [
"card",
"bank_account",
"ussd"
]
},
"brand": {
"type": [
"string",
"null"
],
"example": "verve"
},
"last4": {
"type": [
"string",
"null"
]
},
"bank_name": {
"type": [
"string",
"null"
]
},
"exp_month": {
"type": [
"integer",
"null"
]
},
"exp_year": {
"type": [
"integer",
"null"
]
}
}
}
]
},
"test_clock": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"maxLength": 40
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"livemode": {
"type": "boolean"
},
"created_at": {
"type": "string",
"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"
}
}
}
}
}
}
}PATCH
/customers/{id}Update a customer
Metered on successful live writescustomers:write
Request example
curl --request PATCH \
--url 'https://sandbox-api.mysubbyapp.com/v1/customers/{id}' \
--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",
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"phone": {
"type": "string"
},
"default_payment_method": {
"type": "string",
"description": "A payment method already attached to this customer, or a `pm_test_` ID in sandbox."
},
"metadata": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"maxLength": 40
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
}
}
}
}
}
}Responses
200 The updated customer.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cus_4kQ2mT"
},
"object": {
"const": "customer"
},
"name": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
]
},
"phone": {
"type": [
"string",
"null"
]
},
"default_payment_method": {
"oneOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "pm_2Hx9"
},
"type": {
"type": "string",
"enum": [
"card",
"bank_account",
"ussd"
]
},
"brand": {
"type": [
"string",
"null"
],
"example": "verve"
},
"last4": {
"type": [
"string",
"null"
]
},
"bank_name": {
"type": [
"string",
"null"
]
},
"exp_month": {
"type": [
"integer",
"null"
]
},
"exp_year": {
"type": [
"integer",
"null"
]
}
}
}
]
},
"test_clock": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"maxLength": 40
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"livemode": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}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"
}
}
}
}
}
}
}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"
}
}
}
}
}
}
}DELETE
/customers/{id}Delete a customer
Cancels the customer's active subscriptions immediately, then deletes the customer.
Metered on successful live writescustomers:write
Request example
curl --request DELETE \
--url 'https://sandbox-api.mysubbyapp.com/v1/customers/{id}' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
idpath · string · requiredResponses
200 Deletion confirmation.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"const": "customer"
},
"deleted": {
"const": true
}
}
}
}
}
}
}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"
}
}
}
}
}
}
}