---
title: AppUsageRecord - GraphQL Admin
description: Store usage for app subscriptions with usage pricing.
api_version: 2026-10
source_url:
  html: 'https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord'
  md: 'https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord.md'
api_name: admin
api_type: graphql
type: object
---

# App​Usage​Record

object

Requires The staff member must have permission to manage app billing or approve app charges if authenticated with an online access token as described in <https://shopify.dev/apps/auth/oauth/access-modes>.

Store usage for app subscriptions with usage pricing.

## Fields

* created​At

  [Date​Time!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/DateTime)

  non-null

  The date and time when the usage record was created.

* description

  [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String)

  non-null

  The description of the app usage record.

* id

  [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID)

  non-null

  A globally-unique ID.

* idempotency​Key

  [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String)

  A unique key generated by the client to avoid duplicate charges.

* price

  [Money​V2!](https://shopify.dev/docs/api/admin-graphql/latest/objects/MoneyV2)

  non-null

  The price of the usage record.

* subscription​Line​Item

  [App​Subscription​Line​Item!](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppSubscriptionLineItem)

  non-null

  Defines the usage pricing plan the merchant is subscribed to.

***

## Map

### Fields and connections with this object

* [AppSubscriptionLineItem.usageRecords](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppSubscriptionLineItem#field-AppSubscriptionLineItem.fields.usageRecords)
* [AppUsageRecordConnection.nodes](https://shopify.dev/docs/api/admin-graphql/latest/connections/AppUsageRecordConnection#returns-nodes)
* [AppUsageRecordEdge.node](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecordEdge#field-AppUsageRecordEdge.fields.node)

***

## Mutations

* [app​Usage​Record​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appUsageRecordCreate)

  mutation

  Creates a usage charge for an app subscription with usage-based pricing. The charge counts toward the capped amount limit set when creating the subscription.

  Usage records track consumption of app features or services on a per-use basis. You provide the charge amount, a description of what you consumed, and the subscription line item ID. The optional [`idempotencyKey`](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-idempotencyKey) parameter prevents duplicate charges if you send the same request multiple times.

  If the new charge would cause total usage charges in the current billing interval to exceed the capped amount, then the mutation returns an error.

  Learn more about [creating usage-based subscriptions](https://shopify.dev/docs/apps/launch/billing/subscription-billing/create-usage-based-subscriptions).

  * description

    [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String)

    required

    ### Arguments

    The description of the app usage record.

  * idempotency​Key

    [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String)

    A unique key generated by the client to avoid duplicate charges. Maximum length of 255 characters.

  * price

    [Money​Input!](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MoneyInput)

    required

    The price of the app usage record.

  * subscription​Line​Item​Id

    [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID)

    required

    The ID of the app subscription line item to create the usage record under. This app subscription line item must have a usage pricing plan.

  ***

***

## AppUsageRecord Mutations

### Mutated by

* [app​Usage​Record​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appUsageRecordCreate)

***

## Interfaces

* [Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node)

  interface

***

## AppUsageRecord Implements

### Implements

* [Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node)