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

Was this page helpful?