Purchase intents
Purchase intents power Buy links: share a product offer and let Inttegro handle the customer-facing checkout. Use this API to create the link, change its quantity or availability, and stop it.
The API returns a sale_... ID. Append it to https://pages.inttegro.com/buy/ to create the customer-facing URL. For the complete sales flow, see the Purchase intents product guide.
The purchase intent object
A purchase intent contains the offer shown at checkout: its product, price, quantity limits, availability, and usage policy. Its status changes automatically when the link expires, is canceled, or uses its single allowed purchase.
Properties
- Name
allowVariants- Type
boolean- Required
- required
- Description
Whether the offer uses a variant set. When
variantSetis present, checkout can offer its active, available variants.
- Name
createdAt- Type
Date- Required
- required
- Description
When the purchase intent was created.
- Name
expiresAt- Type
Date- Description
Optional timestamp after which the Buy link stops accepting new purchases. Expiry is effective at the timestamp itself.
- Name
id- Type
string- Required
- required
- Description
Unique purchase intent identifier with the
sale_prefix.
- Name
inactiveAt- Type
Date- Description
When the merchant explicitly inactivated the Buy link. When this is set, the intent is unavailable even if
expiresAtis still in the future.
merchantPurchaseIntentMerchantBusiness identity shown in the hosted checkout. Individual fields are omitted when unavailable.Click or tap to expand- Name
appName- Type
string- Description
- Human-readable application name.
- Name
organizationId- Type
string- Description
- Organization that owns the application.
- Name
organizationName- Type
string- Description
- Human-readable organization name.
pricePurchaseIntentPriceResolved price used for the offer. Amounts use integer minor units.Click or tap to expand- Name
active- Type
boolean- Required
- required
- Description
- Whether the resolved price can be used.
- Name
id- Type
string- Description
- Catalog price identifier when the offer uses a stored price.
- Name
label- Type
string- Description
- Catalog price label when available.
View original attributesClick or tap to expand
Optional comparison price shown alongside the amount charged.
presentationPurchaseIntentPresentationMerchant-authored Buy-page copy. Omitted fields continue to use product-aware defaults.Click or tap to expandproductPurchaseIntentProductCurrent catalog product rendered by the hosted checkout.Click or tap to expand- Name
about- Type
string- Description
- Full product description.
- Name
active- Type
boolean- Required
- required
- Description
- Whether the product is published and available.
- Name
archivedAt- Type
Date | null- Description
- When the product was archived.
- Name
category- Type
string- Description
- Product category.
- Name
createdAt- Type
Date- Required
- required
- Description
- When the product was created.
- Name
customData- Type
Readonly<Record<string, string>>
View custom_data detailsClick or tap to expand
Product metadata, returned as string values.- Name
description- Type
string- Description
- Short product description.
View dimensions attributesClick or tap to expand
Physical, digital, or custom size information.- Name
custom- Type
ProductCustomDimensions
- Name
digital- Type
ProductDigitalDimensions
View physical attributesClick or tap to expand
Physical measurements.- Name
height- Type
number- Description
- Product height.
- Name
length- Type
number- Description
- Product length.
- Name
volume- Type
number- Description
- Product volume.
- Name
volumeUnit- Type
string- Description
- Unit used for volume.
- Name
weight- Type
number- Description
- Product weight.
- Name
weightUnit- Type
string- Description
- Unit used for weight.
- Name
width- Type
number- Description
- Product width.
- Name
id- Type
string- Required
- required
- Description
- Unique product identifier with the
prod_prefix.
- Name
media- Type
ProductMedia | null
View media attributesClick or tap to expand
Product media shown during browsing and checkout.- Name
brandLogo- Type
string- Description
- Brand logo reference or URL.
- Name
demoVideo- Type
string- Description
- Demo video reference or URL.
- Name
downloads- Type
string[]- Description
- Downloadable asset references or URLs.
- Name
gallery- Type
string[]- Description
- Additional image references or URLs.
- Name
heroImage- Type
string- Description
- Primary image reference or URL.
- Name
infographic- Type
string- Description
- Infographic reference or URL.
- Name
promoVideo- Type
string- Description
- Promotional video reference or URL.
- Name
thumbnail- Type
string- Description
- Thumbnail reference or URL.
- Name
webPageUrl- Type
string- Description
- Product web page URL.
- Name
name- Type
string- Required
- required
- Description
- Product name.
- Name
prices- Type
ProductPriceSummary[]
View prices attributesClick or tap to expand
Non-archived catalog prices currently attached to the product.- Name
publishedAt- Type
Date | null- Description
- When the product was published.
- Name
reference- Type
string- Description
- Your product reference or SKU.
- Name
shipment- Type
ProductShipment | null
View shipment detailsClick or tap to expand
Fulfillment details copied from the product when present.- Name
taxCode- Type
string- Description
- Tax classification code.
- Name
type- Type
ProductType- Required
- required
- Description
- Product type:
Inttegro.ProductTypes.Cause,Inttegro.ProductTypes.Custom,Inttegro.ProductTypes.Digital,Inttegro.ProductTypes.Physical,Inttegro.ProductTypes.Service, orInttegro.ProductTypes.Voucher.
- Name
unitDim- Type
string- Description
- Unit dimension label.
- Name
updatedAt- Type
Date | null- Description
- When the product was last updated.
- Name
variantSetId- Type
string- Description
- Variant set configured for this Buy link.
quantityPurchaseIntentQuantityrequiredQuantity bounds enforced by the hosted checkout. Whenquantity.maxis omitted, the offer has no upper quantity limit.Click or tap to expand- Name
status- Type
PurchaseIntentStatus- Required
- required
- Description
Current effective state of the Buy link:
Inttegro.PurchaseIntentStatuses.Active,
Inttegro.PurchaseIntentStatuses.Expired,
Inttegro.PurchaseIntentStatuses.Inactive, or
Inttegro.PurchaseIntentStatuses.Used.
- Name
updatedAt- Type
Date | null- Description
When the merchant last changed the purchase intent.
usagePurchaseIntentUsagerequiredHow often the Buy link may be used.Click or tap to expand- Name
multiUse- Type
boolean- Description
- When
true, the same intent may produce multiple orders over time.
- Name
order- Type
PurchaseIntentUsageOrder
View order attributesClick or tap to expand
- Name
singleUse- Type
boolean- Description
- When
true, creating the first order consumes the Buy link.
variantSetPurchaseIntentVariantSetActive variant choices available to the customer. This can be omitted even whenallowVariantsistrue.Click or tap to expand- Name
active- Type
boolean- Required
- required
- Description
- Whether the variant set is active.
- Name
defaultProductId- Type
string- Description
- Default product in the variant set.
- Name
description- Type
string- Description
- Variant-set description.
- Name
id- Type
string- Required
- required
- Description
- Variant-set identifier.
- Name
name- Type
string- Required
- required
- Description
- Variant-set name.
- Name
reference- Type
string- Description
- Your reference for the variant set.
- Name
variantAxes- Type
PurchaseIntentVariantAxis[]- Required
- required
View variant_axes attributesClick or tap to expand
- Name
variants- Type
PurchaseIntentVariant[]- Required
- required
View variants attributesClick or tap to expand
Products currently available as choices in the variant set.- Name
active- Type
boolean- Required
- required
- Description
- Whether this variant is active.
- Name
position- Type
number- Description
- Display order of the variant.
- Name
price- Type
PurchaseIntentPrice
View price detailsClick or tap to expand
Resolved price for this variant, using the same shape as the top-levelpriceproperty.- Name
product- Type
PurchaseIntentProduct
View product detailsClick or tap to expand
Hydrated catalog product for this variant, using the same shape as the top-levelproductproperty.- Name
productId- Type
string- Required
- required
- Description
- Product represented by this variant.
- Name
variantValues- Type
VariantValues- Required
- required
View variant_values detailsClick or tap to expand
Axis keys and the values selected by this variant.
Create a purchase intent
Create a hosted Buy link for a catalog product. The response includes the sale_... ID used in the shareable checkout URL. No order exists yet; an order is created only when a customer checks out from the link.
Cause products default to “Support this cause,” “Contribution amount,” and “Continue to contribute.” Other product types default to “Prepare order,” “Amount,” and “Continue to payment.” The amount label appears only when the customer can select an amount.
AI clients can use create_buy_link for this operation. Confirmed MCP actions still require explicit form confirmation before Inttegro changes state.
Rules
- Send exactly one of
productorproductId. - Send exactly one of
priceorpriceId. - A referenced product and each referenced price must come from your catalog. The selected catalog price must be active, not archived, and belong to the selected product. An optional comparison price must belong to the selected product but does not determine what the customer is charged.
- An inline
price.nominal.valuemust be at least1and uses the smallest currency unit. Its currency is normalized to lowercase. - Within
price, send exactly one ofprice.idorprice.nominal. For comparison pricing, send at most one ofprice.originalorprice.originalId; withinprice.original, send exactly one ofprice.original.idorprice.original.nominal. quantity.minis required and must be at least1.quantity.maxis optional. When present, it must be at least1and greater than or equal toquantity.min; when omitted, the offer has no upper quantity limit.expiresAtmust be a future RFC3339 timestamp when provided.presentation.buyPage.textis optional. Each supplied label is trimmed, must contain non-whitespace text on one line, and must fit its documented length limit. Omit the completepresentationobject to use product-aware defaults.presentation.buyPage.text.primaryActionLabelcontrols only the ready action. Validation and loading labels remain system-owned so the button continues to describe its current state accurately.- A
product.variantSetIdis saved as offer configuration. Variant options are returned only when that set and its eligible products are available at lookup time. - Omit
usageor setusage.multiUsetotruefor a reusable link. Setusage.singleUsetotruefor a link that can create only one order. Do not send both fields.
Request attributes
- Name
expiresAt- Type
Date- Description
Optional expiry time for the Buy link. After this moment, new shoppers can no longer create orders from the intent.
presentationPurchaseIntentPresentationOptional plain-text overrides for the hosted Buy page. Omit this object to use product-aware defaults.Click or tap to expandView buy_page attributesClick or tap to expand
Hosted Buy-page presentation.View text attributesClick or tap to expand
At least one text override is required.
pricePurchaseIntentPriceSelectorPrice configuration for the Buy link. Use this instead ofpriceIdto supply an inline amount, a catalog price with comparison pricing, or both the sale and comparison amounts inline.Click or tap to expand- Name
id- Type
string- Description
- Existing price identifier to reuse.
- Name
nominal- Type
PriceParams
View original attributesClick or tap to expand
Optional original price for strike-through pricing when you are supplying a custom nominal amount.- Name
originalId- Type
string- Description
- Stored original price identifier when you want strike-through pricing without embedding
price.original.
- Name
priceId- Type
string- Description
Stored catalog price to reuse for the Buy link.
productPurchaseIntentProductSelectorProduct selection for the Buy link. Use this instead ofproductIdwhen the offer should expose a variant set.Click or tap to expand- Name
id- Type
string- Description
- Stored product identifier to sell through the Buy link.
- Name
variantSetId- Type
string- Description
- Variant set identifier when the offer should allow shoppers to switch between related products.
- Name
productId- Type
string- Description
Stored catalog product to reuse for the Buy link.
quantityPurchaseIntentQuantityrequiredQuantity bounds the hosted checkout enforces.Click or tap to expandusagePurchaseIntentUsageOptional usage policy. Omit it to create a reusable Buy link.Click or tap to expand
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.purchaseIntents.create({
productId: "prod_P9sK3vLm4nQ2xR7tY1wBc8Da",
priceId: "pr_G6tV2nQ9xM4bR7cD1yKs5LpW",
presentation: {
buyPage: {
text: {
checkoutSectionTitle: "Order your matcha",
primaryActionLabel: "Continue with this order",
},
},
},
quantity: {
max: 5,
min: 1,
},
usage: {
multiUse: true,
},
expiresAt: new Date("2030-12-01T09:00:00Z"),
})
Response
- Object
- JSON
PurchaseIntentResponse {
purchaseIntent: { … },
}
{
"purchase_intent": {
"id": "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha",
"quantity": { … },
"allow_variants": false,
"usage": { … },
"expires_at": "2030-12-01T09:00:00Z",
"status": "active",
"created_at": "2026-08-05T12:00:00Z",
"product": { … },
"price": { … },
"presentation": { … }
}
}
Update a purchase intent
Change the quantity, availability window, or customer-facing labels of an existing Buy link without changing what the link sells. Product, price, variant selection, and usage mode stay fixed so a URL already shared with customers does not silently become a different offer.
AI clients can use update_buy_link for this operation. Confirmed MCP actions still require explicit form confirmation before Inttegro changes state.
Rules
- Send exactly one identifier. Use
idfor new integrations;purchaseIntentIdremains available as a compatibility alias. - Setting
expiresAttonullclears the expiry time. - A non-null
expiresAtmust be an RFC3339 timestamp. A past timestamp is accepted and makes the offer immediately expired. - Setting
reactivatetotrueclears cancellation state and any existing elapsed expiry. If the same request sets a new elapsedexpiresAt, the intent remains expired. presentation.buyPage.textis a sparse update. Omit a label to preserve its current override; send the label asnullto remove that override and restore the product-aware default.- Every non-null text value is trimmed, must contain non-whitespace text on one line, and must fit its documented length limit. Appearance, validation messages, and loading labels are not configurable here.
- When supplied,
quantitymust includequantity.min, which must be at least1. Its optionalquantity.maxmust be greater than or equal toquantity.min. - Omitting
quantity.maxremoves an existing upper quantity limit. Omit the entirequantityobject to leave both bounds unchanged.
- Sending only the identifier is a valid no-op and returns the current object.
- A used single-use intent stays used; reactivation does not remove its order claim.
Request attributes
- Name
expiresAt- Type
Date | null- Description
New expiry time for the Buy link, or
nullto remove the current expiry.
- Name
id- Type
string- Description
Canonical purchase intent identifier. Required unless you use the compatibility alias.
presentationPurchaseIntentPresentationUpdateSparse plain-text update for the hosted Buy page. Omitted labels are preserved; explicit null restores a product-aware default.Click or tap to expand- Name
buyPage- Type
{ … }- Required
- required
View buy_page attributesClick or tap to expand
Hosted Buy-page presentation update.View text attributesClick or tap to expand
At least one text field is required.
quantityPurchaseIntentQuantityReplacement quantity bounds. Omit this object to leave the current bounds unchanged.Click or tap to expand- Name
purchaseIntentId- Type
string- Description
Compatibility alias for
id. Omit this in new integrations, and never send both identifier fields.
- Name
reactivate- Type
boolean- Description
Clear state that currently prevents new purchases.
This example replaces the section title, restores the product-aware primary action with an explicit null, and leaves the omitted amount-field label unchanged.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.purchaseIntents.update({
id: "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha",
presentation: {
buyPage: {
text: {
checkoutSectionTitle: "Complete your matcha order",
primaryActionLabel: null,
},
},
},
})
Response
- Object
- JSON
PurchaseIntentResponse {
purchaseIntent: { … },
}
{
"purchase_intent": {
"id": "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha",
"quantity": { … },
"allow_variants": false,
"usage": { … },
"expires_at": "2030-12-01T09:00:00Z",
"status": "active",
"created_at": "2026-08-05T12:00:00Z",
"updated_at": "2026-08-05T12:18:00Z",
"product": { … },
"price": { … },
"presentation": { … }
}
}
Cancel a purchase intent
Stop a Buy link from creating new orders immediately. Unlike expiry, cancellation happens when you choose to stop the offer. The intent remains available through the API with status set to Inttegro.PurchaseIntentStatuses.Inactive.
Canceling an already inactive intent returns its current state. A single-use intent that already created an order cannot be canceled.
Send exactly one identifier. Use id for new integrations; purchaseIntentId remains available as a compatibility alias.
AI clients can use cancel_buy_link for this operation. Confirmed MCP actions still require explicit form confirmation before Inttegro changes state.
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.purchaseIntents.cancel({
id: "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha",
})
Response
- Object
- JSON
PurchaseIntentResponse {
purchaseIntent: { … },
}
{
"purchase_intent": {
"id": "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha",
"quantity": { … },
"allow_variants": false,
"usage": { … },
"expires_at": "2030-12-01T09:00:00Z",
"inactive_at": "2026-08-05T12:26:00Z",
"status": "inactive",
"created_at": "2026-08-05T12:00:00Z",
"updated_at": "2026-08-05T12:26:00Z",
"product": { … },
"price": { … }
}
}
Lookup a purchase intent
Retrieve the offer behind a Buy link. Public checkout can look up a sale_... ID without an API key, so the ID is designed to be shared with customers and is not an account credential.
Public lookup returns active and expired offers so checkout can show either the offer or an expiry message. Canceled and already-used single-use offers are not exposed publicly. Authenticate a server-side lookup when you need every lifecycle state.
AI clients can use get_buy_link for this operation. MCP read tools return minimized business data and do not change Inttegro state.
Required attributes
- Name
id- Type
string- Required
- required
- Description
Purchase intent identifier with the
sale_prefix.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.purchaseIntents.lookup({
id: "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha",
})
Response
- Object
- JSON
PurchaseIntentResponse {
purchaseIntent: { … },
}
{
"purchase_intent": {
"id": "sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha",
"merchant": { … },
"quantity": { … },
"allow_variants": true,
"usage": { … },
"status": "active",
"created_at": "2026-08-05T12:00:00Z",
"product": { … },
"price": { … }
}
}
List purchase intents
Browse your Buy links, newest first. Each item contains the same merchant-facing details as an authenticated lookup.
Pagination is numbered rather than cursor-based. size in the response is the number of intents actually returned, which can be smaller than the requested pageSize. The response does not include a total count or next-page token.
AI clients can use list_buy_links for this operation. MCP read tools return minimized business data and do not change Inttegro state.
Required attributes
- Name
pageNumber- Type
number- Required
- required
- Description
1-based page number to fetch. Must be between 1 and 10 inclusive.
- Name
pageSize- Type
number- Required
- required
- Description
Number of items to return. Must be between 1 and 256 inclusive.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.purchaseIntents.page({
pageNumber: 1,
pageSize: 20,
})
Related resources
- Create a product - Build the catalog item a Buy link points at.
- Create a price - Store the catalog price a Buy link should reuse.
- Accept payment with Inttegro Checkout - Put the hosted checkout experience in front of customers.
- Create an order - Compare direct order creation with Buy-link-driven order creation.