Admin GraphQL API2026-07

Subscription mutations get an
actor field

You can now record who initiated subscription billing, contract edits, and status changes — customer, merchant, or partner app — at the time the mutation runs.

On this page
  1. What's changing (in 30 seconds)
  2. The three actor values
  3. How it works: actions are stamped with their origin
  4. Supported Admin API mutations
  5. What's covered / what isn't
  6. 5 key points for developers
  7. 3 practical use cases
  8. A one-line summary you can use in proposals

1What's changing

Subscription-related mutations now have a new actor argument.
When creating a charge or editing a contract,which of these initiated the action — customer, merchant, or a partner app's automated system —can now be recorded alongside it.

Before: only "what happened"

Charge creation and contract changes were recorded, but who initiated the action wasn't standardized as a mutation argument.

After: you can also pass "who initiated it"

actor now accepts customer / merchant / partner , letting you make the source of an action explicit.

2The three actor values

customer

Customer-initiated

When the buyer initiates the action. Example: clicking "pay now" in the customer portal.

merchant

Merchant-initiated

When the merchant or their staff manually initiates the action.

partner

Partner app-initiated

When a partner app's automated system initiates the action. Example: scheduled billing or retry logic.

3How it works: actions are stamped with their origin

Customer pay now in the portal Merchant Manual action in the admin Partner app Recurring billing / retry Admin GraphQL mutation subscriptionContractUpdate( actor: "merchant" ) Subscription contract / billing attempt Action details (create charge / edit contract ...) + actor = origin(who initiated it) Can be analyzed and tracked later by origin
subscriptionBillingAttemptCreate only subscriptionBillingAttemptInput.actor is passed via the input object, as the article explicitly states. Everything else is included as actor a mutation argument.

4List of supported Admin API mutations

The supported mutations listed in the article fall into the following 3 groups by purpose.

GroupSupported mutations
Billing attempt
Billing Attempts		 subscriptionBillingAttemptCreate(subscriptionBillingAttemptInput.actor via)
subscriptionBillingCycleCharge
subscriptionBillingCycleBulkCharge
Contract editing
Contract Edits		 subscriptionContractCreate
subscriptionContractUpdate
subscriptionContractAtomicCreate
subscriptionContractProductChange
subscriptionBillingCycleContractEdit
Status update
Status Updates		 subscriptionContractActivate
subscriptionContractPause
subscriptionContractCancel
subscriptionContractFail
subscriptionContractExpire
From billing, contract editing, and status changes (resume/pause/cancel/fail/expire),nearly all subscription lifecycle operationscan record the origin.

5What is documented / not documented

✅ Explicitly stated in the article

actor The new argument and its purpose (tracking who initiated it)
The three possible values (customer / merchant / partner) and examples of each
The 13 supported mutations (3 groups)
subscriptionBillingAttemptCreate only via the input object
API version tag: 2026-07

⚠️ Not in the article (needs verification)

actor whether it is required or optional, and its default value → Not documented
Behavior when unspecified → Not documented
The recorded actor read (query) method → Not documented
Access scopes / permissions required to use it → Not documented
actor whether it can be verified to match the authenticating party → Not documented

Whether it is required/optional, its default, and how to read it are not described in the article, so before adopting it, check the schema/documentation for the target API version (2026-07).

65 points engineers should keep in mind

1. The value is fixed to 3 enum types

It only accepts customer / merchant / partner —these 3 values only. The sender must be designed to correctly map and pass one of these.

Input

2. Only charge creation passes it differently

subscriptionBillingAttemptCreate goes not directly under the arguments but inside subscriptionBillingAttemptInput.actor . A shared client implementation needs branching.

3. It applies across the board, so handle it all at once

It spans 13 mutations for charges, contract edits, and status updates. In your own subscription integration code, you should apply a consistent actor setting policy across all call sites.

? / ?

4. Required/optional and default values are unpublished

The article doesn't state whether it is required, its default, or the behavior when unspecified. Verify the actual behavior in a sandbox before finalizing production logic.

2026-07 Analysis

5. The feature / value of API version 2026-07 is on the "analysis & audit" axis

The article's tag is 2026-07.actor is not a feature that changes payments themselves, but ratherrecords "who initiated and triggered that subscription operation" as structured metadata. It's useful for churn analysis, audit logs, and distinguishing automatic vs. manual. How to read the recorded value isn't described in the article, so it needs to be confirmed separately.

73 use cases you can apply to your business

By source
USE CASE 1

Break cancellations and charge failures down "by source" for churn analysis

Challenge
You can't tell whether a cancellation (cancel) or charge failure (fail) is a "customer's voluntary cancellation," a "cancellation due to merchant operations," or a "failure due to exhausted automatic retries," so you can't narrow down which improvements to make.
Solution
In status-update and charge-related mutations, actor always attachcustomer / merchant / partner and aggregate cancellations and failures by it.
Effect
You can separate voluntary cancellations from operational and system-driven ones, letting you accurately target retention measures and charge-retry design respectively.
Technical note
How to read the recorded actor isn't documented in the article. Before aggregating, confirm the retrieval method (query) in the target API version.
USE CASE 2

Audit log for subscription operations / handling support inquiries

Challenge
Even when support or an audit asks "who changed/canceled this contract," there's no way to trace the origin of the action (the customer themselves, a staff action, or an automated process).
Solution
To each mutation for contract edits and status updates, attach actor , recording the action's origin as structured metadata.
Impact
You can fulfill your accountability obligations during support, and clearly separate customer-initiated actions from staff actions and automated processes.
Technical notes
Customer portal actions map to customer, admin-panel staff actions to merchant, and backend automated processes to partner —standardize this mapping as a unified implementation approach.
USE CASE 3

Visualize and optimize automatic retry / recurring billing (partner) behavior

Problem
The billing attempts generated by partner apps' scheduled-billing and retry logic get mixed in with customer-initiated payments and can't be distinguished in the logs, so you can't validate how well your retry design works.
Solution
To billing creations triggered by automated processes (subscriptionBillingAttemptCreate and the like), attach partner , and record the customer's "pay now" separately as customer .
Impact
You can measure the success/failure rate of automatic retries independently, giving you the data to justify tuning retry intervals and counts.
Technical notes
subscriptionBillingAttemptCreate is passed via subscriptionBillingAttemptInput.actor —note this. In the scheduler/retry path code, hardcode a fixed partner .

8A one-line summary you can use in a proposal

"For subscription billing, contract edits, and status changes, which of "customer / merchant / partner app" was the origin can now be recorded with the actor field that was added (API 2026-07).
Churn analysis, audit logs, and separating automated from manual actions can all be achieved just by tagging the origin source in your added implementation."