Add pricing headers to a product line

Operation ID: createAccountingProductLinePricing

Group: Accounting › Products › Product Lines

Open in the interactive reference

POST /accounting/products/{id}/product-lines/{productLineId}/pricing

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

Adds pricing headers to a product line. 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. A request that breaks either condition fails with VALIDATION_FAILED.

If any pricing header can't be created, none are. The response contains only the new pricing headers' ids. Read a pricing header 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 you want to add pricing to.

Request body

Required, application/json: createAccountingProductLinePricingInput.

Field Type Required Description
headers array<object> yes The pricing headers to create for the product line.
headers[].priceBookId string yes The price book this header belongs to. See id on GET accounting/price-books/:id.
headers[].currency string yes The currency the header's prices are in. Format ISO 4217, for example 'USD'.
headers[].validFrom date yes The first date the header's prices are effective, inclusive. Use format YYYY-MM-DD.
headers[].validTo date no The last date the header's prices are effective, inclusive. Use format YYYY-MM-DD. Omit for a header with no end date.
headers[].priceBookEntries array<object> yes The price book entries of 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.
headers[].priceBookEntries[].listPrice decimal no The list price, in the header currency. Required when the product line is priced 'flat' or 'perUnit'.
headers[].priceBookEntries[].fromQuantity decimal no The lowest quantity in the tier, inclusive. Use only when the product line is priced 'tiered', 'volume', 'stairstep', or 'thresholdBased'.
headers[].priceBookEntries[].toQuantity decimal no The highest quantity in the tier, inclusive. Omit on the top tier, which has no upper limit.
headers[].priceBookEntries[].priceModel string no How the tier prices its quantity. Use only on a tier. Accepted values: 'flat', 'perUnit'.
headers[].priceBookEntries[].rateCardEntry object no The rate-card entry to attach. Provide only on rate-card-priced entries.
headers[].priceBookEntries[].rateCardEntry.billableComponentId string no The unique identifier of the billable component this rate-card entry prices. No endpoint returns billable components.
headers[].priceBookEntries[].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'.
headers[].priceBookEntries[].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.
headers[].priceBookEntries[].rateCardEntry.usageType string no How usage is measured against this entry. Accepted values: 'consumption', 'overage', 'thresholdCounter', 'payg'.
headers[].priceBookEntries[].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'.
headers[].priceBookEntries[].rateCardEntry.conversion decimal no The multiplier that converts unitOfMeasure quantities into billableUnitOfMeasure quantities.
headers[].priceBookEntries[].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'.
headers[].priceBookEntries[].rateCardEntry.priceModel string no How the rate-card entry's price is calculated. Accepted values: 'flat', 'perUnit', 'tiered', 'volume', 'stairstep', 'rateCard', 'thresholdBased'. 
{
  "headers": [
    {
      "priceBookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "currency": "<currency>",
      "validFrom": "2026-01-15",
      "validTo": "2026-01-15",
      "priceBookEntries": [
        {
          "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>"
          }
        }
      ]
    }
  ]
}

Response

200 Success

Under data (createAccountingProductLinePricingOutput):

Field Type Required Description
createdPricingHeaderIds array<string> yes The unique identifiers for the created pricing headers, in the order you sent them. 
{
  "data": {
    "createdPricingHeaderIds": [
      "<createdPricingHeaderIds>"
    ]
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Response headers

Errors

Code Status
INVALID_ID 400
NOT_FOUND 400
UNKNOWN_PRICE_BOOK_IDS 400
UNKNOWN_BILLABLE_COMPONENT_IDS 400
VALIDATION_FAILED 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses