subbySubscriptions
A customer's recurring billing on a plan.
https://sandbox-api.mysubbyapp.com/v1
POST
/subscriptionsCreate a subscription
Creates a subscription for a customer who already has a payment method. To collect a payment method at the same time, use a checkout session in `subscription` mode instead.
Metered on successful live writessubscriptions:write
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/subscriptions' \
--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": [
"customer",
"plan"
],
"properties": {
"customer": {
"type": "string"
},
"plan": {
"type": "string"
},
"quantity": {
"type": "integer",
"minimum": 1,
"default": 1
},
"payment_method": {
"type": "string",
"description": "Defaults to the customer's default payment method."
},
"trial_days": {
"type": "integer",
"description": "Overrides the plan's trial_days."
},
"start_at": {
"type": "string",
"format": "date-time",
"description": "Start in the future. Defaults to now."
},
"metadata": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"maxLength": 40
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
}
}
}
}
}
}Responses
201 The created subscription.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "sub_9fK3mQ2xLp"
},
"object": {
"const": "subscription"
},
"status": {
"type": "string",
"enum": [
"incomplete",
"trialing",
"active",
"past_due",
"paused",
"cancelled"
]
},
"customer": {
"type": "string",
"description": "ID, or Customer when expanded."
},
"plan": {
"type": "string",
"description": "ID, or Plan when expanded."
},
"quantity": {
"type": "integer"
},
"current_period_start": {
"type": "string",
"format": "date-time"
},
"current_period_end": {
"type": "string",
"format": "date-time"
},
"next_charge_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"trial_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancel_at_period_end": {
"type": "boolean"
},
"paused_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"resumes_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelled_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancellation_reason": {
"type": [
"string",
"null"
],
"enum": [
"customer_request",
"merchant_request",
"nonpayment",
"checkout_expired",
"other",
null
]
},
"retry": {
"type": [
"object",
"null"
],
"properties": {
"attempt": {
"type": "integer"
},
"max_attempts": {
"type": "integer"
},
"next_retry_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
"escalation": {
"type": [
"object",
"null"
],
"properties": {
"action": {
"type": "string",
"enum": [
"pause",
"restrict",
"hold",
"none"
]
},
"triggered_at": {
"type": "string",
"format": "date-time"
}
}
},
"latest_charge": {
"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"
}
}
}
}
}
}
}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
/subscriptionsList subscriptions
Not meteredsubscriptions:read
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/subscriptions' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
limitquery · integer starting_afterquery · string ending_beforequery · string expand[]query · array Related fields to expand, up to 4.
customerquery · string planquery · string statusquery · string Responses
200 Subscriptions, newest first.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "sub_9fK3mQ2xLp"
},
"object": {
"const": "subscription"
},
"status": {
"type": "string",
"enum": [
"incomplete",
"trialing",
"active",
"past_due",
"paused",
"cancelled"
]
},
"customer": {
"type": "string",
"description": "ID, or Customer when expanded."
},
"plan": {
"type": "string",
"description": "ID, or Plan when expanded."
},
"quantity": {
"type": "integer"
},
"current_period_start": {
"type": "string",
"format": "date-time"
},
"current_period_end": {
"type": "string",
"format": "date-time"
},
"next_charge_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"trial_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancel_at_period_end": {
"type": "boolean"
},
"paused_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"resumes_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelled_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancellation_reason": {
"type": [
"string",
"null"
],
"enum": [
"customer_request",
"merchant_request",
"nonpayment",
"checkout_expired",
"other",
null
]
},
"retry": {
"type": [
"object",
"null"
],
"properties": {
"attempt": {
"type": "integer"
},
"max_attempts": {
"type": "integer"
},
"next_retry_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
"escalation": {
"type": [
"object",
"null"
],
"properties": {
"action": {
"type": "string",
"enum": [
"pause",
"restrict",
"hold",
"none"
]
},
"triggered_at": {
"type": "string",
"format": "date-time"
}
}
},
"latest_charge": {
"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
/subscriptions/{id}Retrieve a subscription
Not meteredsubscriptions:read
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/subscriptions/{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 subscription.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "sub_9fK3mQ2xLp"
},
"object": {
"const": "subscription"
},
"status": {
"type": "string",
"enum": [
"incomplete",
"trialing",
"active",
"past_due",
"paused",
"cancelled"
]
},
"customer": {
"type": "string",
"description": "ID, or Customer when expanded."
},
"plan": {
"type": "string",
"description": "ID, or Plan when expanded."
},
"quantity": {
"type": "integer"
},
"current_period_start": {
"type": "string",
"format": "date-time"
},
"current_period_end": {
"type": "string",
"format": "date-time"
},
"next_charge_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"trial_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancel_at_period_end": {
"type": "boolean"
},
"paused_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"resumes_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelled_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancellation_reason": {
"type": [
"string",
"null"
],
"enum": [
"customer_request",
"merchant_request",
"nonpayment",
"checkout_expired",
"other",
null
]
},
"retry": {
"type": [
"object",
"null"
],
"properties": {
"attempt": {
"type": "integer"
},
"max_attempts": {
"type": "integer"
},
"next_retry_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
"escalation": {
"type": [
"object",
"null"
],
"properties": {
"action": {
"type": "string",
"enum": [
"pause",
"restrict",
"hold",
"none"
]
},
"triggered_at": {
"type": "string",
"format": "date-time"
}
}
},
"latest_charge": {
"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
/subscriptions/{id}Update a subscription
Change plan, quantity, payment method, metadata, or undo a scheduled cancellation.
Metered on successful live writessubscriptions:write
Request example
curl --request PATCH \
--url 'https://sandbox-api.mysubbyapp.com/v1/subscriptions/{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": {
"plan": {
"type": "string"
},
"quantity": {
"type": "integer",
"minimum": 1
},
"proration": {
"type": "string",
"enum": [
"prorate_now",
"next_period",
"none"
],
"default": "prorate_now"
},
"payment_method": {
"type": "string"
},
"cancel_at_period_end": {
"type": "boolean"
},
"metadata": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"maxLength": 40
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
}
}
}
}
}
}Responses
200 The updated subscription.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "sub_9fK3mQ2xLp"
},
"object": {
"const": "subscription"
},
"status": {
"type": "string",
"enum": [
"incomplete",
"trialing",
"active",
"past_due",
"paused",
"cancelled"
]
},
"customer": {
"type": "string",
"description": "ID, or Customer when expanded."
},
"plan": {
"type": "string",
"description": "ID, or Plan when expanded."
},
"quantity": {
"type": "integer"
},
"current_period_start": {
"type": "string",
"format": "date-time"
},
"current_period_end": {
"type": "string",
"format": "date-time"
},
"next_charge_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"trial_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancel_at_period_end": {
"type": "boolean"
},
"paused_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"resumes_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelled_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancellation_reason": {
"type": [
"string",
"null"
],
"enum": [
"customer_request",
"merchant_request",
"nonpayment",
"checkout_expired",
"other",
null
]
},
"retry": {
"type": [
"object",
"null"
],
"properties": {
"attempt": {
"type": "integer"
},
"max_attempts": {
"type": "integer"
},
"next_retry_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
"escalation": {
"type": [
"object",
"null"
],
"properties": {
"action": {
"type": "string",
"enum": [
"pause",
"restrict",
"hold",
"none"
]
},
"triggered_at": {
"type": "string",
"format": "date-time"
}
}
},
"latest_charge": {
"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"
}
}
}
}
}
}
}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
/subscriptions/{id}/pausePause a subscription
Metered on successful live writessubscriptions:write
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/subscriptions/{id}/pause' \
--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 · requiredIdempotency-Keyheader · string Makes retries safe. Replays return the original response and are not metered.
Request body schema
{
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resumes_at": {
"type": "string",
"format": "date-time",
"description": "Resume automatically at this time. Omit to pause until resumed."
},
"reason": {
"type": "string",
"maxLength": 200
}
}
}
}
}
}Responses
200 The paused subscription.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "sub_9fK3mQ2xLp"
},
"object": {
"const": "subscription"
},
"status": {
"type": "string",
"enum": [
"incomplete",
"trialing",
"active",
"past_due",
"paused",
"cancelled"
]
},
"customer": {
"type": "string",
"description": "ID, or Customer when expanded."
},
"plan": {
"type": "string",
"description": "ID, or Plan when expanded."
},
"quantity": {
"type": "integer"
},
"current_period_start": {
"type": "string",
"format": "date-time"
},
"current_period_end": {
"type": "string",
"format": "date-time"
},
"next_charge_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"trial_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancel_at_period_end": {
"type": "boolean"
},
"paused_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"resumes_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelled_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancellation_reason": {
"type": [
"string",
"null"
],
"enum": [
"customer_request",
"merchant_request",
"nonpayment",
"checkout_expired",
"other",
null
]
},
"retry": {
"type": [
"object",
"null"
],
"properties": {
"attempt": {
"type": "integer"
},
"max_attempts": {
"type": "integer"
},
"next_retry_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
"escalation": {
"type": [
"object",
"null"
],
"properties": {
"action": {
"type": "string",
"enum": [
"pause",
"restrict",
"hold",
"none"
]
},
"triggered_at": {
"type": "string",
"format": "date-time"
}
}
},
"latest_charge": {
"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"
}
}
}
}
}
}
}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
/subscriptions/{id}/resumeResume a paused subscription
Metered on successful live writessubscriptions:write
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/subscriptions/{id}/resume' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
idpath · string · requiredIdempotency-Keyheader · string Makes retries safe. Replays return the original response and are not metered.
Responses
200 The resumed subscription.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "sub_9fK3mQ2xLp"
},
"object": {
"const": "subscription"
},
"status": {
"type": "string",
"enum": [
"incomplete",
"trialing",
"active",
"past_due",
"paused",
"cancelled"
]
},
"customer": {
"type": "string",
"description": "ID, or Customer when expanded."
},
"plan": {
"type": "string",
"description": "ID, or Plan when expanded."
},
"quantity": {
"type": "integer"
},
"current_period_start": {
"type": "string",
"format": "date-time"
},
"current_period_end": {
"type": "string",
"format": "date-time"
},
"next_charge_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"trial_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancel_at_period_end": {
"type": "boolean"
},
"paused_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"resumes_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelled_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancellation_reason": {
"type": [
"string",
"null"
],
"enum": [
"customer_request",
"merchant_request",
"nonpayment",
"checkout_expired",
"other",
null
]
},
"retry": {
"type": [
"object",
"null"
],
"properties": {
"attempt": {
"type": "integer"
},
"max_attempts": {
"type": "integer"
},
"next_retry_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
"escalation": {
"type": [
"object",
"null"
],
"properties": {
"action": {
"type": "string",
"enum": [
"pause",
"restrict",
"hold",
"none"
]
},
"triggered_at": {
"type": "string",
"format": "date-time"
}
}
},
"latest_charge": {
"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"
}
}
}
}
}
}
}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
/subscriptions/{id}/cancelCancel a subscription
Metered on successful live writessubscriptions:write
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/subscriptions/{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 · requiredIdempotency-Keyheader · string Makes retries safe. Replays return the original response and are not metered.
Request body schema
{
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"at_period_end": {
"type": "boolean",
"default": true
},
"reason": {
"type": "string",
"enum": [
"customer_request",
"merchant_request",
"other"
],
"default": "merchant_request"
}
}
}
}
}
}Responses
200 The cancelled (or scheduled to cancel) subscription.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "sub_9fK3mQ2xLp"
},
"object": {
"const": "subscription"
},
"status": {
"type": "string",
"enum": [
"incomplete",
"trialing",
"active",
"past_due",
"paused",
"cancelled"
]
},
"customer": {
"type": "string",
"description": "ID, or Customer when expanded."
},
"plan": {
"type": "string",
"description": "ID, or Plan when expanded."
},
"quantity": {
"type": "integer"
},
"current_period_start": {
"type": "string",
"format": "date-time"
},
"current_period_end": {
"type": "string",
"format": "date-time"
},
"next_charge_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"trial_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancel_at_period_end": {
"type": "boolean"
},
"paused_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"resumes_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelled_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancellation_reason": {
"type": [
"string",
"null"
],
"enum": [
"customer_request",
"merchant_request",
"nonpayment",
"checkout_expired",
"other",
null
]
},
"retry": {
"type": [
"object",
"null"
],
"properties": {
"attempt": {
"type": "integer"
},
"max_attempts": {
"type": "integer"
},
"next_retry_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
"escalation": {
"type": [
"object",
"null"
],
"properties": {
"action": {
"type": "string",
"enum": [
"pause",
"restrict",
"hold",
"none"
]
},
"triggered_at": {
"type": "string",
"format": "date-time"
}
}
},
"latest_charge": {
"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"
}
}
}
}
}
}
}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
/subscriptions/{id}/unit-recordsReport units for a per-unit plan
For plans with `overage_per_unit` (for example litres of diesel or laundry items). Units are billed at the next renewal.
Metered on successful live writessubscriptions:write
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/subscriptions/{id}/unit-records' \
--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 · requiredIdempotency-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": [
"quantity"
],
"properties": {
"quantity": {
"type": "integer",
"minimum": 0
},
"action": {
"type": "string",
"enum": [
"increment",
"set"
],
"default": "increment"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"description": {
"type": "string",
"maxLength": 200
}
}
}
}
}
}Responses
201 The unit record.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "ur_5Tq"
},
"object": {
"const": "unit_record"
},
"subscription": {
"type": "string"
},
"quantity": {
"type": "integer"
},
"action": {
"type": "string",
"enum": [
"increment",
"set"
]
},
"period_total": {
"type": "integer"
},
"timestamp": {
"type": "string",
"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"
}
}
}
}
}
}
}