Blog

/

Partnerships

Table of Contents

TL;DR / Key Takeaways

What Rye's Catalog Is

How Merchants Join Your Catalog

Reading the Catalog

Commission Economics, in Code

Webhooks: Catalog Drift Without the Drift

Direct Routing vs. Agentic Routing

Use Cases

Frequently Asked Questions

Getting Started

Building on Rye's Commissioned Merchant Catalog: A Developer's Guide

Sophia Willows

Head of Engineering @ Rye

11 minutes read

How developers build multi-brand apps on Rye's network of 260+ commissioned merchants — install flows, catalog reads, commission economics, and webhook patterns.

TL;DR / Key Takeaways

  • Rye operates a network of 260+ directly-connected merchants, with developer commission rates of 14–17.5% and growing by ~50 merchants per month.

  • The same Universal Checkout API powers both flows. When the merchant is in the commissioned catalog, Rye routes the order through the direct merchant integration; for any other URL, Rye runs the checkout via agentic flows.

  • Merchants install Rye's Shopify app to join the catalog. On a Shopify-connected order, your platform's commission lands Net-0 — paid out at the moment the order is placed, not on a 30-day affiliate cycle.

  • Real-time webhooks keep your local catalog and order state in sync — product updates and removals, order status, shipment updates.

  • This post is for developers building on the catalog. If you're a brand evaluating whether to join, read Your Competitors Are Getting Orders From AI Agents. Are You?. If you're building a single-product lookup, read Introducing the Rye Product Data API.

What Rye's Catalog Is

Rye's commissioned-merchant catalog is a directly-connected network of ~260 Shopify merchants — spanning apparel, beauty, home goods, food and beverage, and consumer electronics — who've installed Rye's sales channel app. The catalog grows by ~50 merchants per month as Rye's BD team onboards new ones.

If you've shipped against the Product Data API, this guide is the next step — multi-merchant flows on top of the commissioned catalog.

You build against the same Universal Checkout API for every order. Rye routes the order under the hood:

  1. Direct routing (commissioned merchants) — when the merchant is in the catalog, Rye uses the direct Shopify integration. ~260 merchants today. Higher reliability, lower latency, ~14–17.5% developer commission with Net-0 payout.

  2. Agentic routing — when the order is for a URL outside the catalog, Rye completes the checkout via agentic flows. Coverage is broad; commission economics are platform-dependent.

If you're building rewards redemption, corporate gifting, employee recognition, cross-border commerce, or AI shopping experiences, the commissioned merchants are the volume your Rye economics — and your end-user UX — depend on.

This post walks through what it looks like to build against that catalog from a developer's perspective: how merchants get added, how to read the catalog, how commission flows through your code, and how to handle the catalog drifting underneath you.

How Merchants Join Your Catalog

The merchant-side onboarding flow matters to your product because it's how new supply lands in your app. Two paths feed your catalog: merchants you bring directly, and merchants Rye onboards over time that flow into your account automatically.

Onboarding merchants you bring

A merchant you know joins your catalog in three steps:

  1. Install link. Your Rye account generates a Shopify OAuth install link, scoped to that account.

  2. Merchant install. The merchant clicks the link, lands in the Shopify admin panel, and installs Rye's sales channel app. They configure their commission rate at the same time.

  3. Catalog availability. The connection is live. Their products are immediately queryable through the catalog API on the account that generated the install — no overnight sync, no backfill job.

The "immediately queryable" piece is what makes this different from running your own merchant outreach pipeline. You don't have to write a per-merchant ingestion path, manage feed validation, or coordinate inventory schemas. Once the merchant is installed, their full SKU set, variants, pricing, and availability are exposed through the same catalog endpoints you're already calling.

For developers building outbound merchant flows ("we want to onboard our brand partners directly into our rewards storefront"), this is where most of the implementation work goes — generating install links, surfacing them to the merchant in your own onboarding email or dashboard, and listening for the connection to land in your account.

The install link itself is a single call:

import Rye from 'checkout-intents';

const client = new Rye({ apiKey: process.env.RYE_API_KEY });

const installation = await client.merchantConnectors.createInstallationLink(
  'shopify',
  {
    storeUrl: 'shop.example.com',
  }
);

// Route the merchant to installation.url via your onboarding email or dashboard.

A dedicated merchant portal launching later in Q2 will replace the Shopify-app-only install flow — your developer-side experience doesn't change.

If you know a brand that fits but want Rye to handle recruiting and onboarding, the Brand Referral Program pays $500 per qualified referral (signed MSA, completed integration, first 3 sales) — unlimited, paid within 30 days. Reach out to us directly: mailto:carrie@rye.com.

Inheriting merchants Rye onboards

Rye's BD team is onboarding new commissioned merchants every week — currently around 50/month, weighted toward established brands across apparel, beauty, home, and food and beverage.

The merchant-side onboarding flow matters to your product because it's how new supply lands in your app. Two paths feed your catalog: merchants you bring directly, and merchants Rye onboards over time that flow into your account automatically.

Onboarding merchants you bring

A merchant you know joins your catalog in three steps:

  1. Install link. Your Rye account generates a Shopify OAuth install link, scoped to that account.

  2. Merchant install. The merchant clicks the link, lands in the Shopify admin panel, and installs Rye's sales channel app. They configure their commission rate at the same time.

  3. Catalog availability. The connection is live. Their products are immediately queryable through the catalog API on the account that generated the install — no overnight sync, no backfill job.

The "immediately queryable" piece is what makes this different from running your own merchant outreach pipeline. You don't have to write a per-merchant ingestion path, manage feed validation, or coordinate inventory schemas. Once the merchant is installed, their full SKU set, variants, pricing, and availability are exposed through the same catalog endpoints you're already calling.

For developers building outbound merchant flows ("we want to onboard our brand partners directly into our rewards storefront"), this is where most of the implementation work goes — generating install links, surfacing them to the merchant in your own onboarding email or dashboard, and listening for the connection to land in your account.

The install link itself is a single call:

import Rye from 'checkout-intents';

const client = new Rye({ apiKey: process.env.RYE_API_KEY });

const installation = await client.merchantConnectors.createInstallationLink(
  'shopify',
  {
    storeUrl: 'shop.example.com',
  }
);

// Route the merchant to installation.url via your onboarding email or dashboard.

A dedicated merchant portal launching later in Q2 will replace the Shopify-app-only install flow — your developer-side experience doesn't change.

If you know a brand that fits but want Rye to handle recruiting and onboarding, the Brand Referral Program pays $500 per qualified referral (signed MSA, completed integration, first 3 sales) — unlimited, paid within 30 days. Reach out to us directly: mailto:carrie@rye.com.

Inheriting merchants Rye onboards

Rye's BD team is onboarding new commissioned merchants every week — currently around 50/month, weighted toward established brands across apparel, beauty, home, and food and beverage.

The merchant-side onboarding flow matters to your product because it's how new supply lands in your app. Two paths feed your catalog: merchants you bring directly, and merchants Rye onboards over time that flow into your account automatically.

Onboarding merchants you bring

A merchant you know joins your catalog in three steps:

  1. Install link. Your Rye account generates a Shopify OAuth install link, scoped to that account.

  2. Merchant install. The merchant clicks the link, lands in the Shopify admin panel, and installs Rye's sales channel app. They configure their commission rate at the same time.

  3. Catalog availability. The connection is live. Their products are immediately queryable through the catalog API on the account that generated the install — no overnight sync, no backfill job.

The "immediately queryable" piece is what makes this different from running your own merchant outreach pipeline. You don't have to write a per-merchant ingestion path, manage feed validation, or coordinate inventory schemas. Once the merchant is installed, their full SKU set, variants, pricing, and availability are exposed through the same catalog endpoints you're already calling.

For developers building outbound merchant flows ("we want to onboard our brand partners directly into our rewards storefront"), this is where most of the implementation work goes — generating install links, surfacing them to the merchant in your own onboarding email or dashboard, and listening for the connection to land in your account.

The install link itself is a single call:

import Rye from 'checkout-intents';

const client = new Rye({ apiKey: process.env.RYE_API_KEY });

const installation = await client.merchantConnectors.createInstallationLink(
  'shopify',
  {
    storeUrl: 'shop.example.com',
  }
);

// Route the merchant to installation.url via your onboarding email or dashboard.

A dedicated merchant portal launching later in Q2 will replace the Shopify-app-only install flow — your developer-side experience doesn't change.

If you know a brand that fits but want Rye to handle recruiting and onboarding, the Brand Referral Program pays $500 per qualified referral (signed MSA, completed integration, first 3 sales) — unlimited, paid within 30 days. Reach out to us directly: mailto:carrie@rye.com.

Inheriting merchants Rye onboards

Rye's BD team is onboarding new commissioned merchants every week — currently around 50/month, weighted toward established brands across apparel, beauty, home, and food and beverage.

Reading the Catalog

The catalog API today is anchored on single-product lookup by URL. Your code calls the lookup endpoint per product to populate your local store; webhook subscriptions then keep your local copy in sync as products change. Commission rate at the product level is landing in the public API soon — pull from rye.com/docs for the current surface before writing production code.

Looking up a single product by URL:

import Rye from 'checkout-intents';

const client = new Rye({ apiKey: process.env.RYE_API_KEY });

const product = await client.products.lookup({
  url: '<https://shop.example.com/products/example-sku>',
});

console.log(product.name, product.price.amountSubunits, product.availability);

The catalog API today is anchored on single-product lookup by URL. Your code calls the lookup endpoint per product to populate your local store; webhook subscriptions then keep your local copy in sync as products change. Commission rate at the product level is landing in the public API soon — pull from rye.com/docs for the current surface before writing production code.

Looking up a single product by URL:

import Rye from 'checkout-intents';

const client = new Rye({ apiKey: process.env.RYE_API_KEY });

const product = await client.products.lookup({
  url: '<https://shop.example.com/products/example-sku>',
});

console.log(product.name, product.price.amountSubunits, product.availability);

The catalog API today is anchored on single-product lookup by URL. Your code calls the lookup endpoint per product to populate your local store; webhook subscriptions then keep your local copy in sync as products change. Commission rate at the product level is landing in the public API soon — pull from rye.com/docs for the current surface before writing production code.

Looking up a single product by URL:

import Rye from 'checkout-intents';

const client = new Rye({ apiKey: process.env.RYE_API_KEY });

const product = await client.products.lookup({
  url: '<https://shop.example.com/products/example-sku>',
});

console.log(product.name, product.price.amountSubunits, product.availability);

Commission Economics, in Code

For Shopify-connected merchants, commission flow is fundamentally different from how legacy affiliate networks work. Two things to know.

1. Net-0 commission payout on Shopify-connected orders.

Your platform's share of the commission lands at the same moment the order is placed — Net-0, not the end of a 30-day affiliate cycle.

For non-Shopify merchants, commissions still flow, but invoicing follows the merchant agreement — typically net-30 to net-90, accounting for return windows and how Rye invoices its own merchant partners. If your product spans both routing paths, your code should be able to handle two timing models.

2. The structural commission shift in agentic commerce is its own topic.

If you want the broader frame on why deterministic, at-checkout commission flow is structurally different from cookie-based affiliate attribution, read Affiliate Commissions in Agentic Commerce. The short version: agents bypass the cookie-based referral chain entirely, and the new surface is the kind of catalog-level commission hand-off described above.

Webhooks: Catalog Drift Without the Drift

If you're building a multi-merchant app, your local catalog state will drift from the source of truth the moment you cache it. New SKUs get added. Inventory hits zero. Prices move. Commission rates change.

Rye fires real-time webhooks for catalog members tied to your account. The patterns developers tend to wire up first:

  • Catalog updates fanout. When product.updated fires, the payload carries the full product object — check the availability field to drive your "in-stock / back soon" UI, and price to keep your stored prices in sync.

  • Catalog removals fanout. When product.removed fires, hide the listing immediately.

  • Order-status fanout. Wire checkout_intent.completed to mark orders confirmed in your system, and checkout_intent.order_failed to surface the failure to your end user.

A minimal handler in TypeScript:

import Rye from 'checkout-intents';
import express from 'express';

const client = new Rye({ apiKey: process.env.RYE_API_KEY });
const app = express();

app.post(
  '/webhooks/rye',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    let event;
    try {
      event = client.events.unwrap(
        req.body.toString(),
        req.header('x-rye-signature'),
        process.env.RYE_WEBHOOK_SECRET,
      );
    } catch {
      return res.status(401).send();
    }

    switch (event.type) {
      case 'product.updated':
        updateLocalProduct(event.data);
        break;
      case 'product.removed':
        removeLocalProduct(event.data.product_id);
        break;
      case 'checkout_intent.completed':
        markOrderConfirmed(event.data);
        break;
      case 'checkout_intent.order_failed':
        handleFailedOrder(event.data);
        break;
      case 'shipment.updated':
        updateLocalShipment(event.data);
        break;
    }

    res.status(200).send();
  },
);

Additional events for new merchant connections and commission-rate changes are landing as the catalog API expands — see rye.com/docs for the current event list.

If you're building a multi-merchant app, your local catalog state will drift from the source of truth the moment you cache it. New SKUs get added. Inventory hits zero. Prices move. Commission rates change.

Rye fires real-time webhooks for catalog members tied to your account. The patterns developers tend to wire up first:

  • Catalog updates fanout. When product.updated fires, the payload carries the full product object — check the availability field to drive your "in-stock / back soon" UI, and price to keep your stored prices in sync.

  • Catalog removals fanout. When product.removed fires, hide the listing immediately.

  • Order-status fanout. Wire checkout_intent.completed to mark orders confirmed in your system, and checkout_intent.order_failed to surface the failure to your end user.

A minimal handler in TypeScript:

import Rye from 'checkout-intents';
import express from 'express';

const client = new Rye({ apiKey: process.env.RYE_API_KEY });
const app = express();

app.post(
  '/webhooks/rye',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    let event;
    try {
      event = client.events.unwrap(
        req.body.toString(),
        req.header('x-rye-signature'),
        process.env.RYE_WEBHOOK_SECRET,
      );
    } catch {
      return res.status(401).send();
    }

    switch (event.type) {
      case 'product.updated':
        updateLocalProduct(event.data);
        break;
      case 'product.removed':
        removeLocalProduct(event.data.product_id);
        break;
      case 'checkout_intent.completed':
        markOrderConfirmed(event.data);
        break;
      case 'checkout_intent.order_failed':
        handleFailedOrder(event.data);
        break;
      case 'shipment.updated':
        updateLocalShipment(event.data);
        break;
    }

    res.status(200).send();
  },
);

Additional events for new merchant connections and commission-rate changes are landing as the catalog API expands — see rye.com/docs for the current event list.

If you're building a multi-merchant app, your local catalog state will drift from the source of truth the moment you cache it. New SKUs get added. Inventory hits zero. Prices move. Commission rates change.

Rye fires real-time webhooks for catalog members tied to your account. The patterns developers tend to wire up first:

  • Catalog updates fanout. When product.updated fires, the payload carries the full product object — check the availability field to drive your "in-stock / back soon" UI, and price to keep your stored prices in sync.

  • Catalog removals fanout. When product.removed fires, hide the listing immediately.

  • Order-status fanout. Wire checkout_intent.completed to mark orders confirmed in your system, and checkout_intent.order_failed to surface the failure to your end user.

A minimal handler in TypeScript:

import Rye from 'checkout-intents';
import express from 'express';

const client = new Rye({ apiKey: process.env.RYE_API_KEY });
const app = express();

app.post(
  '/webhooks/rye',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    let event;
    try {
      event = client.events.unwrap(
        req.body.toString(),
        req.header('x-rye-signature'),
        process.env.RYE_WEBHOOK_SECRET,
      );
    } catch {
      return res.status(401).send();
    }

    switch (event.type) {
      case 'product.updated':
        updateLocalProduct(event.data);
        break;
      case 'product.removed':
        removeLocalProduct(event.data.product_id);
        break;
      case 'checkout_intent.completed':
        markOrderConfirmed(event.data);
        break;
      case 'checkout_intent.order_failed':
        handleFailedOrder(event.data);
        break;
      case 'shipment.updated':
        updateLocalShipment(event.data);
        break;
    }

    res.status(200).send();
  },
);

Additional events for new merchant connections and commission-rate changes are landing as the catalog API expands — see rye.com/docs for the current event list.

Direct Routing vs. Agentic Routing

Both routing paths go through the same Universal Checkout API. The difference is what happens after Rye receives the order:

Dimension

Direct routing (commissioned merchants)

Agentic routing

Merchants

~260 directly-connected, growing ~50/month

Any merchant with a product URL

Path

Direct Shopify backend integration

Browser automation

Latency

Lower (direct API)

Higher (browser session)

Commission

~14–17.5%, Net-0 payout on Shopify-connected orders

Affiliate-based where available; lower rates; net-30 to net-90 per merchant agreement

Reliability

Very high

High but variable

Best for

Curated catalogs (rewards, gifting, employee recognition)

Open-ended "buy any product" (AI shopping agents, cross-border)

Most platform builds use both routing paths — the catalog is your high-margin, high-reliability core, and the agentic path is your tail for everything else. (For the architectural deep-dive, see the Universal Checkout API whitepaper.)

Use Cases

A few of the platform builds running on the catalog today:

  • Rewards redemption store. Surface commissioned-catalog merchants inside a logged-in cardholder experience. Convert points to dollars at checkout. Native checkout in your app — no affiliate redirects.

  • Corporate gifting catalog. Curate a multi-brand selection inside a B2B gifting flow. Stay merchant-of-record. Use real landed cost (shipping + sales tax) so your buyer sees the final price before sending.

  • Employee recognition program. Same shape as gifting, with the commission used to subsidize program cost rather than passed to the recipient.

  • Multi-brand AI agent shopping. When an agent's user names a product or category, Rye returns full landed cost (price, shipping, tax) in one call; the user gets a one-step purchase.

Each one is the same set of API calls. The difference is the UX layer wrapped around them.

Frequently Asked Questions

What is Rye's commissioned-merchant catalog?

Rye's commissioned-merchant catalog is a directly-connected network of 260+ merchants who've installed Rye's sales channel app on their commerce platform (Shopify today, with additional connectors built on request). Developers query the catalog through the Universal Checkout API and earn commission — typically 14–17.5% — on orders placed through their platform. The catalog grows by ~50 merchants per month.

How do merchants join Rye's catalog?

Two paths. Developers can generate an OAuth install link via client.merchantConnectors.createInstallationLink() and route it to merchants they want to onboard; the merchant installs Rye's sales channel app and configures their commission rate. Separately, Rye's BD team onboards new merchants directly — non-private installs flow into every developer's account automatically.

How does commission flow through Rye's catalog?

On commissioned-catalog orders, commission lands Net-0 — at the same moment the order is placed, not on a 30-day affiliate cycle. For non-Shopify merchants, invoicing follows the merchant agreement, typically net-30 to net-90.

What webhooks does Rye fire for catalog changes?

The live events are product.updated (full product object on any change), product.removed, checkout_intent.completed, checkout_intent.order_failed, and shipment.updated. Verify signatures with client.events.unwrap() before processing. Don't poll the catalog — subscribe and react.

Can I use Rye with non-Shopify merchants?

Yes. For any merchant URL outside the commissioned catalog, Rye runs the checkout via agentic flows.

Getting Started

If you're scoping a build like this:

  1. Get a Rye API key.

  2. Pull the Rye SDK (TypeScript, plus other languages).

  3. Use client.products.lookup({ url }) against a seed product, render it in your app, and complete a test checkout.

  4. Wire your webhook handler with signature validation before you go to scale.

If you're working on a high-volume rewards, gifting, or AI commerce build and want hands-on engineering support, Rye forward-deploys engineers to platforms during integration. Worth asking about.

Read the docs →

Get an API key →

Related Articles

Related Articles

Partnerships

6 minutes read

AgentCash + Rye: Physical Commerce for Agents on x402

Arjun Bhargava

Partnerships

11 minutes read

Skyfire + Rye: The End-to-End Agentic Commerce Stack — Identity and Checkout

Arjun Bhargava

Engineering

6 minutes read

How We Use Durable Execution to Power Agentic Checkout

Sophia Willows

Partnerships

6 minutes read

AgentCash + Rye: Physical Commerce for Agents on x402

Arjun Bhargava

Partnerships

11 minutes read

Skyfire + Rye: The End-to-End Agentic Commerce Stack — Identity and Checkout

Arjun Bhargava

Stop the redirect.
Start the revenue.

Get Started

Stop the redirect.
Start the revenue.

Get Started

Stop the redirect.
Start the revenue.

Get Started