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 enable 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 enable promoted placements on a saved catalog and reference it with catalog.catalog_id in search_catalog calls. You then 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.

Joining the program doesn't change your existing requests. You earn commission only on requests that include the catalog.catalog_id of a saved catalog with Earn commission turned on.

Shopify pays a commission on the value of attributed purchases you drive through promoted placements. Each promoted variant shows the total commission rate you earn on it in placement.commission.percentage.value. The rate is a single value: Shopify's base rate plus any commission that a merchant funds through Shop Campaigns.

For example, the following response indicates a total commission of 1.5% on this variant:

The placement.type value is always "affiliate", including on products with Shop Campaigns commission.

Products from merchants outside Shopify, which use gid://catalog/... IDs, aren't eligible for commission and never include a placement object. These products aren't sold on Shopify, so they aren't part of the program.

Anchor to Step 1: Sign up for the programStep 1: Sign up for the program

Promoted placements are invite-led during Developer Preview. Sign up to enable promoted placements for saved catalogs in 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, review the program terms, and click Agree and sign up. Accepting the terms enrolls your organization in the program.

After you accept the program terms, you can enable promoted placements for saved catalogs:

• Saved catalogs that you create after you join have Earn commission turned on by default.
• Saved catalogs that you created before you joined don't earn commission until you turn it on. For each of these saved catalogs, open the catalog in the Dev Dashboard and select Earn commission in the Promoted Placement Program settings. Before you turn it on, make sure that the experiences that use the catalog include the disclosures that the program requires.

Anchor to Step 2: Search an enabled catalogStep 2: Search an enabled catalog

Send catalog.catalog_id from the saved catalog on your search_catalog calls. The catalog's server-managed configuration determines whether Shopify blends promoted placements into the ranked results. Requests that don't include an affiliate-enabled catalog return only organic variants. Callers who aren't enrolled in the program receive organic variants and an unauthorized message explaining that they aren't authorized for promoted placements. If Shopify can't verify your enrollment, then the response returns variants without attribution and a failed message, and you can retry the request.

{
  "catalog": {
    "query": "trail running shoes",
    "catalog_id": "01arz3ndektsv4rrffq69g5fav"
  }
}

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

{
  "products": [
    {
      "title": "Summit Trail Shoe",
      "variants": [
        {
          "id": "gid://shopify/ProductVariant/91823",
          "url": "https://peakgear.example/products/summit-trail-shoe?variant=91823&_gsid=clk_3b9f2a&utm_source=shopify&utm_medium=catalog"
        }
      ]
    }
  ],
  "messages": [
    {
      "type": "error",
      "code": "unauthorized",
      "path": "$.catalog_id",
      "content": "You aren't authorized for promoted placements. Returning organic variants.",
      "severity": "unrecoverable"
    }
  ]
}

Anchor to Attribute product lookupsAttribute product lookups

If you use the draft version of UCP, then you can also send catalog.catalog_id on lookup_catalog and get_product calls. Shopify adds the same attribution parameters to variant URLs and IDs in those responses, so purchases that start from a lookup are attributed to your catalog. These responses don't include placement objects. To see commission rates, use search_catalog.

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?shcgid=01arz3ndektsv4rrffq69g5fav&shclid=clk_3b9f2a",
  "placement": {
    "type": "affiliate",
    "commission": {
      "percentage": {
        "value": 1.5
      }
    }
  }
}

{
  "id": "gid://shopify/ProductVariant/91823?shcgid=01arz3ndektsv4rrffq69g5fav&shclid=clk_3b9f2a"
}

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

Anchor to Step 4: Preserve attributionStep 4: Preserve attribution

To earn commission, send buyers through the attributed variant URLs in an authorized response.

Anchor to Send buyers to a product pageSend buyers to a product page

Use the variant's url to send the buyer to the product page with the correct SKU selected. To send the buyer straight to checkout, use the variant's checkout_url. In an authorized response, all variant URLs include shclid and shcgid attribution parameters, whether the variant is promoted or organic. Unauthorized responses are returned without these affiliate attribution parameters.

When a merchant funds additional commission on a variant through Shop Campaigns, the variant's url and checkout_url point to the product in Shop (shop.com) instead of the merchant's online store. Send the buyer to these URLs as provided so that the purchase is attributed.

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

https://shop.com/products/{product_id}?variantId={v}&_gsid={click_id}&utm_source=shopify&utm_medium=catalog&utm_campaign=sca_1&shcgid={catalog_id}&shclid={click_id}

Use these URL parameters to interpret attribution:

Anchor to Variant IDs in cart and checkout flowsVariant IDs in cart and checkout flows

In an authorized response, Shopify variant IDs can also carry the shcgid and shclid parameters:

Cart MCP and Checkout MCP accept these IDs as returned, but they don't yet carry the attribution through to the order. Purchases made by adding a variant ID to a cart or checkout aren't attributed to your catalog, so send buyers through the variant url or checkout_url to earn commission.

Anchor to Keep attribution intactKeep attribution intact

Commissions are credited only when you send buyers through the variant url or checkout_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

After you accept the program terms, the Catalogs page in the Dev Dashboard shows Finish setup to get paid. Use it to set up your payout method, including any identity verification needed for Shopify to pay you. Payouts use the same payment 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 commission on every eligible item in the order that's available through the Global Catalog. Each item earns the base rate, or the higher rate shown in placement.commission when the merchant funds additional commission on that item through Shop Campaigns. A rate above the base rate applies only when the buyer completes the purchase in Shop, either in the Shop mobile app or on shop.com. Otherwise, that item earns the base rate, if it's eligible for the base rate.

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. Your payouts appear on the Payouts page in your organization settings, which you can open from the Dev 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.