Skip to main content
View as Markdown

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.

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.

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​

TypeScript SDK responseProductv12.0.0

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.

POST/products/create

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 or 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, Inttegro.ProductShipmentInputTypes.Download, Inttegro.ProductShipmentInputTypes.Render, or Inttegro.ProductShipmentInputTypes.Stream); negative dimension values are rejected and zero-valued dimensions are omitted from storage.

Available through MCP

AI clients can use create_product for this operation. Confirmed MCP actions still require explicit form confirmation before Inttegro changes state.

Request attributes​

TypeScript SDK requestCreateProductRequestv12.0.0

Request

POST/products/create
SDK versionv12.0.0
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",
  },
})

Response

SDK versionv12.0.0
ProductResponse {
  product: { … },
}
POST/products/search

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 before displaying current pricing or changing catalog state.

Request attributes​

TypeScript SDK requestResourceSearchRequestv12.0.0
  • Name
    cursor
    Type
    string
    Description

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

  • facetsResourceSearchFacet[]Fields to group and count: category, status, or type.Click or tap to expand
    • Name
      field
      Type
      string
      Required
      required
      Description
      Route-local facet field.
    • Name
      limit
      Type
      number
      Description
      Maximum buckets, from 1 through 50. Defaults to 10.
  • filtersResourceSearchFilter[]Exact category, status, or type constraints.Click or tap to expand
    • Name
      field
      Type
      string
      Required
      required
      Description
      Route-local filter field.
    • Name
      operator
      Type
      ResourceSearchOperator
      Required
      required
      Description
      eq for one value or in for any supplied value.
    • Name
      values
      Type
      string[]
      Required
      required
      Description
      One value for eq; one through 20 values for in.
  • Name
    pageSize
    Type
    number
    Description

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

  • sortResourceSearchSortResult ordering.Click or tap to expand
  • Name
    text
    Type
    string
    Description

    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, and freshness metadata. Read the canonical product before acting on a result.

Request

POST/products/search
SDK versionv12.0.0
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)

Response excerpt

SDK versionv12.0.0
SearchResponse {
  search: { … },
}
POST/products/lookup

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 attributes and media.

Archived products remain available through this endpoint for historical and administrative reads; inspect archivedAt rather than treating a successful lookup as proof that the product is currently offered.

Available through MCP

AI clients can use get_product for this operation. MCP read tools return minimized business data and do not change Inttegro state.

Request attributes​

TypeScript SDK requestLookupProductRequestv12.0.0
  • Name
    productId
    Type
    string
    Required
    required
    Description

    Unique product identifier returned when you created the product.

Request

POST/products/lookup
SDK versionv12.0.0
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",
})

Response

SDK versionv12.0.0
ProductResponse {
  product: { … },
}
POST/products/add_price

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 productId 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.

Available through MCP

AI clients can use create_product_price for this operation. Confirmed MCP actions still require explicit form confirmation before Inttegro changes state.

Request attributes​

TypeScript SDK requestAddProductPriceRequestv12.0.0
  • customerSelectedAmountCustomerSelectedAmountParamsSelection policy required when type is "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 when type is "fixed_amount".Click or tap to expand
    • Name
      currency
      Type
      Currency
      Required
      required
      Description
      Three-letter currency code.
    • Name
      value
      Type
      number
      Required
      required
      Description
      Amount in the currency's smallest unit. Must be greater than 0.
  • Name
    about
    Type
    string
    Description

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

  • Name
    label
    Type
    string
    Description

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

  • Name
    productId
    Type
    string
    Required
    required
    Description

    Unique identifier for a product in your catalog.

  • Name
    type
    Type
    'fixed_amount' | 'customer_selected_amount'
    Required
    required
    Description

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

Request

POST/products/add_price
SDK versionv12.0.0
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,
  },
})

Response

SDK versionv12.0.0
PriceResponse {
  price: { … },
}
POST/products/update

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 updatedAt. 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 id currently omits the prod_ type prefix. Call 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​

TypeScript SDK requestUpdateProductRequestv12.0.0

Request

POST/products/update
SDK versionv12.0.0
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",
})

Response

SDK versionv12.0.0
ProductResponse {
  product: { … },
}
POST/products/publish

Publish a product

Set the product's catalog state by setting active to true. Publishing does not create a checkout URL, choose a price, or authorize payment; create a purchase intent when you need a hosted Buy link.

publishedAt is set only on the first publish and remains unchanged after later unpublish and republish cycles. The endpoint returns a conflict when active is already true. The current operation does not reject an archived product, so check archivedAt before publishing.

Request attributes​

TypeScript SDK requestProductActionRequestv12.0.0
  • Name
    productId
    Type
    string
    Required
    required
    Description

    Unique product identifier.

Request

POST/products/publish
SDK versionv12.0.0
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",
})

Response

SDK versionv12.0.0
ProductResponse {
  product: { … },
}
POST/products/unpublish

Unpublish a product

Set active to false while preserving publishedAt. 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​

TypeScript SDK requestProductActionRequestv12.0.0
  • Name
    productId
    Type
    string
    Required
    required
    Description

    Unique product identifier.

Request

POST/products/unpublish
SDK versionv12.0.0
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",
})

Response

SDK versionv12.0.0
ProductResponse {
  product: { … },
}
POST/products/archive

Archive a product

Mark a product as retired. Archiving sets active to false, sets archivedAt, and advances updatedAt. There is no public unarchive endpoint, and 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​

TypeScript SDK requestProductActionRequestv12.0.0
  • Name
    productId
    Type
    string
    Required
    required
    Description

    Unique product identifier.

Request

POST/products/archive
SDK versionv12.0.0
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",
})

Response

SDK versionv12.0.0
ProductResponse {
  product: { … },
}
POST/products/page

Page through products

Browse every product in your catalog, including published, unpublished, and archived records. Products are sorted by products[].createdAt 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.

Available through MCP

AI clients can use list_products for this operation. MCP read tools return minimized business data and do not change Inttegro state.

Request attributes​

TypeScript SDK requestPageProductsRequestv12.0.0
  • Name
    pageNumber
    Type
    number
    Required
    required
    Description

    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.

  • Name
    pageSize
    Type
    number
    Description

    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​

Request

POST/products/page
SDK versionv12.0.0
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,
})

Response

SDK versionv12.0.0
PageResponse {
  page: { … },
}