Prices
Use this reference for exact request attributes, response envelopes, object shape, and examples. For catalog modeling, product-price relationships, and selling patterns, start with Manage your product catalog.
Price and product IDs from another application are treated as unavailable. Use the response error code rather than the HTTP status alone when choosing a recovery path.
The price object
A price object captures a specific monetary amount in a single currency, with optional metadata for display and organization. Prices can be associated with a product or exist independently. Each price also exposes whether it is currently active for new flows. The amount is set at creation and cannot be modified afterward—this immutability ensures that historical orders always reference the exact price that was charged.
Properties
- Name
about- Type
string | null- Description
Optional description of what this price represents. Max 500 characters.
- Name
active- Type
boolean- Description
Whether this price is active and can be used in new flows. Newly created prices are active by default. Deactivated prices remain available through lookup and pagination but are rejected by new catalog-price selections.
- Name
archivedAt- Type
Date | null- Description
When this price was permanently retired. Omitted otherwise. Archiving also sets
activetofalse, and archived prices cannot be reactivated.
- Name
createdAt- Type
Date- Description
When this price was first created. Set automatically and never changes.
- Name
id- Type
string- Description
Unique identifier for this price, generated automatically during creation.
- Name
label- Type
string | null- Description
Optional short name for distinguishing prices. Max 100 characters. Examples:
Monthly,Enterprise Annual,One-time setup.
productProduct | nullClick or tap to expandThe related product, when the price is attached to one. Omitted for a standalone price. The related product omits the full
pricescollection.- Name
updatedAt- Type
Date | null- Description
Last time this price was modified. Omitted if it has not been updated.
Create a price
Create an active fixed price, or a customer-selected price for an eligible product. The price definition and product relationship are immutable after creation—if either needs to change, create a replacement price and retire the old one.
Send "fixed_amount" with fixedAmount, or "customer_selected_amount" with customerSelectedAmount. Do not send both definitions. Customer-selected prices require productId and are available only where enabled. If you provide a product ID, choose an existing product from your catalog. This endpoint currently permits attachment to an archived product and still creates the price as active; price eligibility does not consult the product's archive state. Monetary values use the currency's smallest unit, and currency codes are normalized to lowercase.
Request attributes
- Name
about- Type
string- Description
Description of the price. Max 500 characters.
customerSelectedAmountCustomerSelectedAmountParamsSelection policy required whentypeis"customer_selected_amount".Click or tap to expand- Name
currency- Type
AmountParams['currency']- Required
- required
- Description
- Currency accepted from the customer.
- Name
minimum- Type
number- Required
- required
- Description
- Smallest amount the customer may enter. Must be at least 1.
- Name
maximum- Type
number- Description
- Optional largest amount the customer may enter. Must be at least the minimum.
- Name
suggestedAmounts- Type
SuggestedAmountParams[]- Description
- Optional convenient choices. IDs and values must be unique, and at most one suggestion may be recommended.
fixedAmountAmountParamsAmount required whentypeis"fixed_amount".Click or tap to expand- Name
label- Type
string- Description
Short display name. Max 100 characters.
- Name
productId- Type
string- Description
Permanently associate the price with an existing product in your catalog. Required for customer-selected prices; optional for fixed prices.
- Name
type- Type
'fixed_amount' | 'customer_selected_amount'- Required
- required
- Description
Price definition. Use
"fixed_amount"or"customer_selected_amount".
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.prices.create({
type: "fixed_amount",
fixedAmount: {
currency: "usd",
value: 2999,
},
label: "Monthly",
about: "Standard monthly subscription price",
productId: "prod_abc123xyz789",
})
Archive a price
Permanently retire a price. Archiving sets active to false, records archivedAt, and advances updatedAt. The amount, optional product relationship, and historical order snapshots remain unchanged.
Archived prices remain available through lookup and pagination but cannot be activated or selected by new catalog-priced order and purchase-intent flows. An already-archived price returns a lifecycle conflict; create a new price if you later need the same amount again.
Request attributes
- Name
priceId- Type
string- Required
- required
- Description
Identifier of the price to archive.
Request
- cURL
- SDK coverage
curl https://api.inttegro.com/prices/archive \
-H "Authorization: Bearer $INTTEGRO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: archive-price-pr_k8m2x9v4n7p1" \
-d '{"price_id":"pr_k8m2x9v4n7p1"}'
Official SDK coverage for POST /prices/archive is pending.
Add this operation to the checked-in SDKs before publishing a runnable sample here.
Response
- Object
- JSON
PriceResponse {
price: { … },
}
{
"price": {
"id": "pr_k8m2x9v4n7p1",
"about": "Standard monthly subscription price",
"active": false,
"archived_at": "2026-03-01T09:00:00Z",
"created_at": "2026-02-13T02:00:00Z",
"label": "Monthly",
"nominal": { … },
"product": { … },
"updated_at": "2026-03-01T09:00:00Z"
}
}
Lookup a price
Retrieve an existing price by its ID. Active, inactive, and archived prices can all be read. The response includes the immutable nominal amount, any associated product snapshot, and lifecycle timestamps; a standalone price omits product.
AI clients can use get_price for this operation. MCP read tools return minimized business data and do not change Inttegro state.
Request attributes
- Name
priceId- Type
string- Required
- required
- Description
The ID of the price to retrieve.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.prices.lookup({
priceId: "pr_k8m2x9v4n7p1",
})
Page through prices
Retrieve a paginated list of your prices. Results are sorted from newest to oldest, so page 1 contains the most recently created prices.
If you provide productId, the page is scoped to prices belonging to that product only. This includes active, inactive, and archived prices, which lets you inspect the full pricing history for a product or for your broader catalog.
AI clients can use list_prices for this operation. MCP read tools return minimized business data and do not change Inttegro state.
Request attributes
- Name
pageNumber- Type
number- Description
1-based page index to fetch. Defaults to
1when omitted.
- Name
pageSize- Type
number- Description
Number of prices to return. Defaults to
256. Must be between1and256.
- Name
productId- Type
string- Description
Optional product ID to scope the results to a single product.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.prices.page({
pageNumber: 1,
pageSize: 2,
productId: "prod_abc123xyz789",
})
Update a price
Update an existing price's descriptive fields. Only about and label are mutable. The product association and nominal amount remain fixed after creation, so create a new price when either needs to change.
Do not send amount or product_id: they are not supported updates. Updating an archived price's descriptive fields is currently allowed and does not reactivate it. Sending no changed descriptive fields returns the current price without advancing updatedAt.
Request attributes
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.prices.update({
priceId: "pr_k8m2x9v4n7p1",
label: "Monthly (discounted)",
about: "Promotional monthly rate for early adopters",
})
Response
- Object
- JSON
PriceResponse {
price: { … },
}
{
"price": {
"id": "pr_k8m2x9v4n7p1",
"about": "Promotional monthly rate for early adopters",
"active": true,
"nominal": { … },
"created_at": "2026-02-13T02:00:00Z",
"label": "Monthly (discounted)",
"product": { … },
"updated_at": "2026-02-13T03:00:00Z"
}
}
Activate a price
Reactivate a previously deactivated price so it can be selected by new catalog-priced order and purchase-intent flows. Activation does not change the amount or product association; it sets active to true and advances updatedAt.
Archived prices cannot be activated, and an already-active price returns a lifecycle conflict.
Request attributes
- Name
priceId- Type
string- Required
- required
- Description
Price identifier to activate.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.prices.activate({
priceId: "pr_k8m2x9v4n7p1",
})
Response
- Object
- JSON
PriceResponse {
price: { … },
}
{
"price": {
"id": "pr_k8m2x9v4n7p1",
"about": "Standard monthly subscription price",
"active": true,
"nominal": { … },
"created_at": "2026-02-13T02:00:00Z",
"label": "Monthly",
"product": { … },
"updated_at": "2026-02-13T04:10:00Z"
}
}
Deactivate a price
Deactivate a price so it is rejected by new catalog-priced order and purchase-intent flows. This is the reversible alternative to archiving: the price remains visible through lookup and pagination and can be reactivated later.
Deactivation only affects future selections. Existing orders that already reference the price keep their recorded amount. Archived and already-inactive prices return lifecycle conflicts.
Request attributes
- Name
priceId- Type
string- Required
- required
- Description
Price identifier to deactivate.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.prices.deactivate({
priceId: "pr_k8m2x9v4n7p1",
})
Response
- Object
- JSON
PriceResponse {
price: { … },
}
{
"price": {
"id": "pr_k8m2x9v4n7p1",
"about": "Standard monthly subscription price",
"active": false,
"nominal": { … },
"created_at": "2026-02-13T02:00:00Z",
"label": "Monthly",
"product": { … },
"updated_at": "2026-02-13T04:20:00Z"
}
}