Prices

Once you have created a product, next you will need to create a price.

The price points to a specific product and will set how much that product costs, as well as important details like whether that product is paid for on a one-time or recurring (subscription) basis, and if pricing is tiered.

Endpoints

POST

The Price object

Properties

Name
id
Type
string
Description
A unique identifier for the object.
Name
active
Type
boolean
Description
Denotes whether your price is usable in new payment methods.
- Inactive price objects passed as a lineItem to a payment method will return an API error.
- Pre-existing payment methods with a newly inactive price will continue to function. Recommended to update the payment method directly to make it inactive or remove specific line items.
Name
name
Type
string
Description
The name of your price. Hidden from customers. Max length (500).
Name
description
Type
string
Description
The description of your price. Hidden from users. Max length (500).
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.
Name
network
Type
enum
Description
The underlying network of your price, the network that your currency is native to. One of sol, ethereum, bitcoin, polygon, gnosis, optimism, arbitrum, bsc, or sepolia.
Name
billingScheme
Type
enum
Description
Defines how the total cost of the price will be calculated.
- perUnit sets a fixed price per unit, defined by either the unitAmountDecimal or unitAmount field.
- tiered sets a variable price per unit, defined by the tiers and tierType fields.
Name
taxBehavior
Type
enum
Description
Identifies whether the price is inclusive or exclusive of taxes.
- inclusive: Your price includes taxes
  - E.g., a tax inclusive price of $10 could mean the "true" value of the product is $9, with a tax of $1.
- exclusive: Your price does not include taxes
  - E.g., a tax exclusive price of $10 means that the "true" value of the product is $10.
- Note: this field is primarily intended for your own accounting purposes. Sphere's billing engine will apply whatever taxRate is defined to tax exclusive products during payment.
Name
type
Type
enum
Description
Defines whether the product the price is attached to is paid for on a one-time or on a recurring basis (subscription). The recurring field defines the behavior of a price for a recurring price type. Defaults to oneTime.
Name
tierType
Type
enum
Description
Defines how usage costs are calculated across different tiers. Requires billingScheme to be set to tiered and is null by default.
- Graduated billing sums up the cost of usage as you go up tiers.
- Whereas volume based billing will assume the most recent tier that was reached.
Name
tiers
Type
object array
Description
List of tiers, where each element represents a different pricing tier. Defines details in your pricing model.
- Requires billingScheme to be set to tiered, otherwise it'll produce an error.
- The non-decimal sub-fields contain the same information as the decimal sub-fields, but just presented as the raw default integer value of a token.
- The algorithm for total billing will depend on the tier type.
- Name
  index
  Type
  number
  Description
  The order of the tier. Starts at 1.
- Name
  flatAmount
  Type
  string
  Description
  The flat cost for usage in a given tier.
- Name
  flatAmountDecimal
  Type
  number
  Description
  The flat cost for usage in a given tier. Formatted to base-10.
- Name
  unitAmount
  Type
  string
  Description
  Defines the default cost of your price.
- Name
  unitAmountDecimal
  Type
  number
  Description
  Defines the default cost of your price, automatically converting the amount of raw token units for a given currency into base-10 (decimal) instead of the default unit amount for a given currency.
- Name
  upTo
  Type
  number
  Description
  Defines the number of units of usage that the given tier goes up to.
  
  The last defined tier covers the pricing for all potential usage indefinitely. If you don't set upTo to inf in the final tier, the API will throw an error.
- Name
  updated
  Type
  string
  Description
  Datetime for when the tier was last updated.
- Name
  created
  Type
  string
  Description
  Datetime for when the tier was created.
Name
currencyOptions
Type
string array
Description
List of price ids. Useful for when you want to create a paymentLink with multiple networks.
Name
currency
Type
string
Description
Defines the underlying token the price is associated with. The public key for the mint address (Solana) or token contract address (EVM).
Name
unitAmount
Type
string
Description
The raw cost of the price, denominated in the specified currency. A non-negative integer in raw token decimals. For example, to charge 5 USDC, use 5_000_000 (5*10^6) since the the number of token decimals of USDC is 6.
Name
unitAmountDecimal
Type
number
Description
The decimal adjusted cost of the price, denominated in the specified currency. A non-negative integer in base-10. For example, to charge 5 USDC, use 5.
Name
customUnitAmount
Type
object
Description
Allows customers to adjust the amount during checkout. Mutually exclusive to unitAmount and unitAmountDecimal.
- Name
  presets
  Type
  number array
  Description
  A list of preset amounts for the custom unit amount. The presets are the decimal adjusted cost of the custom unit amount.
Name
recurring
Type
object
Description
Defines the behavior of recurring payments. Relevant if the type of your price is recurring (e.g., a subscription).
- Name
  type
  Type
  enum
  Description
  Defines whether the customer pays for the subscription by pre-funding an escrow account (escrowed), or approving automatic withdrawals from their wallet (delegated).
  
  escrowed: Customers lock up funds dedicated to the subscription in an escrow account. Each billing period, funds will be withdrawn from that account.
  
  Customers can withdraw at anytime through the subscription management portal. You can also use the withdraw escrow funds endpoint to serve the transaction on your own frontend.
  
  Similarly, customers may top-off their escrow account either through the subscription management portal or your own frontend via the add escrow funds endpoint.
  
  We suggest listening for the subscription.escrowed.low_balance and subscription.escrowed.insufficient events to appropriately notify your customers.
  
  delegated: Customers approve to have funds automatically drawn from their wallet at the end of each billing period. If there are insufficient funds, the subscription is voided.
  
  Customers may revoke delegation in the subscription management portal. You can also use the revoke delegation endpoint to serve the transaction on your own frontend.
  
  Similarly, customers may approve for additional tokens to be delegated either through the subscription management portal or your own frontend via the extend delegation endpoint.
  
  We suggest listening for the subscription.delegated.insufficient and subscription.delegated.redelegated events to appropriately notify your customers.
- Name
  interval
  Type
  enum
  Description
  Defines the frequency of each billing period. One of min, day, week, month, or year.
- Name
  intervalCount
  Type
  number
  Description
  Defines the number of intervals between billing periods.
  
  E.g., with "interval": "day" and intervalCount: 2, the customer is billed every 2 days.
  
  The maximum total amount of time between billing periods is 5 years.
- Name
  defaultLength
  Type
  number
  Description
  Defines the number of billing periods. If your subscription's billing scheme is escrowed, then this defines the number of billing cycles the customer will pre-pay at checkout. If it is delegated (e.g., escrowless), then this defines the number of billing cycles the customer will be prompted to approve token transfers for.
  
  E.g., with "type": "delegated", "defaultLength": 3, and "interval": "month", the customer will be prompted to approve the delegation of tokens equal to the amount of 3 months of billing upon subscribing.
- Name
  usageAggregation
  Type
  enum
  Description
  Defines how usage for metered billing is calculated.
  
  sum: The customer will be billed for the sum of their usage over the current billing period.
  
  latest: The customer will be billed for the latest reported usage, irrespective of billing period.
  
  max: The customer will be billed for the maximum of their usage over the current billing period.
- Name
  usageType
  Type
  enum
  Description
  Defines whether your billing is licensed or metered.
  
  If licensed is selected, then customers will based upon the quantity they specify upon checkout (price x quantity).
  
  If metered is selected, then customers will be billed based on their usage.
  
  This is calculated on your backend and passed to Sphere through the usageRecords object, with the exact details for pricing, such as the underlying pricing model, being defined by fields such as usageAggregation and tier inside the price object.
  
  You will need to create usageRecord objects for each subscription customer periodically so we can appropriately bill them for their usage.
- Name
  expectedUsagePerInterval
  Type
  number
  Description
  The amount of units you expect your customers to use on average per interval. Relevant if your subscription's billing scheme is metered.
Name
product
Type
string
Description
The id of the product object to connect this price to.
- It is recommended that you use this field upon creation of a price, although it is technically optional as you can pass in the price id when creating a product.
- A price can only be attached to a single product at a time.
Name
updated
Type
string
Description
Datetime for when the price was last updated.
Name
created
Type
timestamp
Description
Datetime for when the price was created.

Price Object

{
  "id": "price_3b15ec6ae6734d7687e7a4ac09326608",
  "active": true,
  "name": null,
  "description": null,
  "meta": {},
  "network": "sol",
  "billingScheme": "perUnit",
  "taxBehavior": "exclusive",
  "type": "oneTime",
  "tierType": null,
  "tiers": [],
  "currencyOptions": [],
  "currency": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "unitAmount": "10000000",
  "unitAmountDecimal": 10,
  "customUnitAmount": null,
  "recurring": {
    "type": null,
    "usageAggregation": null,
    "interval": null,
    "intervalCount": null,
    "usageType": null,
    "defaultLength": null,
    "expectedUsagePerInterval": null
  },
  "product": "product_a65d51a2f2134bfc96326f40734d486f",
  "updated": "2024-08-09T22:44:44.547Z",
  "created": "2024-08-09T22:44:44.547Z"
}

POST/v1/price

Create a price

Creates a new price object that points to a product. Set type to recurring for subscriptions.

Parameters

Name
curency
Type
string
Required
Required
Description
Defines the underlying token the price is associated with. The public key for the mint address (Solana) or token contract address (EVM).
Name
unitAmount
Type
string
Required
Required
Description
The raw cost of the price, denominated in the specified currency. A non-negative integer in raw token decimals. For example, to charge 5 USDC, use 5_000_000 (5*10^6) since the the number of token decimals of USDC is 6.
- Either unitAmount or unitAmountDecimal is required. If unitAmount is provided, unitAmountDecimal will be calculated automatically.
Name
unitAmountDecimal
Type
number
Required
Required
Description
The decimal adjusted cost of the price, denominated in the specified currency. A non-negative integer in base-10. For example, to charge 5 USDC, use 5.
- Either unitAmount or unitAmountDecimal is required. If unitAmountDecimal is provided, unitAmount will be calculated automatically.
Name
network
Type
enum
Description
The underlying network of your price, the network that your currency is native to. One of sol, ethereum, bitcoin, polygon, gnosis, optimism, arbitrum, bsc, or sepolia. Defaults to sol.
Name
name
Type
string
Description
The name of your price. Hidden from customers. Max length (500).
Name
description
Type
string
Description
The description of your price. Hidden from users. Max length (500).
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.
Name
product
Type
string
Description
The id of the product object to connect this price to.
- It is recommended that you use this field upon creation of a price, although it is technically optional as you can pass in the price id when creating a product.
- A price can only be attached to a single product at a time.
Name
type
Type
enum
Description
Defines whether the product the price is attached to is paid for on a one-time or on a recurring basis (subscription). The recurring field defines the behavior of a price for a recurring price type. Defaults to oneTime.
Name
taxBehavior
Type
enum
Description
Identifies whether the price is inclusive or exclusive of taxes.
- inclusive: Your price includes taxes
  - E.g., a tax inclusive price of $10 could mean the "true" value of the product is $9, with a tax of $1.
- exclusive: Your price does not include taxes
  - E.g., a tax exclusive price of $10 means that the "true" value of the product is $10.
- Note: this field is primarily intended for your own accounting purposes. Sphere's billing engine will apply whatever taxRate is defined to tax exclusive products during payment.
Name
billingScheme
Type
enum
Description
Defines how the total cost of the price will be calculated.
- perUnit sets a fixed price per unit, defined by either the unitAmountDecimal or unitAmount field.
- tiered sets a variable price per unit, defined by the tiers and tierType fields.
Name
customUnitAmount
Type
object
Description
Allows customers to adjust the amount during checkout. Mutually exclusive with unitAmount and unitAmountDecimal.
- Name
  presets
  Type
  number array
  Description
  A list of preset amounts for the custom unit amount. The presets are the decimal adjusted cost of the custom unit amount.
Name
tierType
Type
enum
Description
Defines how usage costs are calculated across different tiers. Requires billingScheme to be set to tiered and is null by default.
- Graduated billing sums up the cost of usage as you go up tiers.
- Whereas volume based billing will assume the most recent tier that was reached.
Name
tiers
Type
object array
Description
List of tiers, where each element represents a different pricing tier. Defines details in your pricing model.
- Requires billingScheme to be set to tiered, otherwise it'll produce an error.
- The non-decimal sub-fields contain the same information as the decimal sub-fields, but just presented as the raw default integer value of a token.
- The algorithm for total billing will depend on the tier type.
- Name
  flatAmount
  Type
  string
  Description
  The flat cost for usage in a given tier.
- Name
  flatAmountDecimal
  Type
  number
  Description
  The flat cost for usage in a given tier. Formatted to base-10.
- Name
  unitAmount
  Type
  string
  Description
  Defines the default cost of your price.
- Name
  unitAmountDecimal
  Type
  number
  Description
  Defines the default cost of your price, automatically converting the amount of raw token units for a given currency into base-10 (decimals).
- Name
  upTo
  Type
  number
  Description
  Defines the number of units of usage that the given tier goes up to.
  
  The last defined tier covers the pricing for all potential usage indefinitely. If you don't set upTo to inf in the final tier, the API will throw an error.
Name
recurring
Type
object
Description
The recurring object defines the behavior of recurring payments. Required if the type of your price is recurring (e.g., a subscription).
- Name
  type
  Type
  enum
  Description
  Defines whether the customer pays for the subscription by pre-funding an escrow account (escrowed), or approving automatic withdrawals from their wallet (delegated).
  
  escrowed: Customers lock up funds dedicated to the subscription in an escrow account. Each billing period, funds will be withdrawn from that account.
  
  Customers can withdraw at anytime through the subscription management portal. You can also use the withdraw escrow funds endpoint to serve the transaction on your own frontend.
  
  Similarly, customers may top-off their escrow account either through the subscription management portal or your own frontend via the add escrow funds endpoint.
  
  We suggest listening for the subscription.escrowed.low_balance and subscription.escrowed.insufficient events to appropriately notify your customers.
  
  delegated: Customers approve to have funds automatically drawn from their wallet at the end of each billing period. If there are insufficient funds, the subscription is voided.
  
  Customers may revoke delegation in the subscription management portal. You can also use the revoke delegation endpoint to serve the transaction on your own frontend.
  
  Similarly, customers may approve for additional tokens to be delegated either through the subscription management portal or your own frontend via the extend delegation endpoint.
  
  We suggest listening for the subscription.delegated.insufficient and subscription.delegated.redelegated events to appropriately notify your customers.
- Name
  interval
  Type
  enum
  Description
  Defines the frequency of each billing period. One of min, day, week, month, or year.
- Name
  intervalCount
  Type
  number
  Description
  Defines the number of intervals between billing periods.
  
  E.g., with "interval": "day" and intervalCount: 2, the customer is billed every 2 days.
  
  The maximum total amount of time between billing periods is 5 years.
- Name
  usageAggregation
  Type
  enum
  Description
  Defines how usage for metered billing is calculated.
  
  sum: The customer will be billed for the sum of their usage over the current billing period. (total usage)
  
  latest: The customer will be billed for the latest reported usage, irrespective of billing period. (most recent usage)
  
  max: The customer will be billed for the maximum of their usage over the current billing period. (highest usage in period)
- Name
  usageType
  Type
  enum
  Description
  Defines whether your billing is licensed or metered. Defaults to licensed.
  
  If licensed is selected, then customers will based upon the quantity they specify upon checkout (price x quantity).
  
  If metered is selected, then customers will be billed based on their usage.
  
  This is calculated on your backend and passed to Sphere through the usageRecords object, with the exact details for pricing, such as the underlying pricing model, being defined by fields such as usageAggregation and tier inside the price object.
  
  You will need to create usageRecord objects for each subscription customer periodically so we can appropriately bill them for their usage.
- Name
  defaultLength
  Type
  number
  Description
  Defines the number of billing periods. If your subscription's billing scheme is escrowed, then this defines the number of billing cycles the customer will pre-pay at checkout. If it is delegated (e.g., escrowless), then this defines the number of billing cycles the customer will be prompted to approve token transfers for.
  
  E.g., with "type": "delegated", "defaultLength": 3, and "interval": "month", the customer will be prompted to approve the delegation of tokens equal to the amount of 3 months of billing upon subscribing.
- Name
  expectedUsagePerInterval
  Type
  number
  Description
  The amount of units you expect your customers to use on average per interval. Required if your subscription's billing scheme is metered.

Request

POST

/v1/price

curl https://api.spherepay.co/v1/price \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "network": "sol",
    "unitAmountDecimal": "10",
    "product": "product_a65d51a2f2134bfc96326f40734d486f"
  }'

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "price": {
      "id": "price_3b15ec6ae6734d7687e7a4ac09326608",
      "active": true,
      "name": null,
      "description": null,
      "meta": {},
      "network": "sol",
      "billingScheme": "perUnit",
      "taxBehavior": "exclusive",
      "type": "oneTime",
      "tierType": null,
      "tiers": [],
      "currencyOptions": [],
      "currency": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "unitAmount": "10000000",
      "unitAmountDecimal": 10,
      "customUnitAmount": null,
      "recurring": {
        "type": null,
        "usageAggregation": null,
        "interval": null,
        "intervalCount": null,
        "usageType": null,
        "defaultLength": null,
        "expectedUsagePerInterval": null
      },
      "product": "product_a65d51a2f2134bfc96326f40734d486f",
      "updated": "2024-08-09T22:44:44.547Z",
      "created": "2024-08-09T22:44:44.547Z"
    }
  },
  "ts": "2024-08-09T22:44:44.557Z",
  "request": "request_411734a5208643f1849574e2324d24c6"
}

GET/v1/price/:id

Retrieve a price

Retrieves a price object by id.

Request

GET

/v1/price/:id

curl https://api.spherepay.co/v1/price/price_6e65113b72e74b349222da1532f2e4ce \
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "price": {
      "id": "price_6e65113b72e74b349222da1532f2e4ce",
      "active": true,
      "name": null,
      "description": null,
      "meta": {},
      "network": "sol",
      "billingScheme": "perUnit",
      "taxBehavior": "exclusive",
      "type": "oneTime",
      "tierType": null,
      "tiers": [],
      "currencyOptions": [],
      "currency": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "unitAmount": "1000000",
      "unitAmountDecimal": 1,
      "customUnitAmount": null,
      "recurring": {
        "type": null,
        "usageAggregation": null,
        "interval": null,
        "intervalCount": null,
        "usageType": null,
        "defaultLength": null,
        "expectedUsagePerInterval": null
      },
      "product": "product_52b9a8078bb54e918dfe2fd417a0cb14",
      "updated": "2024-01-22T07:09:56.911Z",
      "created": "2024-01-22T07:09:55.555Z"
    }
  },
  "ts": "2024-08-10T12:03:53.504Z",
  "request": "request_d90066758eaa41ee88491d7c650628e9"
}

GET/v1/price

List all prices

Returns a list of your price objects, sorted by newest creation date first.

Request

GET

/v1/price

curl -G https://api.spherepay.co/v1/price \
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "prices": [
      {
        "id": "price_6e65113b72e74b349222da1532f2e4ce",
        "active": true,
        "name": null,
        "description": null,
        "meta": {},
        "network": "sol",
        "billingScheme": "perUnit",
        "taxBehavior": "exclusive",
        "type": "oneTime",
        "tierType": null,
        "tiers": [],
        "currencyOptions": [],
        "currency": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "unitAmount": "1000000",
        "unitAmountDecimal": 1,
        "customUnitAmount": null,
        "recurring": {
          "type": null,
          "usageAggregation": null,
          "interval": null,
          "intervalCount": null,
          "usageType": null,
          "defaultLength": null,
          "expectedUsagePerInterval": null
        },
        "product": "product_52b9a8078bb54e918dfe2fd417a0cb14",
        "updated": "2024-01-22T07:09:56.911Z",
        "created": "2024-01-22T07:09:55.555Z"
      },
      {
        "id": "price_a6eadf02cd5c45e89bc3a970ae9eea73",
        // ...
      }
    ]
  },
  "ts": "2024-08-10T12:02:46.829Z",
  "request": "request_9b9dab09a4ca4ec8a45eee1ef0432ab3"
}

GET/v1/price/createCurrencyOptionsGroup

Create a currency option group

Creates a new currencyOption object for a given price. Currency options are useful for when you want to create a paymentLink with multiple networks.

Parameters

Name
mainPriceId
Type
string
Required
Required
Description
The id of the price that will be used to create the currency options group. The primary price.
Name
currencyOptions
Type
string array
Required
Required
Description
The ids of the prices that will be used to create the currency options group.

Request

GET

/v1/price

curl -G https://api.spherepay.co/v1/price/createCurrencyOptionsGroup \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d "{
    \"mainPriceId\": \"price_6ed08ebf6e1e44008b6a980adb73cf21\",
    \"currencyOptions\": [
      \"price_7c4cf8c32d2347b19346cebc50c2a792\"
    ]
  }"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "price": {
      "id": "price_6ed08ebf6e1e44008b6a980adb73cf21",
      "active": true,
      "name": null,
      "description": null,
      "meta": {},
      "network": "ethereum",
      "billingScheme": "perUnit",
      "taxBehavior": "exclusive",
      "type": "oneTime",
      "tierType": null,
      "tiers": [],
      "currencyOptions": ["price_7c4cf8c32d2347b19346cebc50c2a792"],
      "currency": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "unitAmount": "1000000",
      "unitAmountDecimal": 1,
      "customUnitAmount": null,
      "recurring": {
        "type": null,
        "usageAggregation": null,
        "interval": null,
        "intervalCount": null,
        "usageType": null,
        "defaultLength": null,
        "expectedUsagePerInterval": null
      },
      "product": "product_f7a97f243c354281b32d232401cade4e",
      "updated": "2024-08-13T16:32:09.581Z",
      "created": "2024-08-13T16:30:37.951Z"
    }
  },
  "ts": "2024-08-13T16:32:09.594Z",
  "request": "request_c64d032b4cd44083956ca4986f6ca8f4"
}