> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Write a product's usage values

> Writes up to 1000 rows, each one account's values for one date: `values` maps the product's dimension keys to values (null deletes one; keys not sent are kept). `match` says what `account` is: `id` (default), `crm_account_id` (either Salesforce form) or `domain` (an account's domain or alias). Each row is checked on its own: a row with a problem (for example, an account not found; a domain several accounts share, or a CRM id a deleted account holds, whose `details` list the accounts; a key that is not one of the product's dimensions, or whose type this API does not write; a value of the wrong kind; an account and period an earlier row names, the earlier row being written) is not written and carries its error, and the others are written in one transaction. Answers 200 listing every row. A whole call is one write against the rate limits, and sending it again is safe. A product the app shows by pillar is a 409, as is a write that waited too long on another write to the product or its dates (send it again). Usage values are what a product's dimensions measure, per account and date, at the product's period (its `period`; the app shows usage at no other, and a product with none set shows at MONTHLY). A write moves a date to its period's first day: for WEEKLY, the weekday the product's latest weekly row falls on (Monday when it has none); the 1st for MONTHLY; the first day of the quarter for QUARTERLY (in the product's quarter cycle; calendar quarters when it has no rows), and January 1 for YEARLY; DAILY and SINGLE keep the date sent. An account has one row per date here: where data feeds stored several (older rows, or a CSV feed set to allow multiple rows per customer), the one written and listed is the row the feeds write today, else the oldest, while the app shows them all. A product with no display settings, or a period this API does not know, is a 409.



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/products/{product_id}/usage
openapi: 3.1.0
info:
  description: >-
    The agent-first Statisfy API. Authenticate with an API key (`Authorization:
    Bearer stfy_live_…`), then call `GET /v1/meta/capabilities` to discover
    every operation and its schemas.
  title: Statisfy API
  version: 1.0.0
servers:
  - url: https://api.statisfy.com
    description: Production
security: []
paths:
  /v1/products/{product_id}/usage:
    post:
      tags:
        - usage
      summary: Write a product's usage values
      description: >-
        Writes up to 1000 rows, each one account's values for one date: `values`
        maps the product's dimension keys to values (null deletes one; keys not
        sent are kept). `match` says what `account` is: `id` (default),
        `crm_account_id` (either Salesforce form) or `domain` (an account's
        domain or alias). Each row is checked on its own: a row with a problem
        (for example, an account not found; a domain several accounts share, or
        a CRM id a deleted account holds, whose `details` list the accounts; a
        key that is not one of the product's dimensions, or whose type this API
        does not write; a value of the wrong kind; an account and period an
        earlier row names, the earlier row being written) is not written and
        carries its error, and the others are written in one transaction.
        Answers 200 listing every row. A whole call is one write against the
        rate limits, and sending it again is safe. A product the app shows by
        pillar is a 409, as is a write that waited too long on another write to
        the product or its dates (send it again). Usage values are what a
        product's dimensions measure, per account and date, at the product's
        period (its `period`; the app shows usage at no other, and a product
        with none set shows at MONTHLY). A write moves a date to its period's
        first day: for WEEKLY, the weekday the product's latest weekly row falls
        on (Monday when it has none); the 1st for MONTHLY; the first day of the
        quarter for QUARTERLY (in the product's quarter cycle; calendar quarters
        when it has no rows), and January 1 for YEARLY; DAILY and SINGLE keep
        the date sent. An account has one row per date here: where data feeds
        stored several (older rows, or a CSV feed set to allow multiple rows per
        customer), the one written and listed is the row the feeds write today,
        else the oldest, while the app shows them all. A product with no display
        settings, or a period this API does not know, is a 409.
      operationId: usage_write
      parameters:
        - in: path
          name: product_id
          required: true
          schema:
            type: string
        - description: >-
            What `account` is: the Statisfy account id, its CRM id, or its web
            domain
          in: query
          name: match
          required: false
          schema:
            default: id
            enum:
              - id
              - crm_account_id
              - domain
            type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                rows:
                  items:
                    $ref: '#/components/schemas/UsageRowIn'
                  maxItems: 1000
                  minItems: 1
                  title: Rows
                  type: array
              required:
                - rows
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageWritten'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    UsageRowIn:
      additionalProperties: false
      properties:
        account:
          description: The account, by what `match` names
          maxLength: 255
          minLength: 1
          title: Account
          type: string
        date:
          description: >-
            A day within the period (YYYY-MM-DD, a year from 1900 to 2999);
            stored under the period's first day
          format: date
          title: Date
          type: string
        values:
          additionalProperties:
            anyOf:
              - type: boolean
              - type: integer
              - type: number
              - type: string
              - type: 'null'
          description: >-
            Dimension key → value, as the dimension's type takes it: a number (a
            percent as 20 for 20%, a ratio as 0.2 for 20%; neither is capped),
            text of up to 10,000 characters, true or false, or a date
            (YYYY-MM-DD). null deletes the value; keys not sent are kept.
          maxProperties: 500
          minProperties: 1
          title: Values
          type: object
      required:
        - account
        - date
        - values
      title: UsageRowIn
      type: object
    UsageWritten:
      properties:
        failed:
          title: Failed
          type: integer
        rows:
          description: Every row, in request order
          items:
            $ref: '#/components/schemas/UsageRowResult'
          title: Rows
          type: array
        written:
          title: Written
          type: integer
      required:
        - written
        - failed
        - rows
      title: UsageWritten
      type: object
    UsageRowResult:
      properties:
        account:
          anyOf:
            - type: string
            - type: 'null'
          description: The Statisfy account id the row names, when found
          title: Account
        date:
          description: 'The period''s first day: the date the row is stored under'
          format: date
          title: Date
          type: string
        error:
          anyOf:
            - $ref: '#/components/schemas/ItemError'
            - type: 'null'
          description: Set exactly when `status` is `failed`
        index:
          description: The row's place in the request, from 0
          title: Index
          type: integer
        status:
          enum:
            - written
            - failed
          title: Status
          type: string
      required:
        - index
        - status
        - date
      title: UsageRowResult
      type: object
    ItemError:
      description: The error envelope a single request would have returned.
      properties:
        code:
          title: Code
          type: string
        details:
          items:
            additionalProperties: true
            type: object
          title: Details
          type: array
        message:
          title: Message
          type: string
      required:
        - code
        - message
      title: ItemError
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http
      description: >-
        An API key, sent as `Authorization: Bearer stfy_live_…`. See
        [Authentication](/rest-api/authentication) for how to get one and which
        scopes it needs.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.