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, and conform to the UCP Catalog specification.

Anchor to RequirementsRequirements

Before you request promoted placements, you need:

• An existing Global Catalog integration.
• Access to your organization's Dev Dashboard.

Anchor to How promoted placements workHow promoted placements work

Promoted placements extend Global Catalog search with an optional paid-placement flow. You request placements with search_catalog calls, 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.

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.

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:

Anchor to Step 1: Sign up for the programStep 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 using your organization ID. In the Dev 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, 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.

Anchor to Step 2: Request promoted placementsStep 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.

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

{
  "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"
        }
      ]
    }
  ]
}

{
  "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."
    }
  ]
}

Anchor to Step 3: Identify promoted variantsStep 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.

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

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

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

Anchor to Step 4: Preserve attributionStep 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.

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

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

Use these URL parameters to interpret attribution:

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.

Anchor to Step 5: Set up payments and manage earningsStep 5: Set up payments and manage earnings

Set up your 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 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.

Anchor to Step 6: Disclose paid placementsStep 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.

Anchor to Next stepsNext steps

Global Catalog MCP reference

Reference for UCP-compliant product discovery on Shopify.

About Catalogs

Learn how Global Catalog and Storefront Catalog work.