---
title: "Create a price"
canonical_url: "https://twominutebilling.com/help/developers/api-reference/catalog/create-a-price"
---
# Create a price

<api-operation method="POST" path="/v1/businesses/{biz}/prices">
<template v-slot:docs="">

## Path parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        biz
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      Business id (biz_…)
    </td>
  </tr>
</tbody>
</table>

## Headers

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Idempotency-Key
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Safely retry writes — repeats return the original response. If a write FAILED after it had already taken effect, that failure is what repeats: the key is spent, and a new attempt needs a new key.
    </td>
  </tr>
</tbody>
</table>

## Body

The request body is **required**.

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        grants_credit
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Credit this price grants. <code>
        {"kind":"pack", …}
      </code>
      
       on a one-time price: each paid invoice line grants <code>
        amount
      </code>
      
       × quantity (paid credit, active once the invoice is paid). <code>
        {"kind":"per_cycle", …}
      </code>
      
       on a recurring price: <code>
        amount
      </code>
      
       × item quantity of promotional credit each period, with optional rollover. Null grants nothing.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        grants_credit.kind
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The grants credit's kind. One of <code>
        pack
      </code>
      
      , <code>
        per_cycle
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        grants_credit.unit
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      A credit unit id. Null = money.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        grants_credit.amount
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      In the unit's smallest step (money: minor units).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        grants_credit.priority
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The grants credit's priority.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        grants_credit.expires_after
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Packs: the credit expires this many days after the invoice is paid.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        grants_credit.applicability
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Which invoice lines the grant may pay: <code>
        {"kind":"metered"}
      </code>
      
       (every usage line, the default), <code>
        {"kind":"prices","prices":["…"]}
      </code>
      
      , or <code>
        {"kind":"meters","meters":["…"]}
      </code>
      
       (meter keys: the usage lines of every price that bills the meter when the grant draws). A <code>
        metered
      </code>
      
       grant takes the business's <code>
        credit_config.credit_scope
      </code>
      
       when one is set.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        grants_credit.tax_treatment
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Packs: required, or the business default. <code>
        taxed_at_use
      </code>
      
       is money only. One of <code>
        taxed_at_purchase
      </code>
      
      , <code>
        taxed_at_use
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        grants_credit.on_exhausted
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      What happens when the credit is used up, for a business with blocking on. Null = not set here. One of <code>
        block
      </code>
      
      , <code>
        bill
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        grants_credit.rollover
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Per cycle: <code>
        none
      </code>
      
      , or <code>
        carry
      </code>
      
       floor(remaining × percent ÷ 100) units (optionally capped) into a grant that expires <code>
        expire_after_cycles
      </code>
      
       periods later (null = never).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        grants_credit.reset
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Per cycle: when the credits renew (absent = each term). Each window gets its own grant, which pays only the usage inside that window. Credits do not renew by the hour.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        grants_credit.first_window
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Per cycle, a calendar window that starts before the subscription: grant it in full, prorated, or wait for the first full window. Null = the business setting. One of <code>
        full
      </code>
      
      , <code>
        prorated
      </code>
      
      , <code>
        next_full_window
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        product
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The product's slug id.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        meter
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Bill from this meter's events. Models usage, tiered, volume or package. The usage aggregation is copied from the meter. Fixed after create.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        unit_amount_decimal
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The default rate: minor units per <code>
        quantity_divisor
      </code>
      
       units. A decimal string with at most 12 decimal places and no exponent, for example <code>
        "0.000125"
      </code>
      
      . "$3 per 1M tokens" is <code>
        "300"
      </code>
      
       with divisor 1000000.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        quantity_divisor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The rate is per this many units. Default 1.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        amount_source
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      <code>
        rate
      </code>
      
       (default): quantity × rate. <code>
        event_amount
      </code>
      
      : the sum of the events' <code>
        amount
      </code>
      
      . <code>
        event_cost
      </code>
      
      : the sum of <code>
        cost
      </code>
      
       × (1 + <code>
        markup_percent
      </code>
      
       ÷ 100). <code>
        model_price_list
      </code>
      
      : each combination at the selling rate: a fixed rate in <code>
        rates
      </code>
      
      , else its markup base × (1 + markup ÷ 100); a combination with no base bills <code>
        unit_amount_decimal
      </code>
      
      . <code>
        event_cost_or_list
      </code>
      
      : the events that carry a <code>
        cost
      </code>
      
       bill that cost × (1 + markup ÷ 100), on their own line; the events without one (or with a cost in another currency) bill as <code>
        model_price_list
      </code>
      
      ; a fixed rate for a combination wins over both. The last two: the usage model only, on a sum or count meter with a <code>
        price_list
      </code>
      
       mapping. One of <code>
        rate
      </code>
      
      , <code>
        event_amount
      </code>
      
      , <code>
        event_cost
      </code>
      
      , <code>
        model_price_list
      </code>
      
      , <code>
        event_cost_or_list
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        markup_percent
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      <code>
        event_cost
      </code>
      
      , <code>
        model_price_list
      </code>
      
       and <code>
        event_cost_or_list
      </code>
      
       only: a decimal percent, 0 or more, up to 6 decimal places.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        markup_base
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      <code>
        model_price_list
      </code>
      
       and <code>
        event_cost_or_list
      </code>
      
       only. <code>
        list
      </code>
      
       (default): the model price list, else your cost. <code>
        cost
      </code>
      
      : your cost, else the list. One of <code>
        list
      </code>
      
      , <code>
        cost
      </code>
      
      , <code>
        null
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        rates
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The rate card. A combination that no row names bills at the price's own rate.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        rates.match
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      Group values over some of the meter's <code>
        group_by
      </code>
      
      . The row naming the most values wins, then the oldest.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        rates.unit_amount_decimal
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Minor units per <code>
        quantity_divisor
      </code>
      
       units. A decimal string with at most 12 decimal places and no exponent, for example <code>
        "0.000125"
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        rates.markup_percent
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      <code>
        model_price_list
      </code>
      
       and <code>
        event_cost_or_list
      </code>
      
       only: percent over the price's markup base (and, for <code>
        event_cost_or_list
      </code>
      
      , over the events' own cost), in place of a fixed rate.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        rates.tiers
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Tiers in the price's model: <code>
        up_to
      </code>
      
      , <code>
        unit_amount_decimal
      </code>
      
      , <code>
        flat_amount_minor
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Slug id for the price. Omit and it is derived from the name, or from currency/interval/model. Immutable once set; a collision is a 409.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        external_name
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The name customers see, when it differs from <code>
        name
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      A description of the price.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        trial_end_action
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      What happens when this price's trial ends. One of <code>
        activate_subscription
      </code>
      
      , <code>
        cancel_subscription
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        billing_cycles
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      How many periods a subscription bills this price for; null bills until cancelled.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        free_quantity
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Units free in each billing period. They come off the quantity before the pricing model rates the remaining units. An item uses the value this price had when the item was attached, unless the item sets its own <code>
        free_quantity
      </code>
      
      . Flat and percentage prices do not use it.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        portal_min_quantity
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      For a per-unit plan price: the fewest seats a customer can select in the portal. Null = the business's portal seat minimum. Your team can set any quantity.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        portal_max_quantity
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      For a per-unit plan price: the most seats a customer can select in the portal. Null = the business's portal seat maximum.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        invoice_notes
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Stored with the price.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Your own key-value data.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Price label, e.g. "Monthly USD"
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        model
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The pricing model. One of <code>
        flat
      </code>
      
      , <code>
        per_unit
      </code>
      
      , <code>
        tiered
      </code>
      
      , <code>
        volume
      </code>
      
      , <code>
        stairstep
      </code>
      
      , <code>
        usage
      </code>
      
      , <code>
        package
      </code>
      
      , <code>
        percentage
      </code>
      
      , <code>
        graduated_percentage
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Whether the price recurs or is charged once. One of <code>
        recurring
      </code>
      
      , <code>
        one_time
      </code>
      
      . Defaults to <code>
        "recurring"
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        currency
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The price's currency (ISO-4217 code).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        amount_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Required for flat/per_unit/package
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        interval
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Required for recurring One of <code>
        day
      </code>
      
      , <code>
        week
      </code>
      
      , <code>
        month
      </code>
      
      , <code>
        year
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        interval_count
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Number of intervals between charges, e.g. 3 with <code>
        interval
      </code>
      
       = month charges every 3 months. Defaults to <code>
        1
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        usage_aggregation
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Bill measured usage. Allowed on usage, percentage, graduated_percentage, tiered, volume, stairstep and package prices; refused on flat and per_unit. Fixed after create. One of <code>
        sum
      </code>
      
      , <code>
        max
      </code>
      
      , <code>
        last
      </code>
      
      , <code>
        count
      </code>
      
      , <code>
        min
      </code>
      
      , <code>
        avg
      </code>
      
      , <code>
        unique
      </code>
      
      , <code>
        weighted_sum
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        usage_recurring
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Carry the measured level to the next period (seats, storage). Needs sum, last, max, unique or weighted_sum. A level that changes inside a period bills its peak (last bills the closing level). Fixed after create. Defaults to <code>
        false
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        usage_time_unit
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      weighted_sum only (default hour): usage is billed in unit-hours or unit-days, the level times the time it was held, rounded half-up once per period. Fixed after create. One of <code>
        hour
      </code>
      
      , <code>
        day
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tiers
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Required for tiered/volume/stairstep/graduated_percentage (stairstep uses each tier flatAmountMinor). Bounds must increase, and only the last tier, which must be unbounded, has a null upToMinor; otherwise 400. graduated_percentage tiers are over the money base in minor units: each takes rateBps of the part of the base inside it, plus flatAmountMinor once the base reaches it, rounded half-up once on the total.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tiers.upToMinor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Inclusive upper bound. The tier starts after the previous tier's bound (the first at 0). Null on the last tier only.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tiers.unitAmountMinor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The tier's unit amount minor.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tiers.flatAmountMinor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The tier's flat amount minor.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tiers.rateBps
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      graduated_percentage only: the rate inside the tier, in basis points.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        package_size
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Required for package: units per package
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        free_units
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      package/percentage: units (or base value) billed at 0 first
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        percentage_bps
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Required for percentage: rate in basis points (250 = 2.5%)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        minimum_amount_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Minimum spend for one billing period. When this price's line for a period is lower, period billing adds a true-up line for the difference, prorated on a partial period. Recurring prices only.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bill_usage_monthly
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Recurring plan prices with a billing period of 2 months or more only. New subscriptions on this price invoice metered usage every month, while the plan fee stays on the billing period. Default false.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        commitment_amount_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Recurring plan prices only. Minimum commitment for one full billing period. When the period ends, an invoice line bills the difference between it and the counted fees, prorated on a short period. New subscriptions copy it.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        trial_period
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Trial length, in <code>
        trial_period_unit
      </code>
      
      s. Omit for no trial.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        trial_period_unit
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Unit for <code>
        trial_period
      </code>
      
      . One of <code>
        day
      </code>
      
      , <code>
        week
      </code>
      
      , <code>
        month
      </code>
      
      , <code>
        year
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        show_description_in_invoices
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Whether the price's description is printed on invoices. Defaults to <code>
        false
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        show_description_in_quotes
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Stored and round-tripped; no quote renderer exists yet to honour it. Defaults to <code>
        false
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tax_code
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      HSN/SAC for this price (India GST). The finest level of price → product → business default_tax_code; null asks the product.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sku
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      SKU / alternative name. Descriptive metadata — no engine behaviour is keyed off it.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        accounting_code
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Accounting code ("Account Name"). Descriptive metadata — NOT resolved against our ledger accounts.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        accounting_category_code
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Accounting category code ("Class"). Descriptive metadata.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        is_taxable
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      false → this price's lines are excluded from tax (reason product_exempt) Defaults to <code>
        true
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tax_behavior
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      inclusive → the price already includes tax (backed out); exclusive → tax added on top One of <code>
        inclusive
      </code>
      
      , <code>
        exclusive
      </code>
      
      . Defaults to <code>
        "exclusive"
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

## Response

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        grants_credit
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Credit this price grants. <code>
        {"kind":"pack", …}
      </code>
      
       on a one-time price: each paid invoice line grants <code>
        amount
      </code>
      
       × quantity (paid credit, active once the invoice is paid). <code>
        {"kind":"per_cycle", …}
      </code>
      
       on a recurring price: <code>
        amount
      </code>
      
       × item quantity of promotional credit each period, with optional rollover. Null grants nothing.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        meter
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Bill from this meter's events. Models usage, tiered, volume or package. The usage aggregation is copied from the meter. Fixed after create.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        unit_amount_decimal
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The default rate: minor units per <code>
        quantity_divisor
      </code>
      
       units. A decimal string with at most 12 decimal places and no exponent, for example <code>
        "0.000125"
      </code>
      
      . "$3 per 1M tokens" is <code>
        "300"
      </code>
      
       with divisor 1000000.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        quantity_divisor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      The rate is per this many units. Default 1.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        amount_source
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        rate
      </code>
      
       (default): quantity × rate. <code>
        event_amount
      </code>
      
      : the sum of the events' <code>
        amount
      </code>
      
      . <code>
        event_cost
      </code>
      
      : the sum of <code>
        cost
      </code>
      
       × (1 + <code>
        markup_percent
      </code>
      
       ÷ 100). <code>
        model_price_list
      </code>
      
      : each combination at the selling rate: a fixed rate in <code>
        rates
      </code>
      
      , else its markup base × (1 + markup ÷ 100); a combination with no base bills <code>
        unit_amount_decimal
      </code>
      
      . <code>
        event_cost_or_list
      </code>
      
      : the events that carry a <code>
        cost
      </code>
      
       bill that cost × (1 + markup ÷ 100), on their own line; the events without one (or with a cost in another currency) bill as <code>
        model_price_list
      </code>
      
      ; a fixed rate for a combination wins over both. The last two: the usage model only, on a sum or count meter with a <code>
        price_list
      </code>
      
       mapping. One of <code>
        rate
      </code>
      
      , <code>
        event_amount
      </code>
      
      , <code>
        event_cost
      </code>
      
      , <code>
        model_price_list
      </code>
      
      , <code>
        event_cost_or_list
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        markup_percent
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        event_cost
      </code>
      
      , <code>
        model_price_list
      </code>
      
       and <code>
        event_cost_or_list
      </code>
      
       only: a decimal percent, 0 or more, up to 6 decimal places.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        markup_base
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        model_price_list
      </code>
      
       and <code>
        event_cost_or_list
      </code>
      
       only. <code>
        list
      </code>
      
       (default): the model price list, else your cost. <code>
        cost
      </code>
      
      : your cost, else the list. One of <code>
        list
      </code>
      
      , <code>
        cost
      </code>
      
      , <code>
        null
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        rates
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      The rate card. A combination that no row names bills at the price's own rate.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The object type.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The price's id (<code>
        pro-monthly-usd
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        product
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The product this price belongs to (a slug id, e.g. <code>
        pro
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The price's name.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        model
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The pricing model.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Whether the price recurs or is charged once.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        currency
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The price's currency (ISO-4217 code).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        amount_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      The amount in minor units (integer), e.g. 2900 = $29.00.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        minimum_amount_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Minimum spend for one billing period, or null.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bill_usage_monthly
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      New subscriptions on this price invoice metered usage every month.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        commitment_amount_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Minimum commitment for one full billing period, or null.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        interval
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The billing interval of a recurring price.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        usage_aggregation
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      How usage in a period is combined, or null for a fixed price.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        usage_recurring
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      The measured level carries into later periods.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        usage_time_unit
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The unit of a weighted_sum quantity, or null. One of <code>
        hour
      </code>
      
      , <code>
        day
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metered
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      The price bills measured usage in arrears, not a fixed quantity.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        is_taxable
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Whether tax applies to this price.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tax_behavior
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Whether the price includes tax or tax is added on top.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        show_description_in_invoices
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Whether the price's description is printed on invoices.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        show_description_in_quotes
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Stored and round-tripped; no quote renderer exists yet to honour it.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tax_code
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      HSN/SAC for this price (India GST). Null falls through to the product’s, then the business default_tax_code.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sku
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      SKU. Descriptive metadata — the engine reads it nowhere.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        accounting_code
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Accounting code (“Account Name”). Descriptive metadata — NOT a ledger account reference.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        accounting_category_code
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Accounting category code (“Class”). Descriptive metadata.
    </td>
  </tr>
</tbody>
</table>

## Status codes

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        201
      </code>
    </td>
    
    <td>
      Created
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        400
      </code>
    </td>
    
    <td>
      Invalid body
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        404
      </code>
    </td>
    
    <td>
      No such product
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        409
      </code>
    </td>
    
    <td>
      Price id already in use
    </td>
  </tr>
</tbody>
</table>
</template>

<template v-slot:request="">

```bash [Request]
curl -X POST "$TMBILLING_URL/v1/businesses/biz_XXXXXXXXXXXX01/prices" \
  -H "Authorization: Bearer $TMBILLING_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "pro",
    "description": "Everything a growing team needs.",
    "name": "Monthly",
    "model": "flat",
    "currency": "USD",
    "amount_minor": 2900
  }'
```

</template>

<template v-slot:response="">
<code-group>

```json [201 Created]
{
  "grants_credit": {
    "kind": "pack",
    "unit": "seat",
    "amount": 2900,
    "priority": 1,
    "expires_after": {
      "days": 14
    },
    "applicability": {
      "kind": "metered"
    },
    "tax_treatment": "taxed_at_purchase",
    "on_exhausted": "block",
    "rollover": {
      "mode": "none",
      "percent": 10,
      "cap": 1,
      "expire_after_cycles": 1
    },
    "reset": {
      "every": "hour"
    },
    "first_window": "full"
  },
  "meter": "ai_tokens",
  "unit_amount_decimal": "300",
  "quantity_divisor": 1000000,
  "amount_source": "rate",
  "markup_percent": "20",
  "markup_base": "list",
  "rates": [
    {
      "match": {
        "model": "large-v2",
        "token_type": "output"
      }
    }
  ],
  "object": "price",
  "id": "pro-monthly-usd",
  "product": "pro",
  "name": "Pro monthly",
  "model": "flat",
  "type": "recurring",
  "currency": "USD",
  "amount_minor": 2900,
  "minimum_amount_minor": 2900,
  "bill_usage_monthly": false,
  "commitment_amount_minor": 2900,
  "interval": "month",
  "usage_aggregation": "Usage aggregation",
  "usage_recurring": false,
  "usage_time_unit": "hour",
  "metered": false,
  "is_taxable": false,
  "tax_behavior": "exclusive",
  "show_description_in_invoices": false,
  "show_description_in_quotes": false,
  "tax_code": "998314",
  "sku": "PRO-M",
  "accounting_code": "welcome-10",
  "accounting_category_code": "welcome-10"
}
```

```json [400 Bad Request]
{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid body"
  }
}
```

```json [404 Not Found]
{
  "error": {
    "type": "invalid_request_error",
    "message": "No such product"
  }
}
```

```json [409 Conflict]
{
  "error": {
    "type": "conflict_error",
    "message": "Price id already in use"
  }
}
```

</code-group>
</template>
</api-operation>


## Sitemap

See the full [sitemap](https://twominutebilling.com/sitemap.md) for all pages.