---
title: "Prices"
description: "Create reusable monetary amounts, attach them to products, and control whether new checkout flows may use them."
canonical: "https://studio.inttegro.com/api/prices"
format: inttegro-machine-docs/v1
language: "PHP"
sdk_version: "v12.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/php/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: 700
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "machine-only-decisions"
recommended_mcp_tools: ["get_price","list_prices","create_product_price"]
estimated_tokens: 5855
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Create reusable monetary amounts, attach them to products, and control whether new checkout flows may use them. This PHP representation uses the selected SDK's native names wherever Studio has a verified mapping.

### Five questions

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

Use this reference for create reusable monetary amounts, attach them to products, and control whether new checkout flows may use them. For the complete outcome or lifecycle, start with [Manage your product catalog](https://studio.inttegro.com/machine/php/guides/manage-product-catalog.md); return here for exact operations and fields.

#### Q2. What is the first decision rule for change commercial pricing by replacement, not mutation?

A price's amount, currency, and product relationship are fixed at creation.
Create a replacement when any of those changes, then deactivate or archive
the old price according to whether reversibility is required.

#### Q3. What is the second decision rule for change commercial pricing by replacement, not mutation?

Deactivation prevents new catalog selections and can be reversed. Archiving
is permanent. Neither operation rewrites the amount captured by existing
orders.

#### Q4. What is the third decision rule for change commercial pricing by replacement, not mutation?

Product publication and price eligibility are distinct states. Before using a
catalog price, verify both the intended product relationship and the price's
own active, non-archived lifecycle.

#### Q5. What is the fourth decision rule for change commercial pricing by replacement, not mutation?

Use lookup for the canonical current record and [Products](https://studio.inttegro.com/machine/php/api/products.md) for
catalog composition. Use [Purchase intents](https://studio.inttegro.com/machine/php/api/purchase-intents.md) only when a
hosted Buy link is the desired entry point.

### Recommended MCP assistance

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

- [`get_price`](https://studio.inttegro.com/machine/php/inttegro-mcp/tools.md#get_price) — read; no mutation confirmation. Gets one catalog price by ID with its amount and compact related-product identity.
- [`list_prices`](https://studio.inttegro.com/machine/php/inttegro-mcp/tools.md#list_prices) — read; no mutation confirmation. Lists a bounded page of catalog prices, optionally restricted to one product, with exact familiar-unit amounts.
- [`create_product_price`](https://studio.inttegro.com/machine/php/inttegro-mcp/tools.md#create_product_price) — action; exact user confirmation required. Creates an active price for an existing product. Supply an exact decimal amount in familiar major currency units; the MCP converts it safely.

## Document content

# 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](https://studio.inttegro.com/machine/php/guides/manage-product-catalog.md).

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.

## Change commercial pricing by replacement, not mutation

The four decision rules are in the machine preamble above.

## 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

- [`about`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html) — `string`

  Optional description of what this price represents. Max 500 characters.

- [`active`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html) — `boolean`

  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.

- [`archived_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html) — `timestamp`

  When this price was permanently retired. Omitted otherwise. Archiving also
  sets [`price.active`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html) to
  `false`, and archived prices cannot
  be reactivated.

- [`created_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html) — `timestamp`

  When this price was first created. Set automatically and never changes.

- [`id`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html) — `string`

  Unique identifier for this price, generated automatically during creation.

- [`label`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html) — `string`

  Optional short name for distinguishing prices. Max 100 characters. Examples:
  `Monthly`, `Enterprise Annual`,
  `One-time setup`.

- [`nominal`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html)

  The monetary amount for this price.

  - [`nominal.currency`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html) — `string`

    Three-letter currency code. Supported values: [`\Inttegro\Money\Currency::GHS`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Money-Currency.html#enumcase_GHS) , [`\Inttegro\Money\Currency::USD`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Money-Currency.html#enumcase_USD) , [`\Inttegro\Money\Currency::GBP`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Money-Currency.html#enumcase_GBP) , [`\Inttegro\Money\Currency::EUR`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Money-Currency.html#enumcase_EUR) , [`\Inttegro\Money\Currency::CNY`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Money-Currency.html#enumcase_CNY) . Set at creation and cannot be changed.

  - [`nominal.value`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html) — `integer`

    Amount in the smallest currency unit (e.g., cents for USD, pesewas for GHS). Set at creation and cannot be changed.

- [`product`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html) — `object`

  The related product, when the price is attached to one. Omitted for a
  standalone price. The related product omits the full
  `prices` collection.

- [`updated_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html) — `timestamp`

  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 `fixed_amount`, or `'customer_selected_amount'` with `customer_selected_amount`. Do not send both definitions. Customer-selected prices require `product_id` 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

- `about` — `string` — wire-only

  Description of the price. Max 500 characters.

- `customer_selected_amount` — wire-only

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

  - `customer_selected_amount.currency` — `string` — required — wire-only

    Currency accepted from the customer.

  - `customer_selected_amount.minimum` — `integer` — required — wire-only

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

  - `customer_selected_amount.maximum` — `integer` — wire-only

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

  - `customer_selected_amount.suggested_amounts` — `array` — wire-only

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

- `fixed_amount` — wire-only

  Amount required when type is "fixed\_amount".

  - `fixed_amount.currency` — `string` — required — wire-only

    Three-letter currency code.

  - `fixed_amount.value` — `integer` — required — wire-only

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

- `label` — `string` — wire-only

  Short display name. Max 100 characters.

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

  Permanently associate the price with an existing product in your catalog. Required for customer-selected prices; optional for fixed prices.

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

  Price definition. Use `'fixed_amount'` or `'customer_selected_amount'`.

**Request — POST /prices/create**

```php
<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->prices->create([
  'type' => 'fixed_amount',
  'fixed_amount' => [
    'currency' => 'usd',
    'value' => 2999,
  ],
  'label' => 'Monthly',
  'about' => 'Standard monthly subscription price',
  'product_id' => 'prod_abc123xyz789',
]);
```

```json
{
  "price": {
    "id": "pr_k8m2x9v4n7p1",
    "about": "Standard monthly subscription price",
    "active": true,
    "nominal": {
      "currency": "usd",
      "value": 2999
    },
    "created_at": "2026-02-13T02:00:00Z",
    "label": "Monthly",
    "product": {
      "id": "prod_abc123xyz789",
      "about": "Starter plan for solo businesses",
      "active": true,
      "attributes": [
        {
          "name": "tier",
          "value": "starter"
        }
      ],
      "category": "software",
      "created_at": "2026-02-13T01:45:00Z",
      "custom_data": {
        "plan": "starter"
      },
      "description": "Standard monthly subscription",
      "name": "Starter plan",
      "published_at": "2026-02-13T02:05:00Z",
      "reference": "plan-starter-monthly",
      "tax_code": "txcd_software",
      "type": "digital"
    }
  }
}
```

## Archive a price

Permanently retire a price. Archiving sets [`price.active`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html) to `false`, records [`price.archived_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html), and advances [`price.updated_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html). 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

- `price_id` — `string` — required — wire-only

  Identifier of the price to archive.

**Request — POST /prices/archive**

```bash
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"}'
```

```json
{
  "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": {
      "currency": "usd",
      "value": 2999
    },
    "product": {
      "id": "prod_abc123xyz789",
      "active": true,
      "created_at": "2026-02-13T01:45:00Z",
      "name": "Starter plan",
      "type": "digital"
    },
    "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 [`price.nominal`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html) amount, any associated product snapshot, and lifecycle timestamps; a standalone price omits [`price.product`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html).

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

### Request attributes

- `price_id` — `string` — required — wire-only

  The ID of the price to retrieve.

**Request — POST /prices/lookup**

```php
<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->prices->lookup("pr_k8m2x9v4n7p1");
```

```json
{
  "price": {
    "id": "pr_k8m2x9v4n7p1",
    "about": "Standard monthly subscription price",
    "active": true,
    "nominal": {
      "currency": "usd",
      "value": 2999
    },
    "created_at": "2026-02-13T02:00:00Z",
    "label": "Monthly",
    "product": {
      "id": "prod_abc123xyz789",
      "about": "Starter plan for solo businesses",
      "active": true,
      "attributes": [
        {
          "name": "tier",
          "value": "starter"
        }
      ],
      "category": "software",
      "created_at": "2026-02-13T01:45:00Z",
      "custom_data": {
        "plan": "starter"
      },
      "description": "Standard monthly subscription",
      "name": "Starter plan",
      "published_at": "2026-02-13T02:05:00Z",
      "reference": "plan-starter-monthly",
      "tax_code": "txcd_software",
      "type": "digital"
    }
  }
}
```

## 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 `product_id`, 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.

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

### Request attributes

- `page_number` — `integer` — wire-only

  1-based page index to fetch. Defaults to `1` when omitted.

- `page_size` — `integer` — wire-only

  Number of prices to return. Defaults to `256`. Must be between `1` and `256`.

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

  Optional product ID to scope the results to a single product.

**Request — POST /prices/page**

```php
<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->prices->page([
  'page_number' => 1,
  'page_size' => 2,
  'product_id' => 'prod_abc123xyz789',
]);
```

```json
{
  "page": {
    "number": 1,
    "size": 2,
    "prices": [
      {
        "id": "pr_k8m2x9v4n7p1",
        "about": "Standard monthly subscription price",
        "active": true,
        "nominal": {
          "currency": "usd",
          "value": 2999
        },
        "created_at": "2026-02-13T02:00:00Z",
        "label": "Monthly",
        "product": {
          "id": "prod_abc123xyz789",
          "about": "Starter plan for solo businesses",
          "active": true,
          "attributes": [
            {
              "name": "tier",
              "value": "starter"
            }
          ],
          "category": "software",
          "created_at": "2026-02-13T01:45:00Z",
          "custom_data": {
            "plan": "starter"
          },
          "description": "Standard monthly subscription",
          "name": "Starter plan",
          "published_at": "2026-02-13T02:05:00Z",
          "reference": "plan-starter-monthly",
          "tax_code": "txcd_software",
          "type": "digital"
        },
        "updated_at": "2026-02-13T04:10:00Z"
      },
      {
        "id": "pr_b1n9q2e5m6r7",
        "about": "Legacy promotional price",
        "active": false,
        "nominal": {
          "currency": "usd",
          "value": 2499
        },
        "archived_at": "2026-03-01T09:00:00Z",
        "created_at": "2026-01-10T08:00:00Z",
        "label": "Promo",
        "product": {
          "id": "prod_abc123xyz789",
          "about": "Starter plan for solo businesses",
          "active": true,
          "attributes": [
            {
              "name": "tier",
              "value": "starter"
            }
          ],
          "category": "software",
          "created_at": "2026-02-13T01:45:00Z",
          "custom_data": {
            "plan": "starter"
          },
          "description": "Standard monthly subscription",
          "name": "Starter plan",
          "published_at": "2026-02-13T02:05:00Z",
          "reference": "plan-starter-monthly",
          "tax_code": "txcd_software",
          "type": "digital"
        },
        "updated_at": "2026-03-01T09:00:00Z"
      }
    ]
  }
}
```

## Update a price

Update an existing price's descriptive fields. Only `about` and `label` are mutable. The product association and [`price.nominal`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html) 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 [`price.updated_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html).

### Request attributes

- `about` — `string` — wire-only

  Updated description. Max 500 characters.

- `label` — `string` — wire-only

  Updated display name. Max 100 characters.

- `price_id` — `string` — required — wire-only

  The ID of the price to update.

**Request — POST /prices/update**

```php
<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->prices->update([
  'price_id' => 'pr_k8m2x9v4n7p1',
  'label' => 'Monthly (discounted)',
  'about' => 'Promotional monthly rate for early adopters',
]);
```

```json
{
  "price": {
    "id": "pr_k8m2x9v4n7p1",
    "about": "Promotional monthly rate for early adopters",
    "active": true,
    "nominal": {
      "currency": "usd",
      "value": 2999
    },
    "created_at": "2026-02-13T02:00:00Z",
    "label": "Monthly (discounted)",
    "product": {
      "id": "prod_abc123xyz789",
      "about": "Starter plan for solo businesses",
      "active": true,
      "attributes": [
        {
          "name": "tier",
          "value": "starter"
        }
      ],
      "category": "software",
      "created_at": "2026-02-13T01:45:00Z",
      "custom_data": {
        "plan": "starter"
      },
      "description": "Standard monthly subscription",
      "name": "Starter plan",
      "published_at": "2026-02-13T02:05:00Z",
      "reference": "plan-starter-monthly",
      "tax_code": "txcd_software",
      "type": "digital"
    },
    "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 [`price.active`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html) to `true` and advances [`price.updated_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CatalogPrice.html).

Archived prices cannot be activated, and an already-active price returns a lifecycle conflict.

### Request attributes

- `price_id` — `string` — required — wire-only

  Price identifier to activate.

**Request — POST /prices/activate**

```php
<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->prices->activate("pr_k8m2x9v4n7p1");
```

```json
{
  "price": {
    "id": "pr_k8m2x9v4n7p1",
    "about": "Standard monthly subscription price",
    "active": true,
    "nominal": {
      "currency": "usd",
      "value": 2999
    },
    "created_at": "2026-02-13T02:00:00Z",
    "label": "Monthly",
    "product": {
      "id": "prod_abc123xyz789",
      "about": "Starter plan for solo businesses",
      "active": true,
      "attributes": [
        {
          "name": "tier",
          "value": "starter"
        }
      ],
      "category": "software",
      "created_at": "2026-02-13T01:45:00Z",
      "custom_data": {
        "plan": "starter"
      },
      "description": "Standard monthly subscription",
      "name": "Starter plan",
      "published_at": "2026-02-13T02:05:00Z",
      "reference": "plan-starter-monthly",
      "tax_code": "txcd_software",
      "type": "digital"
    },
    "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

- `price_id` — `string` — required — wire-only

  Price identifier to deactivate.

**Request — POST /prices/deactivate**

```php
<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->prices->deactivate("pr_k8m2x9v4n7p1");
```

```json
{
  "price": {
    "id": "pr_k8m2x9v4n7p1",
    "about": "Standard monthly subscription price",
    "active": false,
    "nominal": {
      "currency": "usd",
      "value": 2999
    },
    "created_at": "2026-02-13T02:00:00Z",
    "label": "Monthly",
    "product": {
      "id": "prod_abc123xyz789",
      "about": "Starter plan for solo businesses",
      "active": true,
      "attributes": [
        {
          "name": "tier",
          "value": "starter"
        }
      ],
      "category": "software",
      "created_at": "2026-02-13T01:45:00Z",
      "custom_data": {
        "plan": "starter"
      },
      "description": "Standard monthly subscription",
      "name": "Starter plan",
      "published_at": "2026-02-13T02:05:00Z",
      "reference": "plan-starter-monthly",
      "tax_code": "txcd_software",
      "type": "digital"
    },
    "updated_at": "2026-02-13T04:20:00Z"
  }
}
```