> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Conto Commerce quickstart

> Make a first test purchase with one organization API key. No real card, store or charge is involved.

Conto Commerce lets your platform's agents buy from online stores for your users. Your server starts a purchase from a product URL and a task. Conto shops, checks out and pays with the buyer's own card, and your user reviews each purchase on a Conto page. Your platform never handles card details.

Test mode is open to every organization. A test card pays only Conto's test stores, so this whole page runs without a real card, a real store or a charge.

## 1. Create a key

Create an organization API key in **Settings > API Keys**. The **Standard** preset covers buyers, setup and purchases. Setting allowed return origins needs `org:write`, which the **Admin** preset includes. Keep the key on your server.

Purchases with one organization key need an `@conto_finance/sdk` release that includes `admin.purchasing.purchases`.

## 2. Set up a test buyer

Map one of your users to a buyer and send them to Conto's setup page.

```typescript theme={null}
import { ContoAdmin } from '@conto_finance/sdk';

const admin = new ContoAdmin({ orgApiKey: process.env.CONTO_ORG_API_KEY! });

await admin.purchasing.settings.update({ allowedReturnOrigins: ['http://localhost:4100'] });

const buyer = await admin.purchasing.buyers.create({
  externalId: 'test-user-1',
  email: 'buyer@example.com',
});

const link = await admin.purchasing.paymentMethods.createSetupLink({
  buyerId: buyer.id,
  environment: 'test',
  returnUrl: 'http://localhost:4100/',
});
console.log(link.url);
```

Open `link.url` in a browser. It works once and expires in 10 minutes. On the page, confirm the spending limits, add the test card and let the agent shop with it.

The same `externalId` returns the same buyer, so reuse it while you test. Each buyer uses one agent in your plan.

## 3. Buy from a test store

```typescript theme={null}
const purchases = admin.purchasing.purchases;

const purchase = await purchases.create(
  {
    buyerId: buyer.id,
    request: {
      url: 'https://supplies.conto-test.invalid/products/notebook-pack',
      task: 'Buy one pack of notebooks with standard shipping',
    },
    maxCost: { amountMinor: 2000, currency: 'USD' },
  },
  { idempotencyKey: `order-${Date.now()}` }
);

for await (const event of purchases.watch(purchase.id)) {
  const { status, requiredAction } = event.data;
  console.log(event.version, status);

  if (requiredAction?.kind === 'buyer_details') {
    await purchases.respond(purchase.id, {
      actionId: requiredAction.id,
      revision: requiredAction.revision,
      fields: {
        name: 'Sample Buyer',
        email: 'buyer@example.com',
        phone: '4155550100',
        address: '1 Market Street',
        city: 'San Francisco',
        region: 'CA',
        postalCode: '94105',
        country: 'US',
      },
    });
  }

  if (requiredAction?.kind === 'purchase_review') {
    const review = await purchases.createActionLink(purchase.id);
    console.log('Open to approve:', review.url);
  }
}
```

The store asks for delivery details, which your server answers. The buyer then opens the review link, checks the items, total and delivery details, and approves.

## 4. Read the result

```typescript theme={null}
const done = await purchases.get(purchase.id);
console.log(done.status, done.result?.merchantReference);
// succeeded TEST-3BE45BD829
```

`succeeded` means the store confirmed the order. `paymentEvidence` reports authorization, the store's confirmation and settlement separately.

## Go live

Live purchases need Conto to enable them for your organization, a Builder or Enterprise plan, and the buyer's own card. Until then, live setup links and live purchases are refused with `LIVE_NOT_ENABLED`. `admin.purchasing.capabilities()` reports `environments.live.available` for your organization.

Your code does not change for live: create the setup link without `environment: 'test'` and buy from a real store URL. For events in production, use [webhooks](/docs/sdk/purchases#events-and-webhooks) instead of holding a stream open.

## Build it with a coding agent

Paste this into your coding agent from your app's repository:

```text theme={null}
Add Conto Commerce to this app with @conto_finance/sdk and an organization API key from
CONTO_ORG_API_KEY, on the server only. Follow https://conto.finance/docs/guides/commerce-quickstart
and https://conto.finance/docs/sdk/purchases.
1. Map each signed-in user to a buyer with admin.purchasing.buyers.create({ externalId: user.id, email }).
2. Add a "Set up purchasing" button that redirects to a test setup link from
   admin.purchasing.paymentMethods.createSetupLink({ buyerId, environment: 'test', returnUrl }).
3. Start purchases with admin.purchasing.purchases.create({ buyerId, request: { url, task }, maxCost })
   and a stable idempotency key per order.
4. Answer buyer_details actions with the user's saved address, and send the user to
   purchases.createActionLink(id) for review and card verification.
5. Receive events by webhook and verify each with verifyPurchaseWebhook.
Never handle card numbers, and never approve a review on the user's behalf.
```

## Next

* [Conto Commerce API reference](/docs/sdk/purchases): statuses, actions, events, webhooks, errors and test stores.
* [MCP tools](/docs/mcp/tools): the purchase tools for agents that call Conto themselves.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.