Create a price

post https://api.spherepay.co/v1/price

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

Log in to see full request history

Body Params

name

string

Name for the price, hidden from customers.

description

string

Description for the price, hidden from customers.

meta

object

Key/value pairs (JSON) for extra info on the object. Useful for external use.

product

string

The ID of the product that this price will point to. Created without a product by default.

type

string

Whether the price is for one-time or recurring (subscription) payments. Defaults to one-time.

currency

string

required

The public key, or name, of the underlying token, or fiat currency, for the price. Mint address on Solana, token contract address on EVM, or a string currency code (e.g. usd).

network

string

The underlying blockchain or fiat network that the price is associated with. Defaults to sol (Solana).

taxBehavior

string

Whether the price is inclusive of tax. Defaults to exclusive.

billingScheme

string

perUnit sets a fixed price per unit, defined by either unitAmountDecimal or unitAmount. tiered sets a variable price per unit, defined by the tiers and tierType fields.

unitAmount

string

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. Mutually exclusive with unitAmountDecimal.

unitAmountDecimal

number

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. Mutually exclusive with unitAmount.

tierType

string

The pricing model used for tiered subscriptions. Either graduated or volume. Requires billingScheme to be set to tiered and is null by default.

tiers

array of objects

List of tiers, where each element represents a different pricing tier. Requires billingScheme to be set to tiered and is null by default.

tiers

recurring

object

required

Response

`price` object.

Response body

object

id

string

required

Unique identifier for the price.

active

boolean

true activates the price, making it usable in products. false deactivates it. Changing this later affects only new resources, not existing ones.

name

string

Name for the price, hidden from customers.

description

string

Description for the price, hidden from customers.

meta

object

Key/value pairs (JSON) for extra info on the object. Useful for external use.

Has additional fields

network

string

The underlying blockchain or fiat network that the price is associated with. Defaults to sol (Solana).

localhost ethereum polygon optimism goerli sepolia mumbai optimism-goerli sol wire stripe

billingScheme

string

perUnit sets a fixed price per unit, defined by either unitAmountDecimal or unitAmount. tiered sets a variable price per unit, defined by the tiers and tierType fields.

perUnit tiered

taxBehavior

string

Whether the price is inclusive of tax. Defaults to exclusive.

inclusive exclusive unspecified

type

string

Whether the price is for one-time or recurring (subscription) payments. Defaults to one-time.

oneTime recurring

tierType

string

The pricing model used for tiered subscriptions. Either graduated or volume. Requires billingScheme to be set to tiered and is null by default.

graduated volume

tiers

array of objects

List of tiers, where each element represents a different pricing tier. Requires billingScheme to be set to tiered and is null by default.

tiers

object

flatAmount

string

flatAmountDecimal

number

unitAmount

string

unitAmountDecimal

number

upTo

object

Has additional fields

currency

string

required

The public key, or name, of the underlying token, or fiat currency, for the price. Mint address on Solana, token contract address on EVM, or a string currency code (e.g. usd).

unitAmount

string

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. Mutually exclusive with unitAmountDecimal.

unitAmountDecimal

number

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. Mutually exclusive with unitAmount.

recurring

object

required

type

string

Funding behavior for subscriptions from this price. Escrowed locks tokens into a smart contract, and requires pre-payment. Delegated uses approvals to bill directly from the customer's wallet.

escrowed delegated

interval

string

Sets billing frequency interval.

min month year week day

intervalCount

number

Sets gaps between billing periods. For example, 'week' and intervalCount: 5 means billing every 5 weeks. Max period is 5 years.

usageAggregation

string

Sets an aggregation method for calculating usage in a metered subscriptions. Choices: sum (total usage), latest (most recent usage), or max (highest usage in period). Defaults to sum.

sum latest maxUsage

usageType

string

Configures how the billable quantity per period should be determined. licensed bills based on the quantity set in the subscription's subscriptionItems. metered bills based on customer usage, which is submitted through usage records. Defaults to licensed.

licensed metered

defaultLength

number

The number of intervals (and interval count) that the customer will be subscribed to by default with a single transaction. Equivalently, defines the number of tokens that will be locked up in escrow or be approved for transfer by the customer upon subscription. For example, if interval is month, intervalCount is 2, and defaultLength is 12, then the customer will be prompted to either escrow or approve 24 months worth of tokens upon subscription.

usageDefaultQuantity

number

Required for metered subscriptions. The default quantity to prompt your customers for escrow or approval for. Suggested to use or estimate the median usage per period per customer.

updated

string

required

The last datetime the price was updated.

created

string

required

The datetime the price was created.

Language

Credentials

Bearer


xxxxxxxxxx
1
curl --request POST \
2
     --url https://api.spherepay.co/v1/price \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json'

Click Try It! to start a request and see the response here! Or choose an example:

application/json