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.

Endpoints

GET

/v1/subscription/:id

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 to pending on creation of the subscription (i.e., when someone clicks the pay button).
- incomplete: A subscription becomes incomplete if the intial payment attempt fails.
- active: A subscription becomes active once we detect that the customer has escrowed/delegated the required amount of tokens on-chain.
- pastDue: A subscription moves to pastDue 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 to canceled if it is pastDue 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 for delegated 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 each price must be recurring.
- Relevant for metered billing, because you will need to include each relevant subscriptionItem object id when creating or updating a usageRecord to correctly bill for usage.
- Name
  id
  Type
  string
  Description
  Unique identifier for the subscription item. Auto-generated by Sphere upon creation.
- 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, or customerHasCancelled.
- 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"
  }

GET/v1/payment/:id

Retrieve a subscription

Retrieves a subscription object by id.

Request

GET

/v1/susbcription/:id

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"
}