appUsageRecordCreate idempotency userErrors

Technical Q&A

Topic summary

A developer is experiencing unexpected behavior with the appUsageRecordCreate GraphQL mutation’s idempotency mechanism.

The Issue:

  • When submitting the mutation with the same idempotencyKey multiple times, no userErrors are returned
  • Multiple usage records appear in the subscriptionLineItem query, all sharing the same idempotency key
  • This creates concern about duplicate charges to customers

Expected Behavior:
The developer expected the second request with an identical idempotencyKey to either:

  • Return an error indicating a duplicate request
  • Prevent creation of additional usage records

Current Status:
The question remains unanswered—seeking clarification on:

  • Whether this is the intended API behavior
  • How to prevent duplicate customer charges when using idempotency keys
Summarized with AI on October 24. AI used: claude-sonnet-4-5-20250929.
1

Hello!

I’m trying create an appUsageRecord via the GraphQL API. I can successfully create the usage record with the following mutation:

            mutation appUsageRecordCreate(
                $description: String!
                $price: MoneyInput!
                $subscriptionLineItemId: ID!
                $idempotencyKey: String
            ) {
                appUsageRecordCreate(
                    description: $description
                    price: $price
                    subscriptionLineItemId: $subscriptionLineItemId
                    idempotencyKey: $idempotencyKey
                ) {
                    appUsageRecord {
                        id
                        description
                        price {
                            amount
                            currencyCode
                        }
                        createdAt
                        idempotencyKey
                    }
                    userErrors {
                        field
                        message
                    }
                }
            }

When I make another request with the same idempotencyKey I get a response to the mutation with no userErrors and when I query the list of subscriptionLineItem I see multiple entries with the idempotency key on them.

I’m confused because I don’t want to charge the second time.

Should I be getting back an error on the 2nd attempt via that idempotency key? How do I know the customer won’t be charged multiple times?