# Update a pricing header

Operation ID: `updateAccountingProductLinePricing`

Group: Accounting › Products › Product Lines

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/updateAccountingProductLinePricing)

`PATCH /accounting/products/{id}/product-lines/{productLineId}/pricing/{pricingId}`

Retry-safe: A write that accepts Idempotency-Key: repeating a request with the same key replays the stored answer instead of executing twice.

Updates a pricing header and its entries with the fields you send. A field you leave out keeps its current value. Entries change one by one: priceBookEntriesToCreate adds entries, priceBookEntriesToUpdate changes existing entries, and priceBookEntriesToDelete removes entries.

Use the pricing header's id, not its headerNumber.

A pricing header sets a product line's prices for one price book and currency over a date range. Each price is a price book entry on the pricing header.

A pricing header's validFrom and validTo must fall within the product's effective dates. Pricing headers on the same product line with the same price book and currency can't overlap in dates. You can't update a pricing header that a sales order line uses.

A request that breaks any of these conditions fails with VALIDATION_FAILED. The response is empty. Read the updated record with GET accounting/pricing/:id.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | string · v1 | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |
| `Idempotency-Key` | header | string | no | An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with `400 IDEMPOTENCY_NOT_SUPPORTED` rather than silently ignored. |
| `id` | path | string | yes | The unique identifier of the product the product line belongs to. |
| `productLineId` | path | string | yes | The unique identifier of the product line the pricing header belongs to. |
| `pricingId` | path | string | yes | The unique identifier of the pricing header you want to update. |

## Request body

Required, `application/json`: updateAccountingProductLinePricingInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `priceBookId` | string | no | The price book this header belongs to. See id on GET accounting/price-books/:id. |
| `currency` | string | no | The currency the header's prices are in. Format ISO 4217, for example 'USD'. |
| `validFrom` | date | no | The first date the header's prices are effective, inclusive. Use format YYYY-MM-DD. |
| `validTo` | date | no | The last date the header's prices are effective, inclusive. Use format YYYY-MM-DD. |
| `priceBookEntriesToCreate` | array<object> | no | The price book entries to add to the pricing header. For a product line priced 'tiered', 'volume', 'stairstep', or 'thresholdBased', each entry is one tier: a quantity range with its own price. A 'flat' or 'perUnit' line has one entry, and a 'rateCard' line has one entry per rate-card entry. |
| `priceBookEntriesToCreate[].listPrice` | decimal | no | The list price, in the header currency. Required when the product line is priced 'flat' or 'perUnit'. |
| `priceBookEntriesToCreate[].fromQuantity` | decimal | no | The lowest quantity in the tier, inclusive. Use only when the product line is priced 'tiered', 'volume', 'stairstep', or 'thresholdBased'. |
| `priceBookEntriesToCreate[].toQuantity` | decimal | no | The highest quantity in the tier, inclusive. Omit on the top tier, which has no upper limit. |
| `priceBookEntriesToCreate[].priceModel` | string | no | How the tier prices its quantity. Use only on a tier. Accepted values: 'flat', 'perUnit'. |
| `priceBookEntriesToCreate[].rateCardEntry` | object | no | The rate-card entry to attach. Provide only on rate-card-priced entries. |
| `priceBookEntriesToCreate[].rateCardEntry.billableComponentId` | string | no | The unique identifier of the billable component this rate-card entry prices. No endpoint returns billable components. |
| `priceBookEntriesToCreate[].rateCardEntry.unitOfMeasure` | string | yes | The unit the rate is quoted in. Accepted values: 'instance', 'gigabyte', 'terabyte', 'user', 'seat', 'minute', 'hour', 'day', 'month', 'each', 'license', 'activeUser', 'megabyte', 'message', 'text', 'platform', 'employee', 'personnel', 'credit', 'currency', 'package', 'case', 'word', 'record'. |
| `priceBookEntriesToCreate[].rateCardEntry.description` | string | no | A description of the rate-card entry. The description distinguishes the entry from other rate-card entries on the same billable component. |
| `priceBookEntriesToCreate[].rateCardEntry.usageType` | string | no | How usage is measured against this entry. Accepted values: 'consumption', 'overage', 'thresholdCounter', 'payg'. |
| `priceBookEntriesToCreate[].rateCardEntry.billableUnitOfMeasure` | string | no | The unit used when billing this entry. Accepted values: 'instance', 'gigabyte', 'terabyte', 'user', 'seat', 'minute', 'hour', 'day', 'month', 'each', 'license', 'activeUser', 'megabyte', 'message', 'text', 'platform', 'employee', 'personnel', 'credit', 'currency', 'package', 'case', 'word', 'record'. |
| `priceBookEntriesToCreate[].rateCardEntry.conversion` | decimal | no | The multiplier that converts unitOfMeasure quantities into billableUnitOfMeasure quantities. |
| `priceBookEntriesToCreate[].rateCardEntry.invoiceFrequency` | string | no | How often usage on this entry is invoiced. Accepted values: 'monthly', 'biMonthly', 'quarterly', 'semiAnnually', 'annually', 'once', 'custom', 'template', 'milestone', 'allAtOnce', 'termEnd'. |
| `priceBookEntriesToCreate[].rateCardEntry.priceModel` | string | no | How the rate-card entry's price is calculated. Accepted values: 'flat', 'perUnit', 'tiered', 'volume', 'stairstep', 'rateCard', 'thresholdBased'. |
| `priceBookEntriesToUpdate` | array<object> | no | Changes to existing price book entries of the pricing header. Only the fields you send change. |
| `priceBookEntriesToUpdate[].entryId` | string | yes | The unique identifier of the price book entry you want to update. The entry must belong to this pricing header, or the request fails with UNKNOWN_PRICE_BOOK_ENTRY_IDS. |
| `priceBookEntriesToUpdate[].listPrice` | decimal | no | The list price, in the header currency. |
| `priceBookEntriesToUpdate[].fromQuantity` | decimal | no | The lowest quantity in the tier, inclusive. Use only when the product line is priced 'tiered', 'volume', 'stairstep', or 'thresholdBased'. |
| `priceBookEntriesToUpdate[].toQuantity` | decimal | no | The highest quantity in the tier, inclusive. Use only when the product line is priced 'tiered', 'volume', 'stairstep', or 'thresholdBased'. |
| `priceBookEntriesToUpdate[].priceModel` | string | no | How the tier prices its quantity. Use only on a tier. Accepted values: 'flat', 'perUnit'. |
| `priceBookEntriesToUpdate[].rateCardEntry` | object | no | Changes to the entry's rate-card entry. Provide only on rate-card-priced entries. |
| `priceBookEntriesToUpdate[].rateCardEntry.rateCardEntryId` | string | yes | The unique identifier of the rate-card entry you want to update. The rate-card entry must belong to this price book entry, or the request fails with UNKNOWN_RATE_CARD_ENTRY_IDS. |
| `priceBookEntriesToUpdate[].rateCardEntry.billableComponentId` | string | no | The unique identifier of the billable component this rate-card entry prices. No endpoint returns billable components. |
| `priceBookEntriesToUpdate[].rateCardEntry.unitOfMeasure` | string | no | The unit the rate is quoted in. Accepted values: 'instance', 'gigabyte', 'terabyte', 'user', 'seat', 'minute', 'hour', 'day', 'month', 'each', 'license', 'activeUser', 'megabyte', 'message', 'text', 'platform', 'employee', 'personnel', 'credit', 'currency', 'package', 'case', 'word', 'record'. |
| `priceBookEntriesToUpdate[].rateCardEntry.description` | string | no | A description of the rate-card entry. The description distinguishes the entry from other rate-card entries on the same billable component. |
| `priceBookEntriesToUpdate[].rateCardEntry.usageType` | string | no | How usage is measured against this entry. Accepted values: 'consumption', 'overage', 'thresholdCounter', 'payg'. |
| `priceBookEntriesToUpdate[].rateCardEntry.billableUnitOfMeasure` | string | no | The unit used when billing this entry. Accepted values: 'instance', 'gigabyte', 'terabyte', 'user', 'seat', 'minute', 'hour', 'day', 'month', 'each', 'license', 'activeUser', 'megabyte', 'message', 'text', 'platform', 'employee', 'personnel', 'credit', 'currency', 'package', 'case', 'word', 'record'. |
| `priceBookEntriesToUpdate[].rateCardEntry.conversion` | decimal | no | The multiplier that converts unitOfMeasure quantities into billableUnitOfMeasure quantities. |
| `priceBookEntriesToUpdate[].rateCardEntry.invoiceFrequency` | string | no | How often usage on this entry is invoiced. Accepted values: 'monthly', 'biMonthly', 'quarterly', 'semiAnnually', 'annually', 'once', 'custom', 'template', 'milestone', 'allAtOnce', 'termEnd'. |
| `priceBookEntriesToUpdate[].rateCardEntry.priceModel` | string | no | How the rate-card entry's price is calculated. Accepted values: 'flat', 'perUnit', 'tiered', 'volume', 'stairstep', 'rateCard', 'thresholdBased'. |
| `priceBookEntriesToDelete` | array<string> | no | The unique identifiers of the price book entries to delete from the pricing header. Deleting an entry also deletes its rate-card entry. Each entry must belong to this pricing header, or the request fails with UNKNOWN_PRICE_BOOK_ENTRY_IDS. |

```json
{
  "priceBookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "currency": "<currency>",
  "validFrom": "2026-01-15",
  "validTo": "2026-01-15",
  "priceBookEntriesToCreate": [
    {
      "listPrice": "19.99",
      "fromQuantity": "19.99",
      "toQuantity": "19.99",
      "priceModel": "<priceModel>",
      "rateCardEntry": {
        "billableComponentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "unitOfMeasure": "<unitOfMeasure>",
        "description": "<description>",
        "usageType": "<usageType>",
        "billableUnitOfMeasure": "<billableUnitOfMeasure>",
        "conversion": "19.99",
        "invoiceFrequency": "<invoiceFrequency>",
        "priceModel": "<priceModel>"
      }
    }
  ],
  "priceBookEntriesToUpdate": [
    {
      "entryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "listPrice": "19.99",
      "fromQuantity": "19.99",
      "toQuantity": "19.99",
      "priceModel": "<priceModel>",
      "rateCardEntry": {
        "rateCardEntryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "billableComponentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "unitOfMeasure": "<unitOfMeasure>",
        "description": "<description>",
        "usageType": "<usageType>",
        "billableUnitOfMeasure": "<billableUnitOfMeasure>",
        "conversion": "19.99",
        "invoiceFrequency": "<invoiceFrequency>",
        "priceModel": "<priceModel>"
      }
    }
  ],
  "priceBookEntriesToDelete": [
    "<priceBookEntriesToDelete>"
  ]
}
```

## Response

`200` Success

```json
{
  "data": {},
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Response headers

- `Idempotency-Replayed` — Present and `true` only when this response replays a previously stored one for the same Idempotency-Key, rather than reflecting a live execution. Absent on a live response - never sent as `false`.

## Errors

| Code | Status |
| --- | --- |
| `INVALID_ID` | 400 |
| `NOT_FOUND` | 400 |
| `UNKNOWN_PRICE_BOOK_IDS` | 400 |
| `UNKNOWN_BILLABLE_COMPONENT_IDS` | 400 |
| `UNKNOWN_PRICE_BOOK_ENTRY_IDS` | 400 |
| `UNKNOWN_RATE_CARD_ENTRY_IDS` | 400 |
| `VALIDATION_FAILED` | 400 |
| `IDEMPOTENCY_KEY_CONFLICT` | 409 |
| `IDEMPOTENCY_PAYLOAD_MISMATCH` | 422 |

## Statuses

- `400` — Invalid request or business failure. Codes: INVALID_ID, NOT_FOUND, UNKNOWN_PRICE_BOOK_IDS, UNKNOWN_BILLABLE_COMPONENT_IDS, UNKNOWN_PRICE_BOOK_ENTRY_IDS, UNKNOWN_RATE_CARD_ENTRY_IDS, VALIDATION_FAILED
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `409` — The Idempotency-Key is still being processed by another request.
- `422` — The Idempotency-Key was already used with a different request payload.
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error