subbyCheckout sessions
Subby-hosted pages that collect payment details.
https://sandbox-api.mysubbyapp.com/v1
POST
/checkout-sessionsCreate a checkout session
Metered on successful live writescheckout_sessions:write
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/checkout-sessions' \
--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": [
"mode",
"success_url",
"cancel_url"
],
"properties": {
"mode": {
"type": "string",
"enum": [
"subscription",
"setup"
],
"description": "`setup` only collects a payment method."
},
"customer": {
"type": "string",
"description": "Existing customer. If omitted, a customer is created from checkout details."
},
"plan": {
"type": "string",
"description": "Required in subscription mode."
},
"quantity": {
"type": "integer",
"minimum": 1,
"default": 1
},
"success_url": {
"type": "string",
"format": "uri"
},
"cancel_url": {
"type": "string",
"format": "uri"
},
"expires_in_minutes": {
"type": "integer",
"minimum": 30,
"maximum": 1440,
"default": 1440
},
"metadata": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"maxLength": 40
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
}
}
}
}
}
}Responses
201 The session. Redirect the customer to `url`.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cs_7Hn2Qp"
},
"object": {
"const": "checkout_session"
},
"mode": {
"type": "string",
"enum": [
"subscription",
"setup"
]
},
"status": {
"type": "string",
"enum": [
"open",
"completed",
"expired"
]
},
"url": {
"type": "string",
"format": "uri"
},
"customer": {
"type": [
"string",
"null"
]
},
"plan": {
"type": [
"string",
"null"
]
},
"subscription": {
"type": [
"string",
"null"
]
},
"success_url": {
"type": "string",
"format": "uri"
},
"cancel_url": {
"type": "string",
"format": "uri"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"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"
}
}
}
}
}
}
}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"
}
}
}
}
}
}
}GET
/checkout-sessions/{id}Retrieve a checkout session
Not meteredcheckout_sessions:read
Request example
curl --request GET \
--url 'https://sandbox-api.mysubbyapp.com/v1/checkout-sessions/{id}' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
idpath · string · requiredResponses
200 The session.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cs_7Hn2Qp"
},
"object": {
"const": "checkout_session"
},
"mode": {
"type": "string",
"enum": [
"subscription",
"setup"
]
},
"status": {
"type": "string",
"enum": [
"open",
"completed",
"expired"
]
},
"url": {
"type": "string",
"format": "uri"
},
"customer": {
"type": [
"string",
"null"
]
},
"plan": {
"type": [
"string",
"null"
]
},
"subscription": {
"type": [
"string",
"null"
]
},
"success_url": {
"type": "string",
"format": "uri"
},
"cancel_url": {
"type": "string",
"format": "uri"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"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"
}
}
}
}
}
}
}POST
/checkout-sessions/{id}/expireExpire a checkout session
Metered on successful live writescheckout_sessions:write
Request example
curl --request POST \
--url 'https://sandbox-api.mysubbyapp.com/v1/checkout-sessions/{id}/expire' \
--header 'Authorization: Bearer sk_test_YOUR_SECRET_KEY'Parameters
idpath · string · requiredResponses
200 The expired session.
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cs_7Hn2Qp"
},
"object": {
"const": "checkout_session"
},
"mode": {
"type": "string",
"enum": [
"subscription",
"setup"
]
},
"status": {
"type": "string",
"enum": [
"open",
"completed",
"expired"
]
},
"url": {
"type": "string",
"format": "uri"
},
"customer": {
"type": [
"string",
"null"
]
},
"plan": {
"type": [
"string",
"null"
]
},
"subscription": {
"type": [
"string",
"null"
]
},
"success_url": {
"type": "string",
"format": "uri"
},
"cancel_url": {
"type": "string",
"format": "uri"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"metadata": {
"type": "object",
"maxProperties": 20,
"propertyNames": {
"maxLength": 40
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"livemode": {
"type": "boolean"
},
"created_at": {
"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"
}
}
}
}
}
}
}