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

Let's take a look at a full subscription object:

{
  "id": "subscription_d2e4fba4b9b44f39ada98f48ac6fab97",
  "amountApproved": "12500000",
  "amountApprovedDecimals": 12.50,
  "cancellation": {
    "cancelAt": null,
    "canceledAt": "2021-01-05T00:00:00.000Z",
    "reason": "cost",
    "feedback": "The service was too expensive"
  },
  "created": "2021-00-01T00:00:00.000Z",
  "currentPeriodStart": 1689387831,
  "currentPeriodEnd": 1689387831,
  "customer": "customer_e2e4fba4b9b44f39ada98f48ac6fab97",
  "description": "An example subscription for your customers",
  "ended": "2021-01-05T00:00:00.000Z",
  "fundingMethod": "delegated",
  "meta": {
    "uuid": "<your_uuid>"
  },
  "name": "Example Subscription",
  "network": "sol",
  "periodsBilled": 40,
  "status": "active",
  "subscriptionItems": [
    {
      "price": "subscriptionItem_e2e4fba4b9b44f39ada98f48ac6fab97",
      "quantity": 5
    },
    {
      "price": "subscriptionItem_a8e4fba4b9b44f39ada98f48ac6fab97",
      "quantity": 2
    }
  ],
  "updated": "2021-01-01T00:00:00.000Z"
}

id: string Unique identifier for the object. Auto-generated by Sphere upon creation.

amountApproved: number 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).

amountApprovedDecimals: number Identical to amountApproved, but with automatic conversion to base-10 (decimal) instead of the default unit amount for a given currency.

cancellation: object Contains important details about when a subscription gets cancelled.

cancelAt: string datetime for when the subscription is scheduled to be cancelled.
canceledAt: string datetime for when the subscription was cancelled.
reason: enum Why the subscription was cancelled.
feedback: string User feedback for why they cancelled.

created: string datetime for when the subscription was created.

currentPeriodStart: string datetime for the beginning of the current billing period.

currentPeriodEnd: string datetime for the end of the current billing period.

customer: string The id of the associated customer object.

description: string Describes your subscription. Hidden from users. Max length (500).

ended: string datetime for when the subscription ended.

meta: object 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: string The name of your subscription. Hidden from users. Max length (500).

network: enum The underlying network of your subscription. Either a blockchain abbreviation or fiat.

periodsBilled: number Identifies the number of billing periods that have been billed.

periodsRemaining: number Identifies the number of billing periods remaining.

status: enum Identifies the current status of the subscription.

subscriptionItems: subscriptionItem[] 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.

type: enum 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.

updated: string datetime for when the subscription was last updated.