Merchant Docs Center

Merchant docs that show what to create, where to view it, and when API work is actually necessary.

This page walks merchants through registration, store setup, offer publishing, reporting, and the lowest-cost integration path before they commit to deeper engineering work.

Become a PartnerSign In to MerchantView Partnership Page
QuickstartWhere to viewIntegration pathsAPI flow
Quickstart

For a first-time merchant, this is the order that keeps setup simple.

The core actions already exist in the current merchant portal. This hub is not just an API page. It tells merchants where to click and what to do first.

01
/register

Create your partner account

Start on the registration page and create a merchant account. If you already have one, sign in and move straight into the portal.

Open Register
02
/merchant/stores

Create your first store

Use the Stores page to define the name, slug, domain, description, and category. Every rule and redemption attaches to a store record.

Open Stores
03
/merchant/coupons

Publish your first offer rule

Use the Coupons page to create a simple percentage or fixed amount rule first. Validate the commercial loop before layering advanced conditions.

Open Coupons
04
/merchant

Review campaign performance in the dashboard

The dashboard shows active rules, recent redemptions, average discount size, and activity intensity so you can see if the offer is working.

Open Dashboard
05
/merchant/settings

Generate API keys and webhooks

Use Settings to create one API key, copy the secret once, and add webhook endpoints only if you need real-time event delivery.

Open Settings
06
/merchant/integration

Validate setup in Integration

This page gives you HTML, React, and server snippets plus a live smoke test for key readiness, rules, quote evaluation, and signature generation.

Open Integration
07
/merchant/orders

Use Orders for redemptions and exports

The Orders page shows redemption history, discount impact, final paid values, and CSV export for finance or partner operations review.

Open Orders
Where To View

After you create things, this is where you manage and inspect them.

Once registration is done, these pages become the daily operator workflow for stores, offers, redemptions, API keys, and validation.

Monitor/merchant

Dashboard

Use it for the high-level view of campaigns, recent redemptions, and average discount behavior.

Create/merchant/stores

Stores

Create and edit store profiles, then confirm the domain, slug, and base commercial identity.

Publish/merchant/coupons

Coupons

Create, edit, and delete discount rules while tracking usage counts and effective windows.

Configure/merchant/settings

Settings

Manage profile, API keys, and webhooks, including one-time secret retrieval.

Validate/merchant/integration

Integration

Choose HTML, React, or server snippets and run the live smoke test from one place.

Review/merchant/orders

Orders

Inspect the redemption ledger, order values, discount totals, and export CSV when needed.

Integration Paths

Choose the lowest-cost path first, then decide if deeper integration is worth it.

Not every partner should modify checkout on day one. For many third-party merchants, the smallest-change path is the right way to validate ROI.

Recommended first

No-code / lowest-cost path

Let the merchant keep using existing coupon-code or landing-page mechanics while Couponify handles member gating, entitlement distribution, and offer operations.

Almost no third-party software changes.
Good for proving conversion and ROI first.
Ideal for pilot merchants such as Beautinow.
One script

Low-code / frontend script path

If a merchant accepts minimal frontend change, place the Couponify SDK in cart or checkout and use connect popup plus quote-based member pricing.

Usually limited to frontend script or component work.
Does not force a full backend rewrite.
Best for surfacing member pricing quickly.
Deep integration

Full API / server-side path

Move into quote / redeem / rollback only when you need automated redemption, strict rollback behavior, and reconciled financial reporting.

Better for scaled or deeply integrated merchants.
Redeem automatically after successful payment.
Rollback automatically after refunds.
API Sequence

Only move into quote / redeem / rollback when deeper automation is justified.

The three-call integration still matters, but it belongs after the operating model is clear so merchants are not forced into engineering details too early.

1. Quote in the storefront

  • Use the JS SDK with a short-lived member JWT
  • Pass store_id, cart items, and total amount
  • Render best_benefit.final_price and member badges

2. Redeem after payment

  • Send Idempotency-Key on every redeem call
  • Authenticate with x-api-key, x-timestamp, x-signature
  • Persist the returned redemption_id on the merchant order

3. Roll back on refunds

  • Use a new Idempotency-Key for rollback
  • Pass the original order_id and refund reason
  • Couponify restores rule usage automatically
Frontend SDKLowest frontend change
import { Couponify } from '@couponify/sdk';

Couponify.init({
  storeId: 'beautinow',
  apiBaseUrl: 'https://api.couponify.ai/api',
  mode: 'auto',
  getCart: () => ({
    items: cart.items.map((item) => ({
      sku: item.sku,
      category: item.category,
      unit_price: item.price,
      quantity: item.quantity,
    })),
    amount: cart.total,
  }),
});
Redeem APIAfter successful payment
const timestamp = Date.now().toString();
const body = {
  order_id: "ord_9001",
  store_id: "beautinow",
  quote_id: "quote_123",
  final_paid_amount: 80,
  currency: "USD",
};

const signature = hmacSha256(
  merchantSecret,
  `${timestamp}.${JSON.stringify(body)}`,
);

await fetch("https://api.couponify.ai/api/redeem", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-api-key": merchantKey,
    "x-timestamp": timestamp,
    "x-signature": signature,
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify(body),
});
FAQ

The questions merchants ask most often.

If you need to send one page to a merchant team or BD contact, this should explain how to create, where to view, and how much code they actually need to change.

Does the merchant need to modify their storefront?

Not necessarily. The lowest-cost path is to avoid or minimize third-party changes and validate the business first with the merchant's existing coupon mechanics plus Couponify entitlements.

Where should I generate API keys first?

Sign in to the merchant portal and open /merchant/settings. Copy the one-time secret there before moving into Integration for validation.

How do I know the integration is actually working?

Open /merchant/integration, choose the target store, inspect the snippet, and run the live smoke test. It checks keys, rules, quote behavior, and signature generation.

Where do I inspect real redemptions and exports?

Use /merchant/orders. It shows the redemption ledger, discount impact, final order values, and CSV export.