---
title: "Products"
description: "Describe what you sell, attach reusable prices, and control how products appear in catalog experiences."
canonical: "https://studio.inttegro.com/api/products"
format: inttegro-machine-docs/v1
language: "TypeScript"
sdk_version: "v12.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/typescript/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 731
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "machine-only-decisions"
recommended_mcp_tools: ["get_product","get_product_analytics","create_product"]
estimated_tokens: 10808
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Describe what you sell, attach reusable prices, and control how products appear in catalog experiences. This TypeScript representation uses the selected SDK's native names wherever Studio has a verified mapping.

### Five questions

#### Q1. Is Products the right source for this task?

Use this reference for describe what you sell, attach reusable prices, and control how products appear in catalog experiences. For the complete outcome or lifecycle, start with [Manage your product catalog](https://studio.inttegro.com/machine/typescript/guides/manage-product-catalog.md); return here for exact operations and fields.

#### Q2. What is the first decision rule for model catalog identity, pricing, and sale availability separately?

A product describes what is sold; a [price](https://studio.inttegro.com/machine/typescript/api/prices.md) fixes a monetary
amount; a [purchase intent](https://studio.inttegro.com/machine/typescript/api/purchase-intents.md) creates a hosted Buy link.
Do not expect product creation or publication to perform either later step.

#### Q3. What is the second decision rule for model catalog identity, pricing, and sale availability separately?

Product type is permanent. Create a replacement product if its fundamental
classification changes, rather than forcing incompatible dimensions or
fulfillment data into the existing record.

#### Q4. What is the third decision rule for model catalog identity, pricing, and sale availability separately?

Updates replace list- and object-shaped fields such as media and custom data
when provided. Lookup first and merge in your system when existing entries
must be preserved.

#### Q5. What is the fourth decision rule for model catalog identity, pricing, and sale availability separately?

Publishing is catalog state, not a complete stop-or-sell control. To retire a
product from future sale, also retire its prices and remove checkout entry
points; existing orders retain their recorded snapshot.

### Recommended MCP assistance

Use these through an authenticated Inttegro MCP connection. This document remains the contract source.

- [`get_product`](https://studio.inttegro.com/machine/typescript/inttegro-mcp/tools.md#get_product) — read; no mutation confirmation. Gets one catalog product by ID with a compact, metadata-minimized projection.
- [`get_product_analytics`](https://studio.inttegro.com/machine/typescript/inttegro-mcp/tools.md#get_product_analytics) — analytics read; no mutation confirmation. Ranks products or inspects one product by paid orders, units sold, and gross revenue for a selected period and currency.
- [`create_product`](https://studio.inttegro.com/machine/typescript/inttegro-mcp/tools.md#create_product) — action; exact user confirmation required. Creates a catalog product as a draft by default. Prices are created separately so each operation has an unambiguous result.

## Document content

# Products

Use this reference for exact request attributes, response envelopes, object shape, and examples. For catalog modeling, product-price relationships, media, lifecycle behavior, and selling patterns, start with [Manage your product catalog](https://studio.inttegro.com/machine/typescript/guides/manage-product-catalog.md).

Product and price IDs from another application are treated as unavailable. Use the response error code rather than the HTTP status alone when choosing a recovery path.

## Model catalog identity, pricing, and sale availability separately

The four decision rules are in the machine preamble above.

## The product object

A product object contains everything needed to list, sell, and fulfill an item: core identification fields (name, description, reference), pricing information, prices attached to the product, categorization for reporting and filtering, media assets for customer-facing displays, physical dimensions for shipping calculations, and extensible custom data for application-specific needs. Products live in your catalog and can be referenced in order line items.

### Properties

- [`about`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Full product description with marketing copy, features, specifications, and
  any details customers need before purchase. Can include multiple paragraphs.
  Shown on product pages and detailed order views.

- [`active`](https://typescript.inttegro.dev/v12.0.0) — `boolean`

  Whether the product is currently published. This is catalog state, not a
  guarantee that every purchase path will accept or reject the product.

- [`attributes`](https://typescript.inttegro.dev/v12.0.0)

  Ordered name/value facts about this product. The list does not create selectable variants.

  - [`attributes.name`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Attribute name (e.g., "Size", "Color", "Material"). Between 1-100 characters.

  - [`attributes.value`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Attribute value (e.g., "Medium", "#FF0000", "Cotton"). Between 1-500 characters.

- [`archivedAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

  When this product was archived. Omitted for unarchived products. There is no
  public unarchive endpoint; use [Lookup a product](#lookup-a-product) when
  you need the canonical state of an archived record.

- [`category`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Product category for grouping, filtering, and reporting. Categories are
  application-specific and reflect your business structure. Examples:
  `clothing`, `software`,
  `consulting`, `electronics`.

- [`createdAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

  When this product was first created. Set automatically and never changes.
  Use for audit trails and chronological sorting.

- [`customData`](https://typescript.inttegro.dev/v12.0.0) — `object`

  String key-value metadata. Keys can contain up to 256 characters, and the
  serialized object can contain up to 25 KB.

- [`description`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Short description or tagline for the product. Appears in condensed views
  like order line items. Keep under 100 characters for best display. Max 200
  characters.

- [`dimensions`](https://typescript.inttegro.dev/v12.0.0)

  Stored dimension payload. The object shape depends on whether the product uses physical, digital, or custom sizing.

  - [`dimensions.custom`](https://typescript.inttegro.dev/v12.0.0) — `object`

    Custom sizing payload with optional [`product.dimensions.custom.details`](https://typescript.inttegro.dev/v12.0.0), [`product.dimensions.custom.size`](https://typescript.inttegro.dev/v12.0.0), and [`product.dimensions.custom.sizeUnit`](https://typescript.inttegro.dev/v12.0.0).

  - [`dimensions.digital`](https://typescript.inttegro.dev/v12.0.0) — `object`

    Digital sizing payload with optional [`product.dimensions.digital.bytes`](https://typescript.inttegro.dev/v12.0.0), [`product.dimensions.digital.size`](https://typescript.inttegro.dev/v12.0.0), and [`product.dimensions.digital.sizeUnit`](https://typescript.inttegro.dev/v12.0.0).

  - [`dimensions.physical`](https://typescript.inttegro.dev/v12.0.0) — `object`

    Physical sizing payload with optional [`product.dimensions.physical.height`](https://typescript.inttegro.dev/v12.0.0), [`product.dimensions.physical.length`](https://typescript.inttegro.dev/v12.0.0), [`product.dimensions.physical.volume`](https://typescript.inttegro.dev/v12.0.0), [`product.dimensions.physical.volumeUnit`](https://typescript.inttegro.dev/v12.0.0), [`product.dimensions.physical.weight`](https://typescript.inttegro.dev/v12.0.0), [`product.dimensions.physical.weightUnit`](https://typescript.inttegro.dev/v12.0.0), and [`product.dimensions.physical.width`](https://typescript.inttegro.dev/v12.0.0).

- [`id`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Unique identifier for this product. Generated automatically during creation.
  Used for lookups, order line items, and inventory tracking.

- [`media`](https://typescript.inttegro.dev/v12.0.0)

  Product media assets displayed to customers during browsing and checkout. Values can be Inttegro file references or plain remote URLs.

  - [`media.brandLogo`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Brand logo reference or URL.

  - [`media.demoVideo`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Demo video reference or URL.

  - [`media.downloads`](https://typescript.inttegro.dev/v12.0.0) — `array`

    Array of downloadable asset references or URLs.

  - [`media.gallery`](https://typescript.inttegro.dev/v12.0.0) — `array`

    Array of additional image references or URLs. Order matters.

  - [`media.heroImage`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Primary image reference or URL.

  - [`media.infographic`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Infographic reference or URL.

  - [`media.promoVideo`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Promotional video reference or URL.

  - [`media.thumbnail`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Thumbnail reference or URL.

  - [`media.webPageUrl`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Canonical product landing page URL.

- [`name`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Customer-facing product title shown in order summaries, invoices, and
  receipts. Keep concise and descriptive. Between 1-100 characters. Examples:
  `Premium Cotton T-Shirt`,
  `Annual Subscription`,
  `Video Editing Service`.

- [`prices`](https://typescript.inttegro.dev/v12.0.0)

  Non-archived prices attached to this product. Use product.prices\[].active to tell whether each one is currently usable in new flows.

  - [`prices.active`](https://typescript.inttegro.dev/v12.0.0) — `boolean`

    Whether the price is active and can be used in new flows.

  - [`prices.id`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Unique price identifier with the pr\_ prefix.

  - [`prices.label`](https://typescript.inttegro.dev/v12.0.0) — `string|null`

    Optional short label such as retail, wholesale, or subscriber.

  - [`prices.nominal`](https://typescript.inttegro.dev/v12.0.0) — `object`

    Price amount object containing lowercase [`product.prices[].nominal.currency`](https://typescript.inttegro.dev/v12.0.0) and smallest-unit [`product.prices[].nominal.value`](https://typescript.inttegro.dev/v12.0.0).

- [`reference`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Optional external reference or SKU from your internal systems. Map products
  to inventory management, ERP, or catalog system. Examples:
  `SKU-12345`,`PROD-SHIRT-BLUE-M`,
  `SERVICE-CONSULTING-HR`.

- [`publishedAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

  When the product was published. Omitted while the product is unpublished.

- [`shipment`](https://typescript.inttegro.dev/v12.0.0)

  Fulfillment method for the product when one is configured.

  - [`shipment.type`](https://typescript.inttegro.dev/v12.0.0) — `string`

    One of [`Inttegro.ProductShipmentTypes.Delivery`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductShipmentTypes.html#delivery) , [`Inttegro.ProductShipmentTypes.Download`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductShipmentTypes.html#download) , [`Inttegro.ProductShipmentTypes.Render`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductShipmentTypes.html#render) , or [`Inttegro.ProductShipmentTypes.Stream`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductShipmentTypes.html#stream) .

- [`taxCode`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Tax classification code for calculating sales tax, VAT, or regional taxes.

- [`type`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Permanent product classification:
  [`Inttegro.ProductTypes.Physical`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductTypes.html#physical),
  [`Inttegro.ProductTypes.Digital`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductTypes.html#digital),
  [`Inttegro.ProductTypes.Service`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductTypes.html#service),
  [`Inttegro.ProductTypes.Voucher`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductTypes.html#voucher),
  [`Inttegro.ProductTypes.Custom`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductTypes.html#custom), or
  [`Inttegro.ProductTypes.Cause`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductTypes.html#cause). Shipment
  and dimensions have their own request validation; the API does not infer
  them from this field.

- [`unitDim`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Measurement unit stored with the product when quantities or dimensions need
  units. Examples: `kg`, `lbs`,
  `liters`, `meters`,
  `sq_ft`.

- [`updatedAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

  Last time this product was modified. Omitted if it has not been updated
  since creation.

Product media fields can store either Inttegro file references or plain remote URLs. Prefer File API IDs when you want ownership and file-purpose validation. Keep `media.webPageUrl` for the product's canonical landing page only; it is not validated as a file reference.

## Create a product

Create a product record with a required `name` and `type`. Product creation does not accept inline `price` data: create the product first, then use [Add a price to a product](#add-a-price-to-a-product) or [Create a price](https://studio.inttegro.com/machine/typescript/api/prices.md#create-a-price).

New products are unpublished unless `publish` is `true`. `type` is permanent after creation. The API accepts one dimensions branch (`dimensions.custom`, `dimensions.digital`, or `dimensions.physical`) and one shipment `shipment.type` ([`Inttegro.ProductShipmentInputTypes.Delivery`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductShipmentInputTypes.html#delivery), [`Inttegro.ProductShipmentInputTypes.Download`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductShipmentInputTypes.html#download), [`Inttegro.ProductShipmentInputTypes.Render`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductShipmentInputTypes.html#render), or [`Inttegro.ProductShipmentInputTypes.Stream`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductShipmentInputTypes.html#stream)); negative dimension values are rejected and zero-valued dimensions are omitted from storage.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Request attributes

- `about` — `string`

  Full product description with features and specifications. Max 5000 characters.

- `attributes` — `Attribute[]`

  Ordered name/value facts about this product. These do not create selectable variants.

  - `attributes.name` — `string`

    Attribute name (1-100 characters).

  - `attributes.value` — `string`

    Attribute value (1-500 characters).

- `category` — `string`

  Product category for grouping and filtering. Max 100 characters.

- `customData` — `Data`

  Arbitrary string key-value pairs for application-specific needs. Attach internal catalog IDs, supplier references, merchandising metadata, or any data your system requires. Maximum size when serialized: 25 KB. See the [Custom Data guide](https://studio.inttegro.com/machine/typescript/api/custom-data.md) for best practices.

- `description` — `string`

  Short product tagline. Max 200 characters.

- `dimensions` — wire-only

  Optional dimensions payload. Provide only one of dimensions.custom, dimensions.digital, or dimensions.physical; numeric values cannot be negative.

  - `dimensions.custom` — `object` — wire-only

    Custom sizing payload with optional `dimensions.custom.details`, `dimensions.custom.size`, and `dimensions.custom.size_unit`.

  - `dimensions.digital` — `object` — wire-only

    Digital sizing payload with optional `dimensions.digital.bytes`, `dimensions.digital.size`, and `dimensions.digital.size_unit`.

  - `dimensions.physical` — `object` — wire-only

    Physical sizing payload with optional `dimensions.physical.height`, `dimensions.physical.length`, `dimensions.physical.volume`, `dimensions.physical.volume_unit`, `dimensions.physical.weight`, `dimensions.physical.weight_unit`, and `dimensions.physical.width`.

- `media` — `Media`

  Media assets. Values can be Inttegro file references or plain remote URLs.

  - `media.brandLogo` — `string`

    Brand logo reference or URL.

  - `media.demoVideo` — `string`

    Demo video reference or URL.

  - `media.downloads` — `string[]`

    Array of downloadable asset references or URLs.

  - `media.gallery` — `string[]`

    Array of additional image references or URLs.

  - `media.heroImage` — `string`

    Primary image reference or URL.

  - `media.infographic` — `string`

    Infographic reference or URL.

  - `media.promoVideo` — `string`

    Promotional video reference or URL.

  - `media.thumbnail` — `string`

    Thumbnail image reference or URL.

  - `media.webPageUrl` — `string`

    Product landing page URL.

- `name` — `string` — required

  Product name shown to customers. Between 1-100 characters.

- `publish` — `boolean` — wire-only

  Publish the product as part of creation. Defaults to `false` when omitted.

- `reference` — `string`

  External reference or SKU from your systems. Max 100 characters.

- `shipment` — `ShipmentInput`

  Optional fulfillment method. The current request shape contains only shipment.type.

  - `shipment.type` — `ShipmentInputType`

    One of [`Inttegro.ProductShipmentInputTypes.Delivery`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductShipmentInputTypes.html#delivery), [`Inttegro.ProductShipmentInputTypes.Download`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductShipmentInputTypes.html#download), [`Inttegro.ProductShipmentInputTypes.Render`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductShipmentInputTypes.html#render), or [`Inttegro.ProductShipmentInputTypes.Stream`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductShipmentInputTypes.html#stream).

- `taxCode` — `string`

  Tax classification code. Max 50 characters.

- `type` — `Type` — required

  Product type: [`Inttegro.ProductTypes.Physical`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductTypes.html#physical), [`Inttegro.ProductTypes.Digital`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductTypes.html#digital), [`Inttegro.ProductTypes.Service`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductTypes.html#service), [`Inttegro.ProductTypes.Voucher`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductTypes.html#voucher), [`Inttegro.ProductTypes.Custom`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductTypes.html#custom), or [`Inttegro.ProductTypes.Cause`](https://typescript.inttegro.dev/v12.0.0/variables/types_products.ProductTypes.html#cause).

- `unit_dimension` — `string` — wire-only

  Measurement unit for quantities. Max 20 characters. Examples: `kg`, `lbs`, `liters`.

**Request — POST /products/create**

```typescript
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.products.create({
  name: "Premium Cotton T-Shirt",
  type: Inttegro.ProductTypes.Physical,
  description: "Comfortable everyday wear",
  about: "Our premium cotton t-shirt is made from 100% organic cotton...",
  category: "clothing",
  attributes: [
    {
      name: "Size",
      value: "Medium",
    },
    {
      name: "Color",
      value: "Blue",
    },
  ],
  media: {
    heroImage: "file_abc123",
    gallery: [
      "file_def456",
      "file_ghi789",
    ],
  },
  customData: {
    season: "summer",
    material: "organic_cotton",
  },
})
```

```json
{
  "product": {
    "id": "prod_abc123xyz789",
    "name": "Premium Cotton T-Shirt",
    "type": "physical",
    "active": false,
    "description": "Comfortable everyday wear",
    "category": "clothing",
    "reference": "SKU-SHIRT-BLUE-M-2024",
    "created_at": "2026-02-08T23:45:00Z"
  }
}
```

## Search products

Search products by catalog text or exact category, status, and type
constraints. Results are discovery summaries: use the returned product ID
with [Lookup a product](#lookup-a-product) before displaying current pricing
or changing catalog state.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

## Use product search for discovery, then read the product

- Send `text`,
  `filters`,
  or both. Filters and facets accept only the wire field names
  `category`, `status`, and
  `type`; field names are unqualified.
- Product search additionally supports the wire sort field
  `published_at`. Relevance is descending only;
  `published_at` and `updated_at` support
  either direction.
- Treat each result as a discovery summary. Read the canonical product by
  [`results[].resource.id`](https://typescript.inttegro.dev/v12.0.0)
  before relying on publication state, prices, or media.
- Replay the same request with
  [`nextCursor`](https://typescript.inttegro.dev/v12.0.0)
  as the request cursor when
  [`hasMore`](https://typescript.inttegro.dev/v12.0.0)
  is true. The cursor is opaque; do not decode or modify it.
- Inspect [`freshness`](https://typescript.inttegro.dev/v12.0.0),
  [`total.relation`](https://typescript.inttegro.dev/v12.0.0),
  and the requested facet counts before interpreting search coverage. Use
  lookup whenever current state matters.

### Request attributes

- `cursor` — `string`

  Opaque continuation cursor returned by the previous page. Replay the
  same request and add this value for the next page.

- `facets` — `array`

  Fields to group and count: category, status, or type.

  - `facets.field` — `array` — required

    Route-local facet field.

  - `facets.limit` — `array`

    Maximum buckets, from 1 through 50. Defaults to 10.

- `filters` — `array`

  Exact category, status, or type constraints.

  - `filters.field` — `array` — required

    Route-local filter field.

  - `filters.operator` — `array` — required

    eq for one value or in for any supplied value.

  - `filters.values` — `array` — required

    One value for eq; one through 20 values for in.

- `pageSize` — `integer`

  Results per page, from `1` through `100`. Defaults to `20`.

- `sort` — `object`

  Result ordering.

  - `sort.direction` — `object` — required

    asc or desc. Relevance supports desc only.

  - `sort.field` — `object` — required

    published\_at, relevance, or updated\_at.

- `text` — `string`

  Search text, from 1 through 512 characters. Supply search text, exact
  filters, or both.

### Response

Returns a typed search page with discovery summaries, requested facet
counts, page and total counts, an optional [`nextCursor`](https://typescript.inttegro.dev/v12.0.0),
and [`freshness`](https://typescript.inttegro.dev/v12.0.0) metadata. Read the canonical product
before acting on a result.

**Request — POST /products/search**

```typescript
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})

const request: Inttegro.ResourceSearchRequest = {
  text: "utility sneakers",
}
const page = await inttegro.products.search(request)
```

```json
{
  "search": {
    "results": [
      {
        "resource": { "type": "product", "id": "prod_abc123xyz" },
        "title": "Utility Sneakers",
        "summary": "Everyday low-profile sneakers",
        "status": "active",
        "updated_at": "2026-09-21T10:30:00Z"
      }
    ]
  }
}
```

## Lookup a product

Retrieve a product by ID, including its catalog fields and non-archived attached prices. Use lookup when you need the current product record before selecting a price or replacing list-shaped fields such as [`product.attributes`](https://typescript.inttegro.dev/v12.0.0) and [`product.media`](https://typescript.inttegro.dev/v12.0.0).

Archived products remain available through this endpoint for historical and administrative reads; inspect [`product.archivedAt`](https://typescript.inttegro.dev/v12.0.0) rather than treating a successful lookup as proof that the product is currently offered.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Request attributes

- `product_id` — `string` — required — wire-only

  Unique product identifier returned when you created the product.

**Request — POST /products/lookup**

```typescript
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.products.lookup({
  productId: "prod_abc123xyz789",
})
```

```json
{
  "product": {
    "id": "prod_abc123xyz789",
    "name": "Premium Cotton T-Shirt",
    "type": "physical",
    "active": false,
    "description": "Comfortable everyday wear",
    "category": "clothing",
    "reference": "SKU-SHIRT-BLUE-M-2024",
    "attributes": [
      {
        "name": "Size",
        "value": "Medium"
      },
      {
        "name": "Color",
        "value": "Blue"
      }
    ],
    "prices": [
      {
        "id": "pr_abc123xyz789",
        "active": true,
        "nominal": {
          "currency": "usd",
          "value": 2999
        }
      }
    ],
    "created_at": "2026-02-08T23:45:00Z",
    "updated_at": "2026-02-08T23:50:15Z"
  }
}
```

## Add a price to a product

Create an active price attached to an existing, unarchived product in your catalog. The operation returns the created price; the product object has no default-price field or default-price mutation.

The response's [`price.productId`](https://typescript.inttegro.dev/v12.0.0) currently uses the product ID value without the `prod_` type prefix; both forms are accepted when you send a product ID back to the API.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Request attributes

- `customerSelectedAmount` — `CustomerSelectedAmountParams`

  Selection policy required when type is "customer\_selected\_amount".

  - `customerSelectedAmount.currency` — `Currency` — required

    Currency accepted from the customer.

  - `customerSelectedAmount.minimum` — `number` — required

    Smallest amount the customer may enter. Must be at least 1.

  - `customerSelectedAmount.maximum` — `number`

    Optional largest amount the customer may enter. Must be at least the minimum.

  - `customerSelectedAmount.suggestedAmounts` — `SuggestedAmountParams[]`

    Optional convenient choices. IDs and values must be unique, and at most one suggestion may be recommended.

- `fixedAmount` — `AmountParams`

  Amount required when type is "fixed\_amount".

  - `fixedAmount.currency` — `Currency` — required

    Three-letter currency code.

  - `fixedAmount.value` — `number` — required

    Amount in the currency's smallest unit. Must be greater than 0.

- `about` — `string`

  Optional internal description for the new price. Maximum length: 500 characters.

- `label` — `string`

  Optional short label for the new price, such as `retail`, `wholesale`, or `subscriber`. Maximum length: 100 characters.

- `productId` — `string` — required

  Unique identifier for a product in your catalog.

- `type` — `Type` — required

  Price definition. Use `"fixed_amount"` or `"customer_selected_amount"`. Send only the matching definition object.

**Request — POST /products/add\_price**

```typescript
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.products.addPrice({
  productId: "prod_abc123xyz789",
  label: "Wholesale",
  about: "Preferred rate for repeat buyers",
  type: "fixed_amount",
  fixedAmount: {
    currency: "ghs",
    value: 85000,
  },
})
```

```json
{
  "price": {
    "id": "pr_abc123xyz789",
    "label": "Wholesale",
    "about": "Preferred rate for repeat buyers",
    "active": true,
    "nominal": {
      "currency": "ghs",
      "value": 85000
    },
    "product_id": "abc123xyz789",
    "created_at": "2026-02-08T23:55:00Z"
  }
}
```

## Update a product

Modify an existing product's details by providing only the fields you want to change. Any field you omit remains unchanged. Update or create prices through the Prices API; this endpoint rejects inline `price` data.

Only `productId` is required. A request with no changed fields succeeds without advancing [`product.updatedAt`](https://typescript.inttegro.dev/v12.0.0). `type` may be sent only when it matches the existing type. `name`, `about`, `category`, and `taxCode` cannot be cleared once populated; `description` can be replaced with an empty string.

For media changes, send the full `media` object you want stored. The legacy `images` array is still accepted and maps to `media.gallery`; do not send `images` and `media` together. The update response is a reduced product projection and omits `active`, `archived_at`, `attributes`, `media`, and `shipment`. Its [`product.id`](https://typescript.inttegro.dev/v12.0.0) currently omits the `prod_` type prefix. Call [Lookup a product](#lookup-a-product) when you need the canonical complete representation.

Archived products are currently accepted by this endpoint. Treat archival as
catalog state and enforce any stricter selling policy in the flow that
selects products for checkout.

### Request attributes

- `about` — `string`

  Full product description. Cannot be cleared once set—only updated to a new non-empty value.

- `attributes` — `Attribute[]`

  Product attributes. Replaces the existing attribute list when provided.

  - `attributes.name` — `string`

    Attribute name (1-100 characters).

  - `attributes.value` — `string`

    Attribute value (1-500 characters).

- `category` — `string`

  Product category. Cannot be cleared once set—only changed to a different category.

- `customData` — `Data`

  Application-specific metadata. Replaces the entire `customData` object when provided—does not merge with existing values. Retrieve the product first if you need to preserve existing keys. Maximum size: 25 KB when serialized.

- `description` — `string`

  Short product tagline. Can be updated or cleared.

- `dimensions` — wire-only

  Optional dimensions payload. Replaces the stored dimensions when provided. Send only one of dimensions.custom, dimensions.digital, or dimensions.physical.

  - `dimensions.custom` — `object` — wire-only

    Custom sizing payload with optional `dimensions.custom.details`, `dimensions.custom.size`, and `dimensions.custom.size_unit`.

  - `dimensions.digital` — `object` — wire-only

    Digital sizing payload with optional `dimensions.digital.bytes`, `dimensions.digital.size`, and `dimensions.digital.size_unit`.

  - `dimensions.physical` — `object` — wire-only

    Physical sizing payload with optional `dimensions.physical.height`, `dimensions.physical.length`, `dimensions.physical.volume`, `dimensions.physical.volume_unit`, `dimensions.physical.weight`, `dimensions.physical.weight_unit`, and `dimensions.physical.width`.

- `images` — `array` — wire-only

  Legacy alias for `media.gallery`. Replaces the gallery entries when provided.

- `media` — `Media`

  Media assets. Replaces the stored media object when provided. Values can be Inttegro file references or plain remote URLs.

  - `media.brandLogo` — `string`

    Brand logo reference or URL.

  - `media.demoVideo` — `string`

    Demo video reference or URL.

  - `media.downloads` — `string[]`

    Array of downloadable asset references or URLs.

  - `media.gallery` — `string[]`

    Array of additional image references or URLs.

  - `media.heroImage` — `string`

    Primary image reference or URL.

  - `media.infographic` — `string`

    Infographic reference or URL.

  - `media.promoVideo` — `string`

    Promotional video reference or URL.

  - `media.thumbnail` — `string`

    Thumbnail image reference or URL.

  - `media.webPageUrl` — `string`

    Product landing page URL.

- `name` — `string`

  Product name. Cannot be cleared once set—only updated to a new non-empty value.

- `productId` — `string` — required

  Unique product identifier.

- `taxCode` — `string`

  Tax classification code. Cannot be cleared once set—only changed to a different code.

- `type` — `string` — wire-only

  Must exactly match the existing product type. Product type cannot be changed after creation.

- `unit_dimension` — `string` — wire-only

  Measurement unit. Cannot exceed 20 characters.

**Request — POST /products/update**

```typescript
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.products.update({
  productId: "prod_abc123xyz789",
  description: "Premium everyday comfort",
  category: "apparel",
})
```

```json
{
  "product": {
    "id": "abc123xyz789",
    "name": "Premium Cotton T-Shirt",
    "type": "physical",
    "description": "Premium everyday comfort",
    "category": "apparel",
    "reference": "SKU-SHIRT-BLUE-M-2024",
    "created_at": "2026-02-08T23:45:00Z",
    "updated_at": "2026-02-09T15:30:00Z"
  }
}
```

## Publish a product

Set the product's catalog state by setting [`product.active`](https://typescript.inttegro.dev/v12.0.0) to `true`. Publishing does not create a checkout URL, choose a price, or authorize payment; create a [purchase intent](https://studio.inttegro.com/machine/typescript/api/purchase-intents.md#create-a-purchase-intent) when you need a hosted Buy link.

[`product.publishedAt`](https://typescript.inttegro.dev/v12.0.0) is set only on the first publish and remains unchanged after later unpublish and republish cycles. The endpoint returns a conflict when [`product.active`](https://typescript.inttegro.dev/v12.0.0) is already `true`. The current operation does not reject an archived product, so check [`product.archivedAt`](https://typescript.inttegro.dev/v12.0.0) before publishing.

### Request attributes

- `product_id` — `string` — required — wire-only

  Unique product identifier.

**Request — POST /products/publish**

```typescript
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.products.publish({
  productId: "prod_abc123xyz789",
})
```

```json
{
  "product": {
    "id": "prod_abc123xyz789",
    "name": "Premium Cotton T-Shirt",
    "type": "physical",
    "active": true,
    "category": "apparel",
    "created_at": "2026-02-08T23:45:00Z",
    "published_at": "2026-02-09T16:30:00Z",
    "updated_at": "2026-02-09T16:30:00Z"
  }
}
```

## Unpublish a product

Set [`product.active`](https://typescript.inttegro.dev/v12.0.0) to `false` while preserving [`product.publishedAt`](https://typescript.inttegro.dev/v12.0.0). This is reversible: publish the same product again when you are ready to mark it active.

The endpoint returns a conflict when the product is already inactive. Unpublishing does not change attached prices or existing purchase intents, and current ID-based order creation does not use product publication as its price-eligibility check. Deactivate or archive prices and withdraw checkout entry points when you need to stop future sales.

### Request attributes

- `product_id` — `string` — required — wire-only

  Unique product identifier.

**Request — POST /products/unpublish**

```typescript
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.products.unpublish({
  productId: "prod_abc123xyz789",
})
```

```json
{
  "product": {
    "id": "prod_abc123xyz789",
    "name": "Premium Cotton T-Shirt",
    "type": "physical",
    "active": false,
    "category": "apparel",
    "created_at": "2026-02-08T23:45:00Z",
    "published_at": "2026-02-09T16:30:00Z",
    "updated_at": "2026-02-09T17:15:00Z"
  }
}
```

## Archive a product

Mark a product as retired. Archiving sets [`product.active`](https://typescript.inttegro.dev/v12.0.0) to `false`, sets [`product.archivedAt`](https://typescript.inttegro.dev/v12.0.0), and advances [`product.updatedAt`](https://typescript.inttegro.dev/v12.0.0). There is no public unarchive endpoint, and [Add a price to a product](#add-a-price-to-a-product) rejects archived products.

The endpoint returns a conflict when the product is already archived. It does not archive or deactivate prices that already belong to the product. Current lookup, update, publish, pagination, purchase-intent creation, and ID-based order paths can still resolve the product, so retire its prices and checkout entry points separately. Existing orders keep their recorded product snapshot.

### Request attributes

- `product_id` — `string` — required — wire-only

  Unique product identifier.

**Request — POST /products/archive**

```typescript
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.products.archive({
  productId: "prod_abc123xyz789",
})
```

```json
{
  "product": {
    "id": "prod_abc123xyz789",
    "name": "Premium Cotton T-Shirt",
    "type": "physical",
    "active": false,
    "category": "apparel",
    "created_at": "2026-02-08T23:45:00Z",
    "archived_at": "2026-02-09T18:00:00Z",
    "updated_at": "2026-02-09T18:00:00Z"
  }
}
```

## Page through products

Browse every product in your catalog, including published, unpublished, and archived records. Products are sorted by [`page.products[].createdAt`](https://typescript.inttegro.dev/v12.0.0) in descending order—page 1 contains the newest entries and subsequent pages step back in time.

Each response returns the full product object, including all fields: media assets, attributes, dimensions, shipment details, and custom data. `pageNumber` is required; `pageSize` defaults to 256 if omitted.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Request attributes

- `pageNumber` — `number` — required

  1-based page index. Must be between 1 and 10 inclusive. Start at 1 to retrieve the most recently created products and increment to walk backwards through your catalog.

- `pageSize` — `number`

  Number of products per page (1–256). Defaults to 256 when omitted. The response echoes the count actually returned, so the final page can be smaller than the value you requested.

### Response shape

- Top-level [`page`](https://typescript.inttegro.dev/v12.0.0) object containing [`page.number`](https://typescript.inttegro.dev/v12.0.0), [`page.size`](https://typescript.inttegro.dev/v12.0.0), and a [`page.products`](https://typescript.inttegro.dev/v12.0.0) array.
- Each entry is a full product object identical to what [Lookup a product](https://studio.inttegro.com/machine/typescript/api/products.md#lookup-a-product) returns: all core fields, optional nested objects ([`page.products[].media`](https://typescript.inttegro.dev/v12.0.0), [`page.products[].dimensions`](https://typescript.inttegro.dev/v12.0.0), [`page.products[].attributes`](https://typescript.inttegro.dev/v12.0.0), [`page.products[].shipment`](https://typescript.inttegro.dev/v12.0.0)), and lifecycle timestamps.
- Stop paginating when the response [`page.size`](https://typescript.inttegro.dev/v12.0.0) is less than the `pageSize` you requested, or when [`page.products`](https://typescript.inttegro.dev/v12.0.0) is an empty array.

**Request — POST /products/page**

```typescript
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.products.page({
  pageNumber: 1,
  pageSize: 50,
})
```

```json
{
  "page": {
    "number": 1,
    "size": 2,
    "products": [
      {
        "id": "prod_mK9XzR2qLpT4nW8sVcJ1bHfYuAeD3gN5oI6Ph7Qa",
        "name": "Premium Cotton T-Shirt",
        "type": "physical",
        "active": true,
        "description": "Comfortable everyday wear",
        "category": "clothing",
        "reference": "SKU-SHIRT-BLUE-M",
        "tax_code": "TX-APPAREL",
        "attributes": [
          { "name": "Size",  "value": "Medium" },
          { "name": "Color", "value": "Blue" }
        ],
        "prices": [
          {
            "id": "pr_M4n8Q2w7X5z1C9v6B3k0LpR",
            "active": true,
            "label": "Retail",
            "nominal": {
              "currency": "usd",
              "value": 2999
            }
          },
          {
            "id": "pr_J7s3D1f9H6k2L8m5N4p0QwT",
            "active": false,
            "label": "Wholesale",
            "nominal": {
              "currency": "usd",
              "value": 2799
            }
          }
        ],
        "media": {
          "hero_image": "file_abc123",
          "thumbnail":  "file_xyz789"
        },
        "created_at":   "2026-01-15T09:30:00Z",
        "published_at": "2026-01-15T10:00:00Z",
        "updated_at":   "2026-02-01T14:22:00Z"
      },
      {
        "id": "prod_aB3CdE4FgH5IjK6LmN7OpQ8RsT9UvW0XyZ1AbCd",
        "name": "Annual SaaS Subscription",
        "type": "digital",
        "active": true,
        "description": "Unlimited platform access",
        "category": "software",
        "created_at": "2026-01-10T08:00:00Z",
        "published_at": "2026-01-10T08:05:00Z"
      }
    ]
  }
}
```