Manage Subscriptions

An agent checkout can sign in to the user’s account at a merchant and change a subscription: subscribe to a plan, change the plan, or cancel it. Write the change in the task. A browser profile keeps the user signed in for the next checkout.

Prerequisites

Agent Checkouts integration — complete the quickstart.
Browser profile and sign-in — a subscription belongs to the user’s account at the merchant. See Sign In to Stores.
Server key — a production key with agent-checkouts.create, agent-checkouts.read, agent-checkouts.update, and agent-checkouts.cancel.

Change a Subscription

Write the change in the task

Name the plan and the change. To keep the user in control, tell the checkout to ask before it confirms the change.

const response = await fetch("https://www.crossmint.com/api/unstable/agent-checkouts", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-KEY": process.env.CROSSMINT_SERVER_API_KEY!,
        "x-crossmint-user-id": "YOUR_USER_ID",
    },
    body: JSON.stringify({
        request: {
            startUrl: "https://streaming.example.com/account",
            task: "Sign in, open the subscription settings, and cancel the Premium plan. Before you confirm the cancellation, ask me to confirm. Then tell me the date when my access ends.",
        },
        browser: { profileId: "YOUR_BROWSER_PROFILE_ID" },
        constraints: { maxCost: { amount: "0.01", currency: "USD" } },
    }),
});
if (!response.ok) {
    throw new Error(`Could not start checkout: ${response.status}`);
}
const { runId } = await response.json();

constraints.maxCost is required. A cancellation does not pay, so a very low cap makes sure that the checkout cannot buy anything.

Answer the sign-in and the confirmation

Follow the checkout. It can ask for a sign-in, a one-time code, or your user’s confirmation. Collect passwords and codes with CrossmintProtectedInput. See Answer Questions.

Show the result

When the checkout ends, read result.summary. It says what changed and when the change takes effect. Show it to your user.

To start a subscription, write the plan and the billing period in the task, for example “Subscribe to the monthly Premium plan”. Set maxCost to the first charge. Then answer the payment request with an order intent. See Pay for a Checkout. When a merchant offers a one-time purchase and a subscription for the same product, for example “Subscribe and save”, say in the task which one to choose.

Subscriptions depend on the card rail. Mastercard Agent Pay and the encrypted card support them. Visa Intelligent Commerce does not support subscriptions yet; support is coming.

Common Gotchas

Later charges of a subscription

The order intent pays the first charge of a new subscription. The merchant charges later renewals with the card details that it keeps. This works with Mastercard Agent Pay and the encrypted card. Visa Intelligent Commerce does not support subscriptions yet, so a renewal on a Visa credential can fail. Before you offer subscriptions, test a renewal at the merchant.

The checkout cannot find the subscription

The user must be signed in to the account that has the subscription. Attach the same browser.profileId that the user signed in with, or tell the checkout which account to sign in to.

Next Steps

Sign In to Stores

Keep the user signed in at a merchant

Answer Questions

Collect sign-in details and confirmations

Create a Checkout

Review the complete create request schema

Introduction

Agent Cards

Agent Wallets and Onramps

Agent Checkouts

API Reference

Prerequisites

Change a Subscription

Common Gotchas

Next Steps

Sign In to Stores

Answer Questions

Create a Checkout

​Prerequisites

​Change a Subscription

​Subscribe to a Plan

​Common Gotchas

​Next Steps

Sign In to Stores

Answer Questions

Create a Checkout

Prerequisites

Change a Subscription

Subscribe to a Plan

Common Gotchas

Next Steps