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 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.

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

Was this page helpful?