Skip to main content

Purchase Intents

Purchase intents let you sell one catalog product from a controlled, shareable Buy link. Use them when you want a product-specific checkout URL for campaigns, social commerce, QR codes, or a lightweight storefront without building a cart and checkout flow yourself.

note

Treat a Buy link as customer-facing access to an offer. The sale_... identifier is not a secret API key, but anyone with the link can view the offer while it is active.

Prerequisites

  • A catalog product created with Create a product
  • An active, unarchived price for that product from Create a price
  • A server-side place to store the returned sale_... purchase intent ID

A purchase intent is the merchant-authored offer behind a Buy link. It fixes the product, price, quantity range, optional expiry, and whether the link can create one order or many orders. It is not itself an order or payment.

When a customer opens the Buy link, Inttegro Checkout loads the offer, collects the customer and payment details, and creates the order only after the customer chooses to buy. The resulting order is then managed through the Orders API.

ResourceCreated byWhat it controls
ProductYour catalog setupName, description, media, fulfillment shape, and catalog identity
PriceYour catalog setupReusable amount and currency for that product
Purchase intentYour serverThe Buy link offer, quantity bounds, expiry, and usage policy
OrderCustomer checkoutThe actual purchase record, payment, invoice, and fulfillment state

Create the purchase intent from your server after the product and price exist. Use usage.multi_use when the same link can keep accepting purchases. Use usage.single_use when the link should be consumed by the first successful order creation.

The full parameter contract, including inline price, catalog price, usage, expiry, and variant-set shapes, is documented in Create a purchase intent.

The response includes purchase_intent.id, such as sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha. Build the customer-facing URL by appending that ID to the Pages Buy path:

https://pages.inttegro.com/buy/sale_B7tQ2nLm5yR8cV1pKs4Dx9Ha

Treat this URL as a shareable bearer link. Anyone with the URL can view the offer and start checkout, although they cannot change the product, price, quantity bounds, or expiry configured on the intent.

Keep the offer controlled

Purchase intents keep shared links stable. Updating an intent can adjust quantity bounds, set or clear expiry, or reactivate a canceled or expired offer. It cannot change the product, price, variant selection, or usage mode, because customers may already have the link.

Use lookup or page operations to inspect status:

  • active means the Buy link can accept checkout.
  • expired means expires_at has passed.
  • inactive means you canceled the offer.
  • used means a single-use link already created an order.

For a shared campaign link, create a multi-use intent and set an expiry that matches the campaign window. For a direct invoice-like sale, create a single-use intent so one customer claim consumes the link.

Use Cancel a purchase intent to stop new purchases immediately while keeping the purchase intent visible to the owning application. Existing orders that were already created from the link remain normal orders and should be fulfilled, canceled, or refunded through the order and refund workflows.

Variants and comparison pricing

If the offer should let the customer choose among related variants, create the intent with a product.variant_set_id. The primary product remains the default product for the offer, and Pages can render eligible variant options when the variant set is available.

Comparison pricing is display-only. You can provide original pricing for strike-through presentation, but the nominal price is the amount used when the order is created.

The checkout flow creates an order when the customer submits the purchase. Look up that order through Lookup an order and use the order status, payment status, invoice, and fulfillment fields as the source of truth for the actual transaction.

Authenticated purchase-intent lookup and list responses may include recent activity for merchant visibility, but purchase intents should not replace order reporting or balance reconciliation. Use List purchase intents to manage the links themselves, Page through orders for transaction records, and Balances for settled financial state.

Operational rules

  • Create, update, cancel, and list purchase intents from your server.
  • Public lookup is available so the hosted Buy page can resolve an offer by its sale_... ID.
  • Store the returned purchase intent ID anywhere you need to display, revoke, or audit the offer later.
  • Cancel stale links instead of deleting records; historical intent records explain how later orders originated.