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
Known 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
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp