Contract: shopify.refund.financially

Prove that the refund transaction succeeded at the gateway. A Refund record does not prove money movement. This level proves the SUCCESS status on the refund transaction with the requested amount.

Contract identity.
Fact	Value
Contract id	`shopify.refund.financially_completed`
Version	`1.0.0`
Hash	`183f55df6169b4e5`
Completion level	`financially_completed`
Certification	Community
Skill	Shopify Admin API 0.1.0
Valid for provider API versions	`2025-07`

What is the intent?

Return the amount to the customer.

What is the subject and the action?

Member	Value
Subject type	`shopify.refund`
Subject identity	refund_id = `$action.result.refundCreate.refund.id`
Canonical effect	`money.refund`
Provider operation	`mutation refundCreate`
Idempotency	not stated

How does the evidence correlate with this operation?

Strategy	Assurance	Keys	Required
`resource_id`	strong	refund_id from `$action.result.refundCreate.refund.id`	yes
`fingerprint`	weak	order from `$input.order_id`; amount from `$input.amount`	no

Which evidence does the contract require?

Minimum evidence level E2. An independent channel is required. Minimum channels: 1.

Channel	Level	Independence	Verifier	Description
`refund_readback`	E2	provider readback	`http`	Read the Refund record with its order and its transactions. It proves the record, not the money movement. The http verifier returns the parsed GraphQL response body, so a condition path starts with $observed.<channel>.data. The connection of the shop gives the base URL.
`transaction_readback`	E2	provider readback	`http`	Read the refund transactions through the Refund record. The status of a transaction carries the money movement state. The http verifier returns the parsed GraphQL response body, so a condition path starts with $observed.<channel>.data. The connection of the shop gives the base URL.
`order_refund_events`	E3	provider event	`webhook`	The refunds/create webhooks for the order since the operation started. A count above one shows a second refund. The webhook verifier returns {events, count, latest, earliest, types, duplicates_dropped}.

Which conditions must all hold for VERIFIED?

Condition	Meaning	Path	Operator	Expected	Evidence
`refund_created_in_window`	The shop created the Refund record after the operation started.	`$observed.transaction_readback.data.refund.createdAt`	`time_after`	`$operation.created_at`	`transaction_readback`
`transaction_status_success`	The refund transaction shows the SUCCESS status.	`$observed.transaction_readback.data.refund.transactions[0].status`	`eq`	`SUCCESS`	`transaction_readback`
`transaction_kind_refund`	The transaction is a refund transaction.	`$observed.transaction_readback.data.refund.transactions[0].kind`	`eq`	`REFUND`	`transaction_readback`
`transaction_amount_matches`	The refund transaction carries the requested amount.	`$observed.transaction_readback.data.refund.transactions[0].amountSet.shopMoney.amount`	`eq`	`$input.amount`	`transaction_readback`

Which conditions give CONTRADICTED?

Condition	Class	Reason	Path	Operator	Expected
`refund_on_wrong_order`	wrong subject	The refund belongs to another order.	`$observed.refund_readback.data.refund.order.id`	`ne`	`$input.order_id`
`refund_amount_mismatch`	wrong amount	The provider recorded a different refund amount.	`$observed.refund_readback.data.refund.totalRefundedSet.shopMoney.amount`	`ne`	`$input.amount`
`refund_predates_operation`	pre existing state	The refund is older than the operation. It proves nothing.	`$observed.refund_readback.data.refund.createdAt`	`time_before`	`$operation.created_at`
`more_than_one_transaction`	partial completion	The refund holds more than one transaction. This contract proves one refund transaction. Use one refund per transaction.	`$observed.transaction_readback.data.refund.transactions`	`array_length`	`{"min":2}`
`duplicate_refund_present`	duplicate side effect	Shopify created more than one refund on the order since the operation started. Do not retry.	`$observed.order_refund_events.count`	`gt`	`1`

Which observed states map to a verdict before completion?

Rule	Match	Verdict	Reason
`terminal_failure`	`$observed.transaction_readback.data.refund.transactions[0].status` in `["FAILURE","ERROR"]`	FAILED	The gateway rejected the refund transaction.
`still_transitional`	`$observed.transaction_readback.data.refund.transactions[0].status` in `["PENDING","AWAITING_RESPONSE"]`	PENDING	The gateway has not processed the refund yet. The runtime observes again later.
`status_unknown`	`$observed.transaction_readback.data.refund.transactions[0].status` eq `"UNKNOWN"`	UNVERIFIABLE	The gateway reports an unknown status. The runtime cannot prove the outcome.

How long does the runtime observe?

Timing member	Value
Initial delay	1000 ms
Poll interval	5000 ms
Backoff	exponential factor 2, max 60000 ms
Maximum attempts	40
Timeout	604800000 ms
Stale read window	20000 ms
On timeout	UNVERIFIABLE (`evidence_unavailable_before_timeout`), escalated to a person

Where do these rules come from?

shopify.graphql#/mutations/refundCreate: shopify.graphql, retrieved 2026-09-05
shopify.docs.refunds#refunds-in-the-admin-graphql-api/refund-objects-and-money-movement/p1: shopify.docs.refunds, retrieved 2026-09-05
shopify.docs.refunds#refunds-in-the-admin-graphql-api/refund-objects-and-money-movement/p2: shopify.docs.refunds, retrieved 2026-09-05
shopify.docs.refunds#refunds-in-the-admin-graphql-api/refund-objects-and-money-movement/p4: shopify.docs.refunds, retrieved 2026-09-05
shopify.graphql#/types/Refund/fields/createdAt: shopify.graphql, retrieved 2026-09-05
shopify.graphql#/enums/OrderTransactionStatus/values/SUCCESS: shopify.graphql, retrieved 2026-09-05
shopify.graphql#/types/OrderTransaction/fields/status: shopify.graphql, retrieved 2026-09-05
shopify.graphql#/enums/OrderTransactionKind/values/REFUND: shopify.graphql, retrieved 2026-09-05
shopify.graphql#/types/OrderTransaction/fields/kind: shopify.graphql, retrieved 2026-09-05
shopify.graphql#/types/OrderTransaction/fields/amountSet: shopify.graphql, retrieved 2026-09-05
shopify.graphql#/inputs/OrderTransactionInput/fields/amount: shopify.graphql, retrieved 2026-09-05

Can shopify.refund.financially_completed return VERIFIED from the action response alone?

No. The minimum evidence level is E2. The action response is E1. The completion conditions read transaction_readback.

What happens after the timeout?

The verdict is UNVERIFIABLE with the reason evidence_unavailable_before_timeout. The operation goes to a person for review.