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

# How to Create Checkout Session

> Spin up a hosted, tax-handled checkout for any product with a single API call.

A checkout session is a short-lived, hosted payment page you generate on demand and hand to a customer. Because Macropay is the **merchant of record**, that one call does more than collect a card: we calculate and remit the right sales tax or VAT for the buyer's country, keep card data inside our **PCI DSS Level 1 compliant** vault, and appear as the seller of record on the statement — so the liability never lands on you.

This guide walks through creating a session over the API, from token to live checkout URL.

<Info>
  Pass one or more products into a session and the customer can switch between them on the page. Everything in Macropay is a **product** — one-time or subscription — so the same flow powers a single license sale or a recurring plan.
</Info>

## What you'll need

* An **organization access token** (created below)
* One or more **product IDs** from your catalogue
* A terminal with `curl`, or any HTTP client / SDK

<Steps>
  <Step title="Create an organization access token">
    Sessions are created with an organization access token (OAT). Generate one by following the [Organization Access Tokens](https://docs.macropay.ai/integrate/oat) guide.
  </Step>

  <Step title="Copy the token immediately">
    The token is shown **once** at creation time. Copy it and store it in a secret manager or environment variable — you won't be able to view it again.

    <img height="200" src="https://mintcdn.com/macrodeepinc/rPF293t5zy_Onjx_/assets/guides/theme-switch-in-checkout/access-token.png?fit=max&auto=format&n=rPF293t5zy_Onjx_&q=85&s=12f7c2b1cc31854f5d5efa0fef6a9f0e" data-path="assets/guides/theme-switch-in-checkout/access-token.png" />
  </Step>

  <Step title="Open your product catalogue">
    In the Macropay dashboard sidebar, go to **Products** > **Catalogue**, or jump straight to the catalogue for your organization:

    `https://macropay.ai/dashboard/${org_slug}/products`

    <img height="200" src="https://mintcdn.com/macrodeepinc/rPF293t5zy_Onjx_/assets/guides/theme-switch-in-checkout/products-catalogue.png?fit=max&auto=format&n=rPF293t5zy_Onjx_&q=85&s=02e5aa9ae6f452abbc3378d0e12a1bec" data-path="assets/guides/theme-switch-in-checkout/products-catalogue.png" />
  </Step>

  <Step title="Grab the product IDs">
    For each item you want to offer, open the **⋮ (More options)** menu next to the product and choose **Copy Product ID**. Collect the IDs you need for the next step.

    <img height="200" src="https://mintcdn.com/macrodeepinc/rPF293t5zy_Onjx_/assets/guides/theme-switch-in-checkout/product-id.png?fit=max&auto=format&n=rPF293t5zy_Onjx_&q=85&s=d09e7da8a5f8c78bd61cd5fee9790853" data-path="assets/guides/theme-switch-in-checkout/product-id.png" />
  </Step>

  <Step title="Create the session">
    Send a `POST` to the checkouts endpoint with the products you want available on the page. Replace `<YOUR_ACCESS_TOKEN>` with your token and the placeholder UUIDs with your real product IDs.

    ```bash Terminal theme={null}
    curl --request POST \
        --url https://api.macropay.ai/v1/checkouts/ \
        --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
        --header 'Content-Type: application/json' \
        --data '{
        "products": [
            "d4e1c6b2-8f3a-4b5e-9c2d-1a2b3c4d5e6f",
            "a7f9e2c1-3b4d-4e5f-8a9b-0c1d2e3f4a5b"
        ],
        "success_url": "https://acme.dev/thanks?checkout_id={CHECKOUT_ID}",
        "customer_email": "rosa@acme.dev"
    }'
    ```

    <Tip>
      `success_url`, `customer_email`, `external_customer_id`, and `metadata` are all optional. Use `external_customer_id` to tie the order to a user in your own system, and `metadata` to stamp the session with anything you want echoed back on the resulting order and [webhook events](https://docs.macropay.ai/integrate/webhooks/events).
    </Tip>

    Every accepted field is documented in the [Create Checkout Session API reference](https://docs.macropay.ai/api-reference/checkouts/create-session).
  </Step>

  <Step title="Redirect the customer to the URL">
    The response is a checkout object. Read the `url` field and send the customer there — that's the hosted, tax-aware payment page.

    ```json theme={null}
    {
        "id": "macropay_c_...",
        "url": "https://buy.macropay.ai/macropay_c_...", // [!code ++]
        "net_amount": 4900,
        "tax_amount": 441,
        "total_amount": 5341,
        "status": "open"
    }
    ```

    The `tax_amount` is computed for the buyer's location and **remitted by us** — you keep your `net_amount` without touching a tax return.
  </Step>
</Steps>

## Selling to AI agents

The same endpoint works when the buyer is an autonomous agent rather than a person. Create a session, hand back the `url`, and let the agent complete payment programmatically. To bill agents by what they actually do, pair checkout with **usage-based pricing** so you can charge on activity or verified outcome and track agentic margin per agent. See the [API reference](https://docs.macropay.ai/api-reference) for the signals and metering endpoints.

## Next steps

<CardGroup cols={2}>
  <Card title="Checkout Links" href="https://docs.macropay.ai/features/checkout/links">
    Skip the API and share a no-code, reusable payment link.
  </Card>

  <Card title="Embedded Checkout" href="https://docs.macropay.ai/features/checkout/embed">
    Drop checkout straight into your own site instead of redirecting.
  </Card>
</CardGroup>