---
title: Earn with promoted placements
description: >-
  Opt into promoted placements to earn commission on the purchases you drive
  through the Global Catalog. Learn how promoted placements work, how to sign
  up, how to request placements, how payouts work, and which disclosures you
  need to make.
source_url:
  html: 'https://shopify.dev/docs/agents/catalog/promoted-placement'
  md: 'https://shopify.dev/docs/agents/catalog/promoted-placement.md'
---

# Earn with promoted placements

You can opt into promoted placements and earn revenue on attributed purchases you drive. Placements use your existing integration, extend the [Global Catalog](https://shopify.dev/docs/agents/catalog/global-catalog), and conform to the [UCP Catalog specification](https://ucp.dev/2026-04-08/specification/catalog/).

**Developer Preview:**

Access to promoted placements is limited and invite-led during Developer Preview. [Join the waitlist](https://docs.google.com/forms/d/e/1FAIpQLScIYXGmAjNgRczIchHAuK-FVU3J9x1qRqZ_7tU3nxdyGPLDNQ/viewform) to register your interest, get early access, receive onboarding support, and help shape the final API. This capability is published for developer feedback ahead of general availability. Field names, shapes, and behavior are not final and might change.

***

## Requirements

Before you request promoted placements, you need:

* An existing [Global Catalog](https://shopify.dev/docs/agents/catalog/global-catalog) integration.
* Access to your organization's [Dev Dashboard](https://shopify.dev/docs/apps/build/dev-dashboard).

***

## How promoted placements work

Promoted placements extend Global Catalog search with an optional paid-placement flow. You [request placements with `search_catalog` calls](https://shopify.dev/docs/agents/catalog/global-catalog#search_catalog), identify promoted variants by their `placement` object, send buyers through the attributed variant `url`, and earn commission on eligible attributed purchases. Organic variants are standard Global Catalog variants that aren't promoted placements.

**Commission in Developer Preview:**

The base rate is set for Developer Preview and might change before general availability.

At launch, Shopify pays a flat base commission on the value of attributed purchases you drive through promoted placements. The rate applies to every eligible product in the Global Catalog, so you don't need to evaluate or compare per-product rates to decide what to promote.

| Detail | Description |
| - | - |
| Base rate | 0.3% (30 bps) on attributed purchases. |
| Order scope | Commission applies to every item in the attributed order that's available through the Global Catalog, not only the clicked product. |
| Attribution window | Conversions are attributed using a last-click methodology using a 7-day attribution window. |

In the future, merchants can offer additional commission, which appears in `placement.commission.percentage.value` on a promoted placement variant and is added to the base rate. When `placement.commission` is omitted, the base rate still applies. The following response indicates an extra 1.5% added to the base rate:

## Promoted variant

```json
{
  "id": "gid://shopify/ProductVariant/45012",
  "placement": {
    "type": "affiliate",
    "commission": {
      "percentage": {
        "value": 1.5
      }
    }
  }
}
```

***

## Step 1: Sign up for the program

Promoted placements are invite-led during Developer Preview. Signing up adds the ability to request promoted placements using an existing Global Catalog integration.

1. Join the [waitlist](https://docs.google.com/forms/d/e/1FAIpQLScIYXGmAjNgRczIchHAuK-FVU3J9x1qRqZ_7tU3nxdyGPLDNQ/viewform) using your organization ID. In the [Dev Dashboard](https://dev.shopify.com/dashboard), you can find your organization ID in the URL (for example, `https://dev.shopify.com/dashboard/{organization_id}/catalogs`).
2. Shopify onboards developers from the waitlist in batches. After Shopify onboards you, a **Get paid** action appears on the **Catalogs** page in the Dev Dashboard.
3. Click **Get paid** and review and sign the program agreement. Accepting the terms enrolls your organization in the program.

After you accept the program terms, you can request promoted placements in Global Catalog requests.

For [saved catalogs](https://shopify.dev/docs/agents/catalog#saved-catalogs), open each saved catalog in the Dev Dashboard and select **Earn commission** under **Promoted Placement Program** settings. New saved catalogs don't automatically earn commission.

***

## Step 2: Request promoted placements

After you accept the program terms, send `placements: ["affiliate"]` on your `search_catalog` calls to blend promoted placements into the ranked results. Omit `placements` to return only organic variants.

Callers who aren't approved receive organic variants and a `messages` note explaining they aren't authorized for promoted placements.

POST

## https://catalog.shopify.com/api/ucp/mcp

##### search\_catalog request

```json
{
  "catalog": {
    "query": "trail running shoes",
    "placements": ["affiliate"]
  }
}
```

##### Authorized response

```json
{
  "products": [
    {
      "title": "Trail Runner Pro",
      "variants": [
        {
          "id": "gid://shopify/ProductVariant/45012",
          "url": "https://runworld.example/products/trail-runner-pro?variant=45012&utm_source=shopify&utm_medium=catalog&shclid=clk_3b9f2a&shdid=dev_8f3a",
          "placement": {
            "type": "affiliate",
            "commission": {
              "percentage": {
                "value": 1.5
              }
            }
          }
        }
      ]
    },
    {
      "title": "Summit Trail Shoe",
      "variants": [
        {
          "id": "gid://shopify/ProductVariant/91823",
          "url": "https://peakgear.example/products/summit-trail-shoe?variant=91823&utm_source=shopify&utm_medium=catalog&shclid=clk_7c1d4e"
        }
      ]
    }
  ]
}
```

##### Unauthorized response

```json
{
  "products": [
    {
      "title": "Summit Trail Shoe",
      "variants": [
        {
          "id": "gid://shopify/ProductVariant/91823",
          "url": "https://peakgear.example/products/summit-trail-shoe?variant=91823&utm_source=shopify&utm_medium=catalog&shclid=clk_7c1d4e"
        }
      ]
    }
  ],
  "messages": [
    {
      "type": "info",
      "code": "unauthorized",
      "content": "You aren't authorized for promoted placements. Returning organic variants."
    }
  ]
}
```

***

## Step 3: Identify promoted variants

Inspect each variant in the `search_catalog` response to determine whether it's a promoted placement. A promoted variant includes a `placement` object. Organic variants omit it.

## Variant comparison

##### Promoted variant

```json
{
  "id": "gid://shopify/ProductVariant/45012",
  "placement": {
    "type": "affiliate",
    "commission": {
      "percentage": {
        "value": 1.5
      }
    }
  }
}
```

##### Organic variant

```json
{
  "id": "gid://shopify/ProductVariant/91823"
}
```

Use these fields in the Global Placement object to interpret promoted placement variants:

| Field | Type | Description |
| - | - | - |
| `variants[].placement` | `object` | Marks the variant as a promoted placement in the current response. Present only on promoted placements. |
| `variants[].placement.type` | `string` | The placement type. The well-known value is `"affiliate"`. |
| `variants[].placement.commission` | `object` | Describes a merchant-provided additional commission. Present only when a merchant offers an additional commission. |
| `variants[].placement.commission.percentage.value` | `number` | The merchant-provided additional commission percentage. |

***

## Step 4: Preserve attribution

Use the variant's `url` to send the buyer to the merchant's canonical product page with the correct SKU selected. Promoted placement URLs include the `shdid` attribution parameter. Organic URLs don't include it.

## Variant URL comparison

##### Promoted placement URL

```text
https://{merchant_site}/products/{product_handle}?variant={v}&utm_source=shopify&utm_medium=catalog&shclid={click_id}&shdid={developer_id}
```

##### Organic URL

```text
https://{merchant_site}/products/{product_handle}?variant={v}&utm_source=shopify&utm_medium=catalog&shclid={click_id}
```

Use these URL parameters to interpret attribution:

| Parameter | Applies to | Description |
| - | - | - |
| `utm_source=shopify` | All variant URLs | Identifies Shopify-sourced traffic for merchant attribution. |
| `utm_medium=catalog` | All variant URLs | Identifies Global Catalog traffic. |
| `shclid` | All variant URLs | Identifies the click for attribution. |
| `shdid` | Promoted placement URLs | Identifies the developer for attribution and payout. |

Commissions are credited only when you send buyers through the variant `url` exactly as provided, with attribution parameters intact. Rerouting, masking the link behind your own domain, or altering parameters breaks attribution and disqualifies the conversion.

***

## Step 5: Set up payments and manage earnings

Set up your [payout method](https://help.shopify.com/en/partners/manage-account/manage-payouts-invoices/payout-method) in the Partner Dashboard, including any identity verification needed for Shopify to pay you. Payouts use the same rails as other Shopify partner payments.

Your payout for a period is the sum of the commissions on your qualified conversions. For each attributed order, you earn the [base rate plus any merchant-provided commission](#how-promoted-placements-work) on every item in the order that's available through the Global Catalog.

Earnings are subject to the following rules:

* A purchase that follows a valid click becomes a qualified conversion after Shopify verifies it during the hold period.
* A conversion can be disqualified and earn nothing for cancellations, returns, refunds, fraudulent or invalid traffic, purchases by you or people connected to you, or missing or altered attribution parameters.
* If an order is later canceled, returned, or refunded, then the related commission is reversed and can reduce a later payout.
* A balance below the minimum payout threshold rolls over to the next payout period.

Commissions are paid to your Shopify Partner payout method using Hyperwallet, on the same monthly schedule and subject to the same minimum payout threshold as other Partner payouts. Payouts appear in the Partner Dashboard.

***

## Step 6: Disclose paid placements

Because you can be paid for referring buyers, you have a material connection that you need to disclose where required by law. Your disclosure should make the paid relationship clear before buyers act on a promoted result.

When you show promoted placements:

* Tell users that you may earn a commission, such as "We may earn a commission on purchases."
* Label promoted placements so users can tell them apart from organic variants.
* Don't bury the disclosure in a footer or privacy policy.
* Don't make false or misleading claims about products, prices, merchants, or Shopify.

These obligations include US FTC material-connection requirements and comparable advertising-transparency and sponsored-content rules in the EU, the UK, and other jurisdictions where you operate. Shopify doesn't prescribe the exact wording or placement, so follow the rules that apply to your audience and check with your own counsel.

***

## Next steps

[Global Catalog MCP reference\
\
](https://shopify.dev/docs/agents/catalog/global-catalog)

[Reference for UCP-compliant product discovery on Shopify.](https://shopify.dev/docs/agents/catalog/global-catalog)

[About Catalogs\
\
](https://shopify.dev/docs/agents/catalog)

[Learn how Global Catalog and Storefront Catalog work.](https://shopify.dev/docs/agents/catalog)

***