# Add product lines to a product

Operation ID: `addAccountingProductLines`

Group: Accounting › Products › Product Lines

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

`POST /accounting/products/{id}/product-lines`

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

Adds one or more product lines, each with optional pricing and tax records, to an existing product in a single request. If any product line can't be added, none are.

The response contains only the ids of the created product lines, in the order you sent them. Read each product line with GET accounting/product-lines/:id.

A 'prepaid' line, or a 'recurring' line priced 'thresholdBased', also creates a paired 'usage' line whose id is not returned. To find the paired 'usage' line, use POST accounting/product-lines/search with filters.parentProductLineId set to the parent line's 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 you want to add product lines to. |

## Request body

Required, `application/json`: addAccountingProductLinesInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `productLines` | array<object> | yes | The product lines to create, each with optional pricing. A 'prepaid' line, or a 'recurring' line whose priceModel is 'thresholdBased', also creates a paired 'usage' line. Provide the pricing of the paired 'usage' line in priceBookHeadersForUsage. |
| `productLines[].lineType` | string | yes | The type of product line. Accepted values: 'recurring', 'oneTime', 'prepaid', 'billableTime', 'billableTravelExpense', 'billablePassThrough'. 'usage' is not accepted and fails with UNSUPPORTED_LINE_TYPE, because 'usage' lines are only created automatically with their parent line. 'commitWithOverage' is not supported and fails with VALIDATION_FAILED. |
| `productLines[].priceModel` | string | yes | How the product line is priced. Accepted values: 'flat', 'perUnit', 'tiered', 'volume', 'stairstep', 'rateCard', 'thresholdBased'. |
| `productLines[].unitOfMeasure` | string | yes | The unit the product line's quantities are measured 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'. |
| `productLines[].name` | string | no | A name for the product line. Omit to have one generated. |
| `productLines[].pricingTerm` | string | no | The pricing term of the product line. Accepted values: 'monthly', 'biMonthly', 'once', 'quarterly', 'semiAnnually', 'annually'. |
| `productLines[].enforceListPrice` | boolean | no | Whether the list price of the product line is enforced. When true, the list price comes from the price book and can't be changed on a sales order, a quote, or a subscription change. An unset value counts as true. |
| `productLines[].invoiceFrequency` | string | no | How often the product line is invoiced. Accepted values: 'monthly', 'biMonthly', 'quarterly', 'semiAnnually', 'annually', 'once', 'custom', 'template', 'milestone', 'allAtOnce', 'termEnd'. |
| `productLines[].prepaidBalanceOverConsumptionBehavior` | string | no | What happens when usage exceeds the prepaid balance. Accepted values: 'allowNegative', 'overage'. 'allowNegative' lets the balance go negative and takes the shortfall from the new prepaid amount at renewal. 'overage' stops the balance at 0 and invoices further usage at the line's overage rate. Defaults to 'allowNegative' on a 'prepaid' line. |
| `productLines[].prepaidBalanceRolloverAtRenewal` | boolean | no | Whether the remaining prepaid balance rolls over at renewal. Defaults to true on a 'prepaid' line. |
| `productLines[].crmProductId` | string | no | The product line's identifier in an external CRM system. |
| `productLines[].dataSource` | string | no | The source system or import job that produced the product line. Examples: 'Salesforce', 'NetSuite', 'Stripe'. |
| `productLines[].productLineTaxes` | array<object> | no | The tax records to attach to the product line. Provide only when a tax provider is configured. |
| `productLines[].productLineTaxes[].taxCode` | string | yes | The tax code, as defined by the configured tax provider. |
| `productLines[].productLineTaxes[].entityId` | string | yes | The legal entity this tax record applies under. See id on GET base/entities. |
| `productLines[].productLineTaxes[].engine` | string | yes | The tax engine that computes this tax. Accepted values: 'avalara', 'anrok', 'everestTaxEngine', 'manualTax', 'none'. |
| `productLines[].productLineTaxes[].country` | string | no | The country the tax record applies in. Format ISO 3166-1, for example 'US'. |
| `productLines[].priceBookHeadersToCreate` | array<object> | no | The pricing headers to create for the product line. |
| `productLines[].priceBookHeadersToCreate[].priceBookId` | string | yes | The price book this header belongs to. See id on GET accounting/price-books/:id. |
| `productLines[].priceBookHeadersToCreate[].currency` | string | yes | The currency the header's prices are in. Format ISO 4217, for example 'USD'. |
| `productLines[].priceBookHeadersToCreate[].validFrom` | date | yes | The first date the header's prices are effective, inclusive. Use format YYYY-MM-DD. |
| `productLines[].priceBookHeadersToCreate[].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. |
| `productLines[].priceBookHeadersToCreate[].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. |
| `productLines[].priceBookHeadersToCreate[].priceBookEntries[].listPrice` | decimal | no | The list price, in the header currency. Required when the product line is priced 'flat' or 'perUnit'. |
| `productLines[].priceBookHeadersToCreate[].priceBookEntries[].fromQuantity` | decimal | no | The lowest quantity in the tier, inclusive. Use only when the product line is priced 'tiered', 'volume', 'stairstep', or 'thresholdBased'. |
| `productLines[].priceBookHeadersToCreate[].priceBookEntries[].toQuantity` | decimal | no | The highest quantity in the tier, inclusive. Omit on the top tier, which has no upper limit. |
| `productLines[].priceBookHeadersToCreate[].priceBookEntries[].priceModel` | string | no | How the tier prices its quantity. Use only on a tier. Accepted values: 'flat', 'perUnit'. |
| `productLines[].priceBookHeadersToCreate[].priceBookEntries[].rateCardEntry` | object | no | The rate-card entry to attach. Provide only on rate-card-priced entries. |
| `productLines[].priceBookHeadersToCreate[].priceBookEntries[].rateCardEntry.billableComponentId` | string | no | The unique identifier of the billable component this rate-card entry prices. No endpoint returns billable components. |
| `productLines[].priceBookHeadersToCreate[].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'. |
| `productLines[].priceBookHeadersToCreate[].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. |
| `productLines[].priceBookHeadersToCreate[].priceBookEntries[].rateCardEntry.usageType` | string | no | How usage is measured against this entry. Accepted values: 'consumption', 'overage', 'thresholdCounter', 'payg'. |
| `productLines[].priceBookHeadersToCreate[].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'. |
| `productLines[].priceBookHeadersToCreate[].priceBookEntries[].rateCardEntry.conversion` | decimal | no | The multiplier that converts unitOfMeasure quantities into billableUnitOfMeasure quantities. |
| `productLines[].priceBookHeadersToCreate[].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'. |
| `productLines[].priceBookHeadersToCreate[].priceBookEntries[].rateCardEntry.priceModel` | string | no | How the rate-card entry's price is calculated. Accepted values: 'flat', 'perUnit', 'tiered', 'volume', 'stairstep', 'rateCard', 'thresholdBased'. |
| `productLines[].priceBookHeadersForUsage` | array<object> | no | The pricing for the paired 'usage' line that the API creates. Provide only when lineType is 'prepaid', or when lineType is 'recurring' and priceModel is 'thresholdBased'. On any other line the request fails with USAGE_PRICING_NOT_APPLICABLE. |
| `productLines[].priceBookHeadersForUsage[].priceBookId` | string | yes | The price book this header belongs to. See id on GET accounting/price-books/:id. |
| `productLines[].priceBookHeadersForUsage[].currency` | string | yes | The currency the header's prices are in. Format ISO 4217, for example 'USD'. |
| `productLines[].priceBookHeadersForUsage[].validFrom` | date | yes | The first date the header's prices are effective, inclusive. Use format YYYY-MM-DD. |
| `productLines[].priceBookHeadersForUsage[].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. |
| `productLines[].priceBookHeadersForUsage[].rateCardEntries` | array<object> | yes | The rate-card entries on the header. Pricing of a 'usage' line is always rate-card based. |
| `productLines[].priceBookHeadersForUsage[].rateCardEntries[].billableComponentId` | string | no | The unique identifier of the billable component this rate-card entry prices. No endpoint returns billable components. |
| `productLines[].priceBookHeadersForUsage[].rateCardEntries[].usageType` | string | yes | How usage is measured against this entry. Accepted values: 'consumption', 'overage', 'thresholdCounter', 'payg'. |
| `productLines[].priceBookHeadersForUsage[].rateCardEntries[].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'. |
| `productLines[].priceBookHeadersForUsage[].rateCardEntries[].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'. |
| `productLines[].priceBookHeadersForUsage[].rateCardEntries[].conversion` | decimal | no | The multiplier that converts unitOfMeasure quantities into billableUnitOfMeasure quantities. |
| `productLines[].priceBookHeadersForUsage[].rateCardEntries[].listPrice` | decimal | no | The list price for this rate-card entry, in the header currency. |

```json
{
  "productLines": [
    {
      "lineType": "<lineType>",
      "priceModel": "<priceModel>",
      "unitOfMeasure": "<unitOfMeasure>",
      "name": "<name>",
      "pricingTerm": "<pricingTerm>",
      "enforceListPrice": true,
      "invoiceFrequency": "<invoiceFrequency>",
      "prepaidBalanceOverConsumptionBehavior": "<prepaidBalanceOverConsumptionBehavior>",
      "prepaidBalanceRolloverAtRenewal": true,
      "crmProductId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "dataSource": "<dataSource>",
      "productLineTaxes": [
        {
          "taxCode": "<taxCode>",
          "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "engine": "<engine>",
          "country": "<country>"
        }
      ],
      "priceBookHeadersToCreate": [
        {
          "priceBookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "currency": "<currency>",
          "validFrom": "2026-01-15",
          "validTo": "2026-01-15",
          "priceBookEntries": [
            {
              "listPrice": null,
              "fromQuantity": null,
              "toQuantity": null,
              "priceModel": null,
              "rateCardEntry": null
            }
          ]
        }
      ],
      "priceBookHeadersForUsage": [
        {
          "priceBookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "currency": "<currency>",
          "validFrom": "2026-01-15",
          "validTo": "2026-01-15",
          "rateCardEntries": [
            {
              "billableComponentId": null,
              "usageType": null,
              "unitOfMeasure": null,
              "billableUnitOfMeasure": null,
              "conversion": null,
              "listPrice": null
            }
          ]
        }
      ]
    }
  ]
}
```

## Response

`200` Success

Under `data` (addAccountingProductLinesOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `createdProductLineIds` | array<string> | yes | The unique identifiers for the created product lines, in the same order as productLines. The 'usage' lines created alongside 'prepaid' or threshold-based lines are not included. |

```json
{
  "data": {
    "createdProductLineIds": [
      "<createdProductLineIds>"
    ]
  },
  "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_TAX_ENTITY_IDS` | 400 |
| `UNSUPPORTED_LINE_TYPE` | 400 |
| `USAGE_PRICING_NOT_APPLICABLE` | 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_TAX_ENTITY_IDS, UNSUPPORTED_LINE_TYPE, USAGE_PRICING_NOT_APPLICABLE, 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