Prices | ArcBlock

A Price object defines how much and how often to charge for a specific product. It associates a price amount and currency with a Product. For example, a product might have multiple prices, each in a different currency or with a different billing interval.

This document details how to manage Price objects using the SDK.

The Price Object

A Price object contains all the details about the pricing model for a product.

Attribute	Type	Description
`id`	string	Unique identifier for the price object.
`product_id`	string	The ID of the product this price is associated with.
`product`	object	The expanded Product object.
`active`	boolean	Whether the price can be used for new purchases.
`currency_id`	string	The ID of the default currency for this price.
`currency`	object	The expanded PaymentCurrency object.
`nickname`	string	A brief description of the price, displayed to customers.
`type`	string	One of `one_time` or `recurring`.
`unit_amount`	string	The price in the smallest currency unit (e.g., cents for USD).
`recurring`	object	For recurring prices, this hash contains billing interval information. See details below.
`lookup_key`	string	A unique, user-defined key to retrieve the price.
`metadata`	object	A set of key-value pairs that you can attach to an object.
`currency_options`	array	Specifies different pricing for multiple currencies.
`quantity_available`	number	The total available quantity for this price. `0` means unlimited.
`quantity_sold`	number	The number of units sold.
`quantity_limit_per_checkout`	number	The maximum quantity a customer can purchase in a single checkout. `0` means no limit.
`upsell`	object	Configuration for upselling to another price.

The recurring Object Properties

Attribute	Type	Description
`interval`	string	The frequency at which a subscription is billed. One of `day`, `week`, `month`, or `year`.
`interval_count`	number	The number of intervals between subscription billings.
`meter_id`	string	The ID of the meter used for usage-based billing.

Create a Price

Creates a new price for an existing product.

Create a Price

async function createPrice() {
  try {
    const price = await payment.prices.create({
      product_id: 'prod_xxxxxxxxxxxxxx',
      unit_amount: 1500, // e.g., $15.00
      currency_id: 'usd_xxxxxxxxxxxxxx',
      type: 'recurring',
      recurring: {
        interval: 'month',
        interval_count: 1,
        usage_type: 'licensed'
      },
      nickname: 'Monthly Pro Plan',
      lookup_key: 'pro_monthly_usd',
    });
    console.log('Price created:', price);
  } catch (error) {
    console.error('Error creating price:', error.message);
  }
}

createPrice();

Parameters

Name	Type	Description
`product_id`	string	Required. The ID of the product this price belongs to.
`unit_amount`	number	Required. The amount to be charged, in the smallest currency unit.
`currency_id`	string	Required. The ID of the currency for this price.
`type`	string	The type of pricing. Can be `one_time` or `recurring`. Defaults to `one_time`.
`active`	boolean	Whether the price is active. Defaults to `true`.
`nickname`	string	An internal name for the price.
`lookup_key`	string	A unique string to reference the price.
`recurring`	object	An object containing recurring billing information. Required if `type` is `recurring`.
`currency_options`	array	An array of objects to specify prices in different currencies.
`metadata`	object	Key-value data to store with the price.
`quantity_available`	number	The total available quantity. Defaults to `0` (unlimited).
`quantity_limit_per_checkout`	number	The maximum quantity per checkout. Defaults to `0` (no limit).

Returns

Returns the newly created Price object.

Response

{
  "id": "price_xxxxxxxxxxxxxx",
  "product_id": "prod_xxxxxxxxxxxxxx",
  "active": true,
  "currency_id": "usd_xxxxxxxxxxxxxx",
  "nickname": "Monthly Pro Plan",
  "type": "recurring",
  "unit_amount": "1500",
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "meter_id": null
  },
  "lookup_key": "pro_monthly_usd",
  "metadata": {},
  "product": {
    "id": "prod_xxxxxxxxxxxxxx",
    "name": "Pro Plan"
  },
  "currency": {
    "id": "usd_xxxxxxxxxxxxxx",
    "name": "United States Dollar"
  }
}

Retrieve a Price

Retrieves the details of an existing price.

Retrieve a Price

async function retrievePrice(priceId) {
  try {
    const price = await payment.prices.retrieve(priceId);
    console.log('Price retrieved:', price);
  } catch (error) {
    console.error('Error retrieving price:', error.message);
  }
}

retrievePrice('price_xxxxxxxxxxxxxx');

Parameters

Name	Type	Description
`id`	string	Required. The unique identifier of the price to retrieve. Can also be a `lookup_key`.

Returns

Returns the requested Price object.

Update a Price

Updates an existing price by setting the values of the parameters passed.

Update a Price

async function updatePrice(priceId) {
  try {
    const price = await payment.prices.update(priceId, {
      nickname: 'Updated Pro Plan Nickname',
      metadata: { order_id: '6735' },
    });
    console.log('Price updated:', price);
  } catch (error) {
    console.error('Error updating price:', error.message);
  }
}

updatePrice('price_xxxxxxxxxxxxxx');

Parameters

Name	Type	Description
`id`	string	Required. The ID of the price to update. Can also be a `lookup_key`.
`updates`	object	An object containing the fields to update. See the create method for a list of updatable fields. Note: Core attributes like `unit_amount` and `recurring` cannot be changed if the price has been used (`locked`).

Returns

Returns the updated Price object.

List all Prices

Returns a list of your prices. The prices are returned sorted by creation date, with the most recently created prices appearing first.

List Prices

async function listPrices() {
  try {
    const prices = await payment.prices.list({
      product_id: 'prod_xxxxxxxxxxxxxx',
      active: true,
      limit: 5,
    });
    console.log('Retrieved prices:', prices.list);
  } catch (error) {
    console.error('Error listing prices:', error.message);
  }
}

listPrices();

Parameters

Name	Type	Description
`active`	boolean	Only return prices with this active status.
`type`	string	Only return prices of this type, e.g., `recurring`.
`currency_id`	string	Only return prices for this currency ID.
`product_id`	string	Only return prices for this product ID.
`lookup_key`	string	Only return the price with this lookup key.
`page`	number	The page number for pagination. Defaults to `1`.
`pageSize`	number	The number of items per page. Defaults to `20`.

Returns

Returns a paginated object containing a list of Price objects, the total count, and paging information.

Search Prices

Searches for prices matching a query string.

Search Prices

async function searchPrices() {
  try {
    const prices = await payment.prices.search({ query: 'Pro Plan' });
    console.log('Search results:', prices.list);
  } catch (error) {
    console.error('Error searching prices:', error.message);
  }
}

searchPrices();

Parameters

Name	Type	Description
`query`	string	The search query string.
`page`	number	The page number for pagination. Defaults to `1`.
`pageSize`	number	The number of items per page. Defaults to `20`.

Returns

Returns a paginated object containing a list of matching Price objects.

Archive a Price

Archives a price, preventing it from being used in new checkouts. If a price has been used, it's generally better to archive it than to delete it.

Archive a Price

async function archivePrice(priceId) {
  try {
    const price = await payment.prices.archive(priceId);
    console.log('Price archived:', price.id, 'Active:', price.active);
  } catch (error) {
    console.error('Error archiving price:', error.message);
  }
}

archivePrice('price_xxxxxxxxxxxxxx');

Parameters

Name	Type	Description
`id`	string	Required. The ID of the price to archive. Can also be a `lookup_key`.

Returns

Returns the archived Price object with active set to false.

Delete a Price

Permanently deletes a price. This action cannot be undone. A price cannot be deleted if it has been used in a transaction or is otherwise locked.

Delete a Price

async function deletePrice(priceId) {
  try {
    const deletedPrice = await payment.prices.del(priceId);
    console.log('Price deleted:', deletedPrice.id);
  } catch (error) {
    console.error('Error deleting price:', error.message);
  }
}

deletePrice('price_xxxxxxxxxxxxxx');

Parameters

Name	Type	Description
`id`	string	Required. The ID of the price to delete. Can also be a `lookup_key`.

Returns

Returns the deleted Price object.

Update Inventory

Manually adjusts the quantity_sold for a price. This is useful for tracking inventory outside of the standard checkout flow.

Update Inventory

async function updateInventory(priceId) {
  try {
    // Increment sold quantity by 2
    const price = await payment.prices.inventory(priceId, {
      quantity: 2,
      action: 'increment',
    });
    console.log('Inventory updated. New quantity sold:', price.quantity_sold);
  } catch (error) {
    console.error('Error updating inventory:', error.message);
  }
}

updateInventory('price_xxxxxxxxxxxxxx');

Parameters

Name	Type	Description
`id`	string	Required. The ID of the price.
`params`	object	An object containing inventory adjustment details.

params Object Properties

Name	Type	Description
`quantity`	number	Required. The amount to adjust the sold quantity by.
`action`	string	Required. The adjustment action. Must be `increment` or `decrement`.

Returns

Returns the updated Price object with the new quantity_sold value.