Creates a product.

POST /accounting/products

Group: Accounting › Products · Operation ID: createAccountingProduct

A productCode that another product already uses fails with DUPLICATE_PRODUCT_CODE, which names the id of the product that already has it. The whole call runs as one transaction, so any failure writes nothing. The response contains only the new product's id. Read the record with GET accounting/products/:id.

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "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.

Request body

Required, application/json: createAccountingProductInput.

Field Type Required Description
productName string yes The product's display name.
productCode string yes The product's code, unique within the tenant. A code another product already uses fails with DUPLICATE_PRODUCT_CODE.
effectiveStartDate string (date) yes The date the product becomes available. Use format YYYY-MM-DD.
effectiveEndDate string (date) no The date the product is no longer available. Use format YYYY-MM-DD. Omit for a product with no end date.
productFamily string no The product family. Accepted values: 'software', 'services', 'physicalProducts'.
productType string no The product type. Accepted values: 'sub', 'termLicense', 'support', 'professionalServices', 'training', 'usage', 'billableTravelExpense', 'bundle', 'hardwareConsumables', 'billablePassThrough', 'merchandise', 'shipping'.
description string no A description of the product shown to customers.
internalDescription string no A description of the product for internal use, not shown to customers.
crmProductId string no The product's identifier in an external CRM system.
isInventory boolean no Whether the product is tracked as inventory. Defaults to false.
itemIds array of string no The inventory items to link to this product. Used only when isInventory is true. There is no endpoint for inventory items.
entityId string no The legal entity this product is scoped to. See id on GET base/entities. Omit to default to your current entity when entity-based visibility is enabled, otherwise the product is shared across all entities.
productLines array of object no The product lines to create with this product, each with optional pricing. A 'prepaid' line also creates a paired 'usage' line, with that line's pricing supplied in priceBookHeadersForUsage.
productLines[].lineType string yes The type of product line. Accepted values: 'recurring', 'oneTime', 'usage', 'prepaid', 'billableTime', 'billableTravelExpense', 'billablePassThrough'. 'commitWithOverage' is not supported and fails with UNSUPPORTED_LINE_TYPE.
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 is enforced on the product line. When true, sales transactions cannot override it.
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 reconciles it at renewal. 'overage' switches to pay-as-you-go invoicing when the balance reaches 0.
productLines[].prepaidBalanceRolloverAtRenewal boolean no Whether the remaining prepaid balance rolls over at renewal.
productLines[].crmProductId string no The product line's identifier in an external CRM system.
productLines[].dataSource string no The upstream system or import job that produced the product line, for example 'Salesforce', 'NetSuite' or 'Stripe'.
productLines[].productLineTaxes array of 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 of 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 string (date) yes The first date the header's prices are effective, inclusive. Use format YYYY-MM-DD.
productLines[].priceBookHeadersToCreate[].validTo string (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 of object yes
productLines[].priceBookHeadersToCreate[].priceBookEntries[].listPrice string (decimal) no The list price, in the header currency. Required except on tiered and rate-card entries.
productLines[].priceBookHeadersToCreate[].priceBookEntries[].fromQuantity string (decimal) no The inclusive lower bound of the tier's quantity range. Provide only on tiered entries.
productLines[].priceBookHeadersToCreate[].priceBookEntries[].toQuantity string (decimal) no The inclusive upper bound of the tier's quantity range. Omit on the top tier, which has no upper bound.
productLines[].priceBookHeadersToCreate[].priceBookEntries[].priceModel string no How the tier prices quantity. Provide only on tiered entries. 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 billable component this rate-card entry prices. There is no endpoint for it.
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 free-form qualifier that distinguishes this rate-card entry from others on the same billable component.
productLines[].priceBookHeadersToCreate[].priceBookEntries[].rateCardEntry.usageType string no How usage is measured against this entry. Accepted values: 'consumption', 'overage', 'thresholdCounter'.
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 string (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 computes a price. Accepted values: 'flat', 'perUnit', 'tiered', 'volume', 'stairstep', 'rateCard', 'thresholdBased'.
productLines[].priceBookHeadersForUsage array of object no The pricing for the auto-created paired usage line. Provide only when lineType is 'prepaid' or priceModel is 'thresholdBased'. Otherwise it is ignored.
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 string (date) yes The first date the header's prices are effective, inclusive. Use format YYYY-MM-DD.
productLines[].priceBookHeadersForUsage[].validTo string (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 of object yes The rate-card entries on the usage-line header. Usage-line pricing is always rate-card based.
productLines[].priceBookHeadersForUsage[].rateCardEntries[].billableComponentId string no The billable component this rate-card entry prices. There is no endpoint for it.
productLines[].priceBookHeadersForUsage[].rateCardEntries[].usageType string yes How usage is measured against this entry. Accepted values: 'consumption', 'overage', 'thresholdCounter'.
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 string (decimal) no The multiplier that converts unitOfMeasure quantities into billableUnitOfMeasure quantities.
productLines[].priceBookHeadersForUsage[].rateCardEntries[].listPrice string (decimal) no The list price for this rate-card entry, in the price book currency.

Example:

{
  "productName": "<productName>",
  "productCode": "<productCode>",
  "effectiveStartDate": "2026-01-15",
  "effectiveEndDate": "2026-01-15",
  "productFamily": "<productFamily>",
  "productType": "<productType>",
  "description": "<description>",
  "internalDescription": "<internalDescription>",
  "crmProductId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "isInventory": true,
  "itemIds": [
    "<itemIds>"
  ],
  "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "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 (createAccountingProductOutput):

Field Type Required Description
id string yes The unique identifier for the created product.

Response headers

Errors

Code Status
INVALID_ID 400
DUPLICATE_PRODUCT_CODE 400
UNKNOWN_ITEM_IDS 400
UNKNOWN_ENTITY_ID 400
UNKNOWN_PRICE_BOOK_IDS 400
UNKNOWN_BILLABLE_COMPONENT_IDS 400
UNKNOWN_TAX_ENTITY_IDS 400
UNSUPPORTED_LINE_TYPE 400
VALIDATION_FAILED 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses