> ## 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 Customize Products Order in Checkouts

> Control exactly which products appear in a checkout — and in what order — using the Macropay API.

When you put several products in front of a buyer, sequence is leverage. The first option anchors the decision; the order you list products in is the order they render on the hosted checkout. Macropay gives you that control through the API: the position of each product ID in your request is the position it occupies on the page.

Because Macropay is the **merchant of record**, every one of these checkouts also handles sales tax and VAT, runs through a PCI DSS Level 1 compliant flow, and settles under our entity — so reordering products is purely a presentation decision, with no compliance strings attached.

<Info>
  Reordering the products shown in a checkout is currently an **API-only** capability. There is no dashboard toggle for it yet.
</Info>

## What you'll need

| Requirement                  | Where it comes from                                                                           |
| ---------------------------- | --------------------------------------------------------------------------------------------- |
| An organization access token | Create one via the [Organization Access Tokens](https://docs.macropay.ai/integrate/oat) guide |
| The right scope              | `checkout_links:write` for links, `checkouts:write` for sessions                              |
| Product IDs                  | Copied from your **Products → Catalogue** in the dashboard                                    |

## Step 1 — Get a token and your product IDs

<Steps>
  <Step title="Mint an organization access token">
    Follow the [Organization Access Tokens](https://docs.macropay.ai/integrate/oat) guide to create a token. After it's generated, copy it immediately — it's shown only once.

    <img height="200" src="https://mintcdn.com/macrodeepinc/rPF293t5zy_Onjx_/assets/guides/customize-products-order-in-checkouts/access-token.png?fit=max&auto=format&n=rPF293t5zy_Onjx_&q=85&s=337a96b45fa24c78f61e704d5ac82706" data-path="assets/guides/customize-products-order-in-checkouts/access-token.png" />
  </Step>

  <Step title="Open the product catalogue">
    In the dashboard sidebar, go to **Products → Catalogue**, or jump straight to `https://macropay.ai/dashboard/${org_slug}/products`.

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

  <Step title="Copy each product ID">
    For every product you want in the checkout, open the **⋮ (More options)** menu beside it and choose **Copy Product ID**. Keep these handy — the order you list them in next is the order buyers will see.

    <img height="200" src="https://mintcdn.com/macrodeepinc/rPF293t5zy_Onjx_/assets/guides/customize-products-order-in-checkouts/product-id.png?fit=max&auto=format&n=rPF293t5zy_Onjx_&q=85&s=2feaafa2a340f93bd0098c35eaeac5a0" data-path="assets/guides/customize-products-order-in-checkouts/product-id.png" />
  </Step>
</Steps>

## Step 2 — Order products in a checkout link

Checkout links are reusable, shareable URLs — drop one in an email, a docs page, or a Slack message and anyone who opens it lands on a ready-to-pay checkout. The `products` array sets the order.

<Steps>
  <Step title="Create the link with products in your preferred order">
    Replace `<YOUR_ACCESS_TOKEN>` with your token, then list the product IDs top-to-bottom in the order you want them rendered.

    <Note>
      Your token needs the **`checkout_links:write`** scope to call the [Create Checkout Link](/api-reference/checkout-links/create) endpoint.
    </Note>

    ```bash Terminal theme={null}
    curl --request POST \
        --url https://api.macropay.ai/v1/checkout-links/ \
        --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
        --header 'Content-Type: application/json' \
        --data '{
        "products": [
            "<STARTER_PLAN_ID>",
            "<PRO_PLAN_ID>"
        ]
    }'
    ```

    Every available parameter is documented in the [Create Checkout Link API reference](https://docs.macropay.ai/api-reference/checkout-links/create).
  </Step>

  <Step title="Open the returned URL">
    The response is JSON. Grab the `url` field and open it in a browser.

    ```json theme={null}
    {
        "...": "...",
        "...": "...",
        "url": "https://buy.macropay.ai/macropay_cl_..." // [!code ++]
    }
    ```

    With the Starter plan listed first, it appears first on the page:

    <img height="200" src="https://mintcdn.com/macrodeepinc/rPF293t5zy_Onjx_/assets/guides/customize-products-order-in-checkouts/p1-p2.png?fit=max&auto=format&n=rPF293t5zy_Onjx_&q=85&s=a0c35b59073c178397582df1d3cd84bd" data-path="assets/guides/customize-products-order-in-checkouts/p1-p2.png" />
  </Step>

  <Step title="Flip the order">
    Want the Pro plan to lead instead? Swap the array so its ID comes first.

    ```bash Terminal theme={null}
    curl --request POST \
        --url https://api.macropay.ai/v1/checkout-links/ \
        --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
        --header 'Content-Type: application/json' \
        --data '{
        "products": [
            "<PRO_PLAN_ID>",
            "<STARTER_PLAN_ID>"
        ]
    }'
    ```

    The checkout now leads with the Pro plan:

    <img height="200" src="https://mintcdn.com/macrodeepinc/rPF293t5zy_Onjx_/assets/guides/customize-products-order-in-checkouts/p2-p1.png?fit=max&auto=format&n=rPF293t5zy_Onjx_&q=85&s=a0a19df85b55c5094299a36f5e0b2d88" data-path="assets/guides/customize-products-order-in-checkouts/p2-p1.png" />
  </Step>
</Steps>

## Step 3 — Order products in a checkout session

Checkout sessions are best when you create a fresh checkout per buyer — for example, generating one on the fly when a customer clicks "Upgrade" or when an automation (Zapier, Raycast, or your own agent) needs a single-use payment URL. The ordering rule is identical: the `products` array decides the layout.

<Steps>
  <Step title="Create the session with your product order">
    Replace `<YOUR_ACCESS_TOKEN>` and list the product IDs in the order you want them shown.

    <Note>
      Your token needs the **`checkouts:write`** scope to call the [Create Checkout Session](/api-reference/checkouts/create-session) endpoint.
    </Note>

    ```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": [
            "<STARTER_PLAN_ID>",
            "<PRO_PLAN_ID>"
        ]
    }'
    ```

    See every parameter in the [Create Checkout Session API reference](https://docs.macropay.ai/api-reference/checkouts/create-session).
  </Step>

  <Step title="Open the returned URL">
    Read the `url` field from the JSON response and open it.

    ```json theme={null}
    {
        "...": "...",
        "url": "https://buy.macropay.ai/macropay_c_...", // [!code ++]
        "...": "..."
    }
    ```

    Starter first in the request, Starter first on the page:

    <img height="200" src="https://mintcdn.com/macrodeepinc/rPF293t5zy_Onjx_/assets/guides/customize-products-order-in-checkouts/p1-p2.png?fit=max&auto=format&n=rPF293t5zy_Onjx_&q=85&s=a0c35b59073c178397582df1d3cd84bd" data-path="assets/guides/customize-products-order-in-checkouts/p1-p2.png" />
  </Step>

  <Step title="Flip the order">
    Reverse the array to lead with the Pro plan.

    ```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": [
            "<PRO_PLAN_ID>",
            "<STARTER_PLAN_ID>"
        ]
    }'
    ```

    The session now presents the Pro plan first:

    <img height="200" src="https://mintcdn.com/macrodeepinc/rPF293t5zy_Onjx_/assets/guides/customize-products-order-in-checkouts/p2-p1.png?fit=max&auto=format&n=rPF293t5zy_Onjx_&q=85&s=a0a19df85b55c5094299a36f5e0b2d88" data-path="assets/guides/customize-products-order-in-checkouts/p2-p1.png" />
  </Step>
</Steps>

<Tip>
  Links vs. sessions: reach for a **checkout link** when you want one durable URL to reuse across many buyers, and a **checkout session** when you mint a single checkout per buyer. Both honor the same `products` ordering, so you can A/B which arrangement converts best without touching anything else.
</Tip>