[Traits](https://oods-foundry.com/traits) / Priceable

# Priceable

Introduces monetization metadata with currency handling, pricing models, and billing cadence semantics.

Generated from @oods/foundry 0.10.1

- Group

  financial

- Maturity

  stable

- Contexts

  card, detail, list

## Fields it adds

| Field | Type | Required | Description |
| - | - | - | - |
| `unit_amount_cents` | `number` | yes | Base unit price expressed in the smallest currency denomination. |
| `currency` | `string` | yes | ISO currency code for the unit amount. |
| `pricing_model` | `string` | yes | Monetization model applied to the entity. |
| `billing_interval` | `string` | no | Billing cadence when pricing_model indicates recurring revenue. |
| `tax_behavior` | `string` (exclusive, inclusive) | yes | Defines whether taxes are included in the displayed price. |

## What it shows in each context

- [detail](https://oods-foundry.com/contexts/detail)

  `PriceSummary`

- [list](https://oods-foundry.com/contexts/list)

  `PriceBadge`

- [card](https://oods-foundry.com/contexts/card)

  `PriceBadge`

## Parameters

- `supportedCurrencies` `string[]`, required

  ISO currency codes permitted for pricing this entity.

- `defaultCurrency` `string`

  Currency preselected when authoring pricing information.

- `pricingModels` `string[]`, required

  Supported strategies describing how the entity is monetized.

- `billingIntervals` `string[]`

  Allowed billing cadences when the pricing model is subscription based.

- `taxBehavior` `string`

  Indicates whether prices are tax inclusive or exclusive.

## Objects that use it

- [Product](https://oods-foundry.com/objects/product)
- [Transaction](https://oods-foundry.com/objects/transaction)

## The trait file

`traits/financial/Priceable.trait.yaml`

```
trait:
  name: Priceable
  version: 1.0.0
  description: |
    Introduces monetization metadata with currency handling, pricing models, and billing cadence semantics.
  category: financial
  tags:
    - pricing
    - monetization
    - commerce
    - billing

parameters:
  - name: supportedCurrencies
    type: string[]
    required: true
    description: ISO currency codes permitted for pricing this entity.
    default:
      - USD
      - EUR
      - GBP
  - name: defaultCurrency
    type: string
    required: false
    description: Currency preselected when authoring pricing information.
    default: USD
    validation:
      enumFromParameter: supportedCurrencies
  - name: pricingModels
    type: string[]
    required: true
    description: Supported strategies describing how the entity is monetized.
    default:
      - one_time
      - subscription
      - usage_based
  - name: billingIntervals
    type: string[]
    required: false
    description: Allowed billing cadences when the pricing model is subscription based.
    default:
      - one_time
      - day
      - week
      - month
      - year
  - name: taxBehavior
    type: string
    required: false
    description: Indicates whether prices are tax inclusive or exclusive.
    default: exclusive
    validation:
      enum:
        - exclusive
        - inclusive

schema:
  unit_amount_cents:
    type: number
    required: true
    description: Base unit price expressed in the smallest currency denomination.
    validation:
      minimum: 0
  currency:
    type: string
    required: true
    description: ISO currency code for the unit amount.
    validation:
      enumFromParameter: supportedCurrencies
  pricing_model:
    type: string
    required: true
    description: Monetization model applied to the entity.
    validation:
      enumFromParameter: pricingModels
  billing_interval:
    type: string
    required: false
    description: Billing cadence when pricing_model indicates recurring revenue.
    validation:
      enumFromParameter: billingIntervals
  tax_behavior:
    type: string
    required: true
    description: Defines whether taxes are included in the displayed price.
    validation:
      enum:
        - exclusive
        - inclusive
    default: exclusive

semantics:
  unit_amount_cents:
    semantic_type: commerce.price.amount
    token_mapping: tokenMap(commerce.price.primary)
    ui_hints:
      minorUnits: 100
      component: CurrencyAmount
      currencyField: currency
  currency:
    semantic_type: commerce.price.currency
    token_mapping: tokenMap(commerce.currency.primary)
    ui_hints:
      component: CurrencyCode
      parameterSource: supportedCurrencies
  pricing_model:
    semantic_type: commerce.price.model
    token_mapping: tokenMap(commerce.pricing.model)
    ui_hints:
      component: PricingModelBadge
      parameterSource: pricingModels
  billing_interval:
    semantic_type: commerce.price.interval
    token_mapping: tokenMap(commerce.pricing.interval)
    ui_hints:
      component: BillingIntervalBadge
      parameterSource: billingIntervals
  tax_behavior:
    semantic_type: commerce.price.tax_behavior
    token_mapping: tokenMap(commerce.pricing.tax)
    ui_hints:
      component: TaxBehaviorTag

view_extensions:
  detail:
    - component: PriceSummary
      position: top
      props:
        amountField: unit_amount_cents
        currencyField: currency
        modelField: pricing_model
        intervalField: billing_interval
        taxBehaviorField: tax_behavior
  list:
    - component: PriceBadge
      props:
        amountField: unit_amount_cents
        currencyField: currency
  # s222-m03 (#2502 ruling 13): a card shows the price, as the row does. PriceCardMeta carries no amount (its contract),
  # so a Product card read "Price  Model: One Time  Interval: One Time" with no price.
  card:
    - component: PriceBadge
      position: after
      props:
        amountField: unit_amount_cents
        currencyField: currency

tokens:
  commerce.price.text: "var(--text-strong)"
  commerce.price.badge.bg: "var(--surface-accent)"
  commerce.pricing.model.text: "var(--text-default)"

dependencies: []

metadata:
  created: "2025-10-16"
  owners:
    - commerce@oods.systems
    - finance@oods.systems
  maturity: stable
  accessibility:
    keyboard: "n/a"
    screenreader: "Announces price, currency, billing interval, and tax behavior."
  regionsUsed:
    - detail
    - list
    - card
  examples:
    - Product
    - Subscription
  references:
    - "Trait Engine Spec v0.1 §2"
```