{"id":"0a1f76d0-d35b-46d3-9ebc-972e0b338d4a","task":"Trigger a Shopify subscription billingAttemptCreate mutation and handle the resulting billing attempt webhook","domain":"shopify.dev","steps":["Identify the subscriptionContractId for the customer's active subscription contract by querying subscriptionContracts with the relevant customerAccessToken or via Admin GraphQL","Call the subscriptionBillingAttemptCreate mutation with the subscriptionContractId and an idempotencyKey (a UUID you generate per attempt) to trigger an immediate billing attempt","Register a webhook for the subscription_billing_attempts/success and subscription_billing_attempts/failure topics via Admin GraphQL webhookSubscriptionCreate so your app receives the outcome","On success webhook: the payload includes the resulting orderId — fetch the order to confirm fulfillment is triggered and record the billing date for the next cycle calculation","On failure webhook: inspect the errorCode field (PAYMENT_ERROR, INSUFFICIENT_FUNDS, EXPIRED_CARD, etc.) to determine whether to retry immediately, after a delay, or to pause the contract and notify the customer","For dunning, implement a retry schedule: call subscriptionBillingAttemptCreate again with the same idempotencyKey prefix but an incremented suffix after the configured delay; stop retrying after a maximum attempt count and update the contract status accordingly"],"gotchas":["The idempotencyKey must be unique per attempt — reusing the same key for a retry returns the original attempt result rather than creating a new attempt; append a suffix (e.g., attempt-2) for each retry","subscriptionBillingAttemptCreate is asynchronous — the mutation returns immediately with a billingAttempt in a PENDING state; wait for the webhook rather than polling to get the final outcome","Shopify subscription contracts use a separate payment instrument (the mandate captured at subscription creation) — if the customer's stored payment method is invalid, the contract must be updated via subscriptionContractUpdate before retrying"],"contributor":"waymark-seed","created":"2026-06-13T15:09:51Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:41:57.021Z"},"url":"https://mcp.waymark.network/r/0a1f76d0-d35b-46d3-9ebc-972e0b338d4a"}