Subscription
A subscription is a recurring payment for an ongoing product. They are available as escrowed or escrowless (delegated), and can be charged flat or by usage.
Sphere creates subscription
objects automatically after your customer pays for a product with a recurring price via a payment method. subscription
objects can be retrieved for convenient access to important information about your subscriptions, such as their remaining billing cycles and cancellation schedules.
Since subscription
objects are auto-generated upon an attempt to pay for a product with a recurring price, you as the developer do not need to create them or explicitly specify that a product is a subscription
. All products with recurring prices, that are included as line items in a payment method, will auto-generate subscriptions when a customer attempts to pay. Put differently, subscription objects are created if and only if a product with a recurring price is attempted to be purchased.
The Subscription object
Properties
- Name
id
- Type
- string
- Description
A unique identifier for the object.
- Name
name
- Type
- string
- Description
The name of your subscription. Hidden from users. Max length (500).
- Name
description
- Type
- string
- Description
Describes your subscription. Hidden from users. Max length (500).
- Name
type
- Type
- enum
- Description
Defines how your customers will pay for the subscription.
escrowed
: Users fund an escrow account, which is withdrawn from per billing period.delegated
: Users have funds automatically withdrawn from their wallet per billing period.
- Name
status
- Type
- enum
- Description
Identifies the current status of the subscription.
pending
: A subscription is set topending
on creation of the subscription (i.e., when someone clicks the pay button).incomplete
: A subscription becomesincomplete
if the intial payment attempt fails.active
: A subscription becomesactive
once we detect that the customer has escrowed/delegated the required amount of tokens on-chain.pastDue
: A subscription moves topastDue
when the payment is required but cannot be paid due to a failed payment or awaiting additional user interactions (i.e., updating their subscription to approve or escrow more tokens).canceled
: A subscription moves tocanceled
if it ispastDue
and we have attempted to bill the subscription three times without success.
- Name
meta
- Type
- object
- Description
Set of key-value pairs (JSON) for arbitrary usage. Used to save structured information about the object to reference elsewhere. Think of it as general purpose storage space.
- Name
network
- Type
- enum
- Description
The underlying network of your subscription. The only subscription supported network is
sol
.
- Name
source
- Type
- string
- Description
The source, a Solana pubkey, the subscription bills from. The escrow wallet for
escrowed
subscriptions, or the delegated wallet fordelegated
subscriptions (the wallet the customer payed with).
- Name
approvedAmount
- Type
- string
- Description
Amount of tokens that the customer is approving to either send to an escrow account (
escrowed
) or delegating to Sphere for automatic withdrawal from their wallet (delegated
).
- Name
approvedAmountDecimal
- Type
- number
- Description
Identical to
approvedAmount
, but with automatic conversion to base-10 (decimal) instead of the default unit amount for a given currency.
- Name
billingRetries
- Type
- number
- Description
The number of times the system has attempted to bill the subscription.
- Name
lastBilling
- Type
- string
- Description
Datetime for when the subscription was last billed.
- Name
periodsBilled
- Type
- number
- Description
The number of billing periods that have been billed.
- Name
periodsRemaining
- Type
- number
- Description
The number of billing periods remaining.
- Name
customer
- Type
- string
- Description
The
id
of the associated customer used for the subscription.
- Name
subscriptionItems
- Type
- object array
- Description
Defines the products with recurring prices that are being charged for in the subscription. Identical to
lineItems
, except that eachprice
must berecurring
.- Relevant for metered billing, because you will need to include each relevant
subscriptionItem
objectid
when creating or updating ausageRecord
to correctly bill for usage. - Name
id
- Type
- string
- Description
Unique identifier for the subscription item. Auto-generated by Sphere upon creation.
- Relevant for metered billing, because you will need to include each relevant
- Name
price
- Type
- object
- Description
The
price
object associated with the subscription item.
- Name
product
- Type
- object
- Description
The
product
object associated with the subscription item.
- Name
quantity
- Type
- number
- Description
The quantity of the subscription item.
- Name
updated
- Type
- string
- Description
Datetime for when the subscription item was last updated.
- Name
created
- Type
- string
- Description
Datetime for when the subscription item was created.
- Name
cancellation
- Type
- object
- Description
Contains important details about when a subscription gets cancelled.
- Name
cancelAt
- Type
- string
- Description
Datetime for when the subscription is scheduled to be cancelled.
- Name
canceledAt
- Type
- string
- Description
Datetime for when the subscription was cancelled.
- Name
reason
- Type
- enum
- Description
Why the subscription was cancelled. One of
complete
,insufficientDelegatedBalance
,insufficientDelegatedApprovedBalance
,insufficientEscrowedBalance
,redelegated
, orcustomerHasCancelled
.
- Name
feedback
- Type
- string
- Description
User feedback for why they cancelled.
- Name
paymentLink
- Type
- object
- Description
The
paymentLink
object associated with the subscription.- Refer to the Payment Link object for more details.
- Name
secondsUntilDue
- Type
- number
- Description
The number of seconds until the next billing period is due.
- Name
currentPeriodEnd
- Type
- number
- Description
The Unix timestamp of when the current billing period ends.
- Name
currentPeriodStart
- Type
- number
- Description
The Unix timestamp of when the current billing period started.
- Name
updated
- Type
- number
- Description
Datetime for when the subscription was last updated.
- Name
created
- Type
- string
- Description
Datetime for when the subscription was created.
Subscription Object
{
"id": "subscription_52aaaf0a67644cee9d75193a67161af0",
"type": "delegated",
"name": "",
"description": "",
"status": "canceled",
"meta": {},
"network": "sol",
"source": "H7zbGjoKvsYYscQy4sV3vcn8VVwwx1jU4i63ye5zzBrn",
"approvedAmount": "0",
"approvedAmountDecimal": 0,
"periodsBilled": 2,
"billingRetries": 4,
"lastBilling": "2024-05-26T16:00:10.162Z",
"periodsRemaining": 2,
"billedAmount": "100000",
"customer": "customer_4646908d5f5e45f0ab03d2cd80ab9031",
"subscriptionItems": [
{
"id": "subscriptionItem_172e41e39b3d46e0a3c791369254c1b1",
"quantity": 1,
"price": {
"id": "price_ac657021b2984749962f9c1d64cf5b44",
"active": true,
"name": null,
"description": null,
"meta": {},
"network": "sol",
"billingScheme": "tiered",
"taxBehavior": "exclusive",
"type": "recurring",
"tierType": "volume",
"tiers": [
{
"index": 1,
"upTo": 1,
"flatAmount": "0",
"flatAmountDecimal": 0,
"unitAmount": "100000",
"unitAmountDecimal": 1,
"updated": "2024-05-07T22:37:32.323Z",
"created": "2024-05-07T22:37:32.239Z"
},
{
"index": 2,
"upTo": "inf",
"flatAmount": "0",
"flatAmountDecimal": 0,
"unitAmount": "50000",
"unitAmountDecimal": 0.5,
"updated": "2024-05-07T22:37:32.323Z",
"created": "2024-05-07T22:37:32.285Z"
}
],
"currencyOptions": [],
"currency": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
"unitAmount": "0",
"unitAmountDecimal": 0,
"customUnitAmount": null,
"recurring": {
"type": "delegated",
"usageAggregation": "sum",
"interval": "min",
"intervalCount": 1,
"usageType": "licensed",
"defaultLength": 2,
"expectedUsagePerInterval": null
},
"product": "product_8d4341df772d4f9ea53802f0a31469e0",
"updated": "2024-05-07T22:37:34.383Z",
"created": "2024-05-07T22:37:32.323Z"
},
"product": {
"id": "product_8d4341df772d4f9ea53802f0a31469e0",
"name": "Volume Subscription",
"description": "",
"images": [],
"tags": [],
"meta": {},
"prices": [],
"updated": "2024-05-07T22:37:34.383Z",
"created": "2024-05-07T22:37:34.383Z"
},
"updated": "2024-05-07T22:37:57.521Z",
"created": "2024-05-07T22:37:57.498Z"
}
],
"cancellation": {
"cancelAt": null,
"canceledAt": null,
"reason": "insufficientDelegatedApprovedBalance",
"feedback": null
},
"paymentLink": {
"id": "paymentLink_d9535b46ad2f4560955a012a78432b7e",
"name": "",
"description": "",
"meta": {},
"url": "https://spherepay.co/pay/paymentLink_d9535b46ad2f4560955a012a78432b7e",
"successUrl": "",
"failUrl": "",
"start": null,
"end": null,
"taxRate": null,
"shippingRate": null,
"lineItems": [],
"features": {
"requiresEmail": true,
"requiresName": true,
"requiresShippingDetails": false
},
"coupon": null,
"discordConstraints": null,
"globalConstraint": null,
"wallets": [],
"phases": [],
"updated": "2024-05-07T22:37:44.566Z",
"created": "2024-05-07T22:37:44.566Z"
},
"secondsUntilDue": 0,
"currentPeriodStart": 1715121547,
"currentPeriodEnd": 1715121607,
"updated": "2024-05-27T16:00:01.317Z",
"created": "2024-05-07T22:37:57.521Z"
}
Retrieve a subscription
Retrieves a subscription
object by id
.
Request
curl https://api.spherepay.co/v1/susbcription/subscription_e504a799e0624bb998274f7477dd3e77 \
-H "Authorization: Bearer {token}"
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"subscription": {
"id": "subscription_52aaaf0a67644cee9d75193a67161af0",
"type": "delegated",
"name": "",
"description": "",
"status": "canceled",
"meta": {},
"network": "sol",
"source": "H7zbGjoKvsYYscQy4sV3vcn8VVwwx1jU4i63ye5zzBrn",
"approvedAmount": "0",
"approvedAmountDecimal": 0,
"periodsBilled": 2,
"billingRetries": 4,
"lastBilling": "2024-05-26T16:00:10.162Z",
"periodsRemaining": 2,
"billedAmount": "100000",
"customer": "customer_4646908d5f5e45f0ab03d2cd80ab9031",
"subscriptionItems": [
{
"id": "subscriptionItem_172e41e39b3d46e0a3c791369254c1b1",
"quantity": 1,
"price": {
"id": "price_ac657021b2984749962f9c1d64cf5b44",
"active": true,
"name": null,
"description": null,
"meta": {},
"network": "sol",
"billingScheme": "tiered",
"taxBehavior": "exclusive",
"type": "recurring",
"tierType": "volume",
"tiers": [
{
"index": 1,
"upTo": 1,
"flatAmount": "0",
"flatAmountDecimal": 0,
"unitAmount": "100000",
"unitAmountDecimal": 1,
"updated": "2024-05-07T22:37:32.323Z",
"created": "2024-05-07T22:37:32.239Z"
},
{
"index": 2,
"upTo": "inf",
"flatAmount": "0",
"flatAmountDecimal": 0,
"unitAmount": "50000",
"unitAmountDecimal": 0.5,
"updated": "2024-05-07T22:37:32.323Z",
"created": "2024-05-07T22:37:32.285Z"
}
],
"currencyOptions": [],
"currency": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
"unitAmount": "0",
"unitAmountDecimal": 0,
"customUnitAmount": null,
"recurring": {
"type": "delegated",
"usageAggregation": "sum",
"interval": "min",
"intervalCount": 1,
"usageType": "licensed",
"defaultLength": 2,
"expectedUsagePerInterval": null
},
"product": "product_8d4341df772d4f9ea53802f0a31469e0",
"updated": "2024-05-07T22:37:34.383Z",
"created": "2024-05-07T22:37:32.323Z"
},
"product": {
"id": "product_8d4341df772d4f9ea53802f0a31469e0",
"name": "Volume Subscription",
"description": "",
"images": [],
"tags": [],
"meta": {},
"prices": [],
"updated": "2024-05-07T22:37:34.383Z",
"created": "2024-05-07T22:37:34.383Z"
},
"updated": "2024-05-07T22:37:57.521Z",
"created": "2024-05-07T22:37:57.498Z"
}
],
"cancellation": {
"cancelAt": null,
"canceledAt": null,
"reason": "insufficientDelegatedApprovedBalance",
"feedback": null
},
"paymentLink": {
"id": "paymentLink_d9535b46ad2f4560955a012a78432b7e",
"name": "",
"description": "",
"meta": {},
"url": "https://spherepay.co/pay/paymentLink_d9535b46ad2f4560955a012a78432b7e",
"successUrl": "",
"failUrl": "",
"start": null,
"end": null,
"taxRate": null,
"shippingRate": null,
"lineItems": [],
"features": {
"requiresEmail": true,
"requiresName": true,
"requiresShippingDetails": false
},
"coupon": null,
"discordConstraints": null,
"globalConstraint": null,
"wallets": [],
"phases": [],
"updated": "2024-05-07T22:37:44.566Z",
"created": "2024-05-07T22:37:44.566Z"
},
"secondsUntilDue": 0,
"currentPeriodStart": 1715121547,
"currentPeriodEnd": 1715121607,
"updated": "2024-05-27T16:00:01.317Z",
"created": "2024-05-07T22:37:57.521Z"
}
},
"ts": "2024-08-09T19:47:13.735Z",
"request": "request_57c8dfe36d8f496d92d50d4d3d42fb42"
}