Guides

Connect a storefront

A store connector mirrors your product catalog into SmoothProfit. Without it, affiliate storefronts have nothing to show and per-product commission rules have nothing to match.

The catalog is a one-way mirror

Your store owns the products. SmoothProfit keeps a copy so it can render storefronts and resolve commissions — it never writes back. Two systems editing one catalog is how prices end up disagreeing.

The sync is the only writer — except for two fields the agency curates locally, is_visible and sort_order, which a sync never overwrites.
Products that disappear are archived, never deleted, so historical conversions still resolve to a product name.
A failed fetch aborts the whole sync. A partially-fetched catalog is indistinguishable from “most products were deleted” and would archive your entire store.

Connecting

In the agency console, open your program's Products page and supply the connector, your store's API base URL, the brand identifier, and an API key. The credential is verified before it is saved — a bad key is rejected at setup rather than surfacing later as an empty storefront.

The key is encrypted at rest. Only its last four characters are stored in the clear, so the console can show you which credential is installed without it being recoverable.

Syncing

Run a sync from the same page. Every run is recorded — created, updated, archived, and any error — because the failure modes here are silent by nature. A stale credential or a renamed upstream field otherwise shows up only as “the storefront is empty”.

Discovering connectors

bash

curl https://app.smoothprofit.app/api/v1/providers/store \
  -H "Authorization: Bearer sp_live_your_key"

Writing a connector

Connectors implement a small interface: test a connection, fetch products, build a checkout URL carrying a referral code. Adding one is a class plus a catalog row — the sync engine never changes.

export class MyStoreAdapter implements StoreConnector {
  readonly id = "mystore";
  readonly name = "My Store";

  async testConnection(config) { /* verify the credential */ }
  async fetchProducts(config) { /* return the whole catalog */ }
  buildCheckoutUrl({ config, product, referralCode }) { /* attach ?ref= */ }
}

Two things to get right in fetchProducts: return money in cents even if your store uses decimals, and key on a stable id rather than a SKU. A nullable or reusable SKU produces duplicate products on every sync.

The catalog is a one-way mirror

The sync is the only writer — except for two fields the agency curates locally, is_visible and sort_order, which a sync never overwrites.

Products that disappear are archived, never deleted, so historical conversions still resolve to a product name.

A failed fetch aborts the whole sync. A partially-fetched catalog is indistinguishable from “most products were deleted” and would archive your entire store.

Connecting

The key is encrypted at rest. Only its last four characters are stored in the clear, so the console can show you which credential is installed without it being recoverable.

Writing a connector

Connectors implement a small interface: test a connection, fetch products, build a checkout URL carrying a referral code. Adding one is a class plus a catalog row — the sync engine never changes.

export class MyStoreAdapter implements StoreConnector {
  readonly id = "mystore";
  readonly name = "My Store";

  async testConnection(config) { /* verify the credential */ }
  async fetchProducts(config) { /* return the whole catalog */ }
  buildCheckoutUrl({ config, product, referralCode }) { /* attach ?ref= */ }
}