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.
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 alineItem
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.
- Inactive
- 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 ofsol
,ethereum
,bitcoin
,polygon
,gnosis
,optimism
,arbitrum
,bsc
, orsepolia
.
- 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 theunitAmountDecimal
orunitAmount
field.tiered
sets a variable price per unit, defined by thetiers
andtierType
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 arecurring
price type. Defaults tooneTime
.
- Name
tierType
- Type
- enum
- Description
Defines how usage costs are calculated across different tiers. Requires
billingScheme
to be set totiered
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 totiered
, 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.
- Requires
- 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
toinf
in the final tier, the API will throw an error.
- The last defined tier covers the pricing for all potential usage indefinitely. If you don't set
- 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 apaymentLink
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
andunitAmountDecimal
.- 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
andsubscription.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
andsubscription.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
, oryear
.
- Name
intervalCount
- Type
- number
- Description
Defines the number of intervals between billing periods.
- E.g., with
"interval": "day"
andintervalCount: 2
, the customer is billed every 2 days. - The maximum total amount of time between billing periods is 5 years.
- E.g., with
- 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 isdelegated
(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.
- E.g., with
- 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
ormetered
.- If
licensed
is selected, then customers will based upon the quantity they specify upon checkout (price
xquantity
). - 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 asusageAggregation
andtier
inside theprice
object. - You will need to create
usageRecord
objects for each subscription customer periodically so we can appropriately bill them for their usage.
- If
- 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 aproduct
. - A
price
can only be attached to asingle
product at a time.
- It is recommended that you use this field upon creation of a price, although it is technically optional as you can pass in the
- 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"
}
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
orunitAmountDecimal
is required. IfunitAmount
is provided,unitAmountDecimal
will be calculated automatically.
- Either
- 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
orunitAmountDecimal
is required. IfunitAmountDecimal
is provided,unitAmount
will be calculated automatically.
- Either
- Name
network
- Type
- enum
- Description
The underlying network of your price, the network that your
currency
is native to. One ofsol
,ethereum
,bitcoin
,polygon
,gnosis
,optimism
,arbitrum
,bsc
, orsepolia
. Defaults tosol
.
- 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 aproduct
. - A
price
can only be attached to asingle
product at a time.
- It is recommended that you use this field upon creation of a price, although it is technically optional as you can pass in the
- 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 arecurring
price type. Defaults tooneTime
.
- 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 theunitAmountDecimal
orunitAmount
field.tiered
sets a variable price per unit, defined by thetiers
andtierType
fields.
- Name
customUnitAmount
- Type
- object
- Description
Allows customers to adjust the amount during checkout. Mutually exclusive with
unitAmount
andunitAmountDecimal
.- 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 totiered
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 totiered
, 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.
- Requires
- 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
toinf
in the final tier, the API will throw an error.
- The last defined tier covers the pricing for all potential usage indefinitely. If you don't set
- Name
recurring
- Type
- object
- Description
The recurring object defines the behavior of recurring payments. Required if the
type
of your price isrecurring
(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
andsubscription.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
andsubscription.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
, oryear
.
- Name
intervalCount
- Type
- number
- Description
Defines the number of intervals between billing periods.
- E.g., with
"interval": "day"
andintervalCount: 2
, the customer is billed every 2 days. - The maximum total amount of time between billing periods is 5 years.
- E.g., with
- 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
ormetered
. Defaults tolicensed
.- If
licensed
is selected, then customers will based upon the quantity they specify upon checkout (price
xquantity
). - 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 asusageAggregation
andtier
inside theprice
object. - You will need to create
usageRecord
objects for each subscription customer periodically so we can appropriately bill them for their usage.
- If
- 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 isdelegated
(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.
- E.g., with
- 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
curl https://api.spherepay.co/v1/price \
-H "Authorization: Bearer {token}" \
-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"
}
Retrieve a price
Retrieves a price
object by id
.
Request
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"
}
List all prices
Returns a list of your price
objects, sorted by newest creation date first.
Request
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"
}
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 theprice
that will be used to create the currency options group. The primary price.
- Name
currencyOptions
- Type
- string array
- Required
- Required
- Description
The
id
s of theprice
s that will be used to create the currency options group.
Request
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"
}