Headless Affiliate And Customer Portals

Overview

Use this setup when you want the frontend to feel fully yours, but you still want Shoppex to handle the hard backend parts.

Your Frontend

You control the branding, layout, auth flow, and customer experience.

Shoppex Backend

Shoppex handles order creation, affiliate attribution, balances, and payout requests.

API-First Flow

You connect your app to Shoppex through API endpoints instead of using a hosted dashboard UI.

This guide is for merchants who want a white-label customer or affiliate portal.

What Shoppex Handles

Orders With Affiliate Attribution

Create an order and attach an affiliate_code so the referral stays linked to the invoice.

Affiliate Stats And Balance

Read referral links, clicks, sales, commissions, claims, and balance buckets for your frontend.

Convert To Store Balance

Let affiliates move approved earnings into store balance with an API-triggered action.

Crypto Payout Requests

Accept payout requests without forcing automatic onchain payouts.

Recommended Portal Experience

For a strong headless setup, your portal usually needs three surfaces:

Orders

Show invoices, payment state, and order history.

Affiliate

Show referral code, referral link, clicks, conversions, and commissions.

Balance Actions

Let affiliates convert earnings into store balance or request a payout.

Typical Integration Flow

Create the order

Your frontend or backend creates the order and includes the affiliate code.

Start provider payment

Your app starts the payment session for the gateway you want, like Stripe or PayPal.

Render affiliate dashboard data

Your dashboard reads affiliate stats and balance data from Shoppex.

Handle balance actions

Your UI lets the affiliate convert earnings into store balance or submit a payout request.

Resolve And Attribute Affiliate Codes In A Custom Storefront

If you run your own storefront, use the Storefront affiliate endpoints before checkout to validate a code and read its customer discount metadata. When a customer lands on ?ref=creator10, your frontend calls POST /v1/storefront/affiliates/resolve to check if the code is valid and whether it unlocks a discount. When the customer continues, your frontend calls POST /v1/storefront/affiliates/attribution to lock in the referral.

These are Storefront API endpoints under /v1/storefront/*, not Dev API endpoints under /dev/v1/*.

curl -X POST https://api.shoppex.io/v1/storefront/affiliates/resolve \
  -H "Content-Type: application/json" \
  -d '{
    "shop_slug": "cheatsmarket",
    "code": "creator10"
  }'

Resolve response example:

{
  "status": 200,
  "data": {
    "valid": true,
    "affiliate_code": "creator10",
    "discount_active": true,
    "discount_percent": 12
  }
}

Attribution response example:

{
  "status": 200,
  "data": {
    "accepted": true,
    "affiliate_code": "creator10",
    "discount_active": true,
    "discount_percent": 12
  }
}

If discount_active is true and discount_percent is 12, your storefront can immediately show “12% affiliate discount applied”. This makes it easier to build a custom referral banner, pricing preview, or coupon-style affiliate UX without guessing the effective discount.

1. Create The Order

Create the invoice or order from your frontend or backend and attach the affiliate code. Your backend calls the invoice create flow and includes affiliate_code: "creator123" — Shoppex stores the affiliate attribution on the invoice automatically.

Use this when you want your own landing page, pricing page, or custom checkout entry point.

This keeps the affiliate relationship on the order and uses the same attribution rules as the modern storefront flow.

2. Start Payment With The Provider You Want

You do not need to use a generic Shoppex checkout page if your flow is more API-first. Create the invoice, start a Stripe or PayPal payment session, send the customer into that provider flow, and let Shoppex complete the invoice through the normal payment lifecycle.

Think of Shoppex as the payment and accounting backend, while your frontend stays fully branded.

3. Read Affiliate Data For Your Frontend

For a headless customer or affiliate dashboard, use the Dev API affiliate endpoints.

Affiliate Summary

GET /dev/v1/customers/{id}/affiliate

Convert To Balance

POST /dev/v1/customers/{id}/affiliate/convert-to-balance

Payout Request

POST /dev/v1/customers/{id}/affiliate/payout-requests

curl https://api.shoppex.io/dev/v1/customers/cus_123/affiliate \
  -H "Authorization: Bearer shx_your_api_key"

The affiliate summary gives your frontend the building blocks for a real dashboard:

referral link and code
clicks and sales
commissions
claims
balance buckets like available, requested, and converted

Example response:

{
  "data": {
    "customer_id": "cus_123",
    "state": "active",
    "link": {
      "code": "creator123",
      "url": "https://example.test/?ref=creator123",
      "total_clicks": 14,
      "total_sales": 3,
      "total_revenue": 299
    },
    "balances": {
      "available": 25,
      "requested": 0,
      "converted": 0
    }
  }
}

4. Convert Affiliate Balance Into Store Balance

This is the self-serve flow for affiliates who want to spend their earnings inside the store instead of cashing out.

curl -X POST https://api.shoppex.io/dev/v1/customers/cus_123/affiliate/convert-to-balance \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: affiliate-convert-001" \
  -d '{
    "amount": 25
  }'

If the affiliate balance is 25 and the user enters 10, Shoppex creates the balance claim and credits 10 into store balance. Example response:

{
  "data": {
    "claim_id": "claim_123",
    "amount": 10,
    "status": "COMPLETED",
    "wallet_transaction_id": "wallet_tx_123",
    "new_balance": 10
  }
}

Use idempotency keys for button-triggered actions so retries do not duplicate balance conversions.

5. Create A Crypto Payout Request

This flow is for affiliates who want to request a payout without forcing fully automatic onchain settlement.

This does not go through a payment gateway like Stripe or PayPal. The API stores a payout request, and your own ops flow, webhook consumer, or treasury process decides whether and how the crypto payout gets fulfilled.

curl -X POST https://api.shoppex.io/dev/v1/customers/cus_123/affiliate/payout-requests \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: affiliate-payout-001" \
  -d '{
    "amount": 7,
    "asset": "usdt",
    "address": "TQ2nBylQp1n7hT8t9r3V7A4C6X9K1M2P3Q",
    "network": "tron",
    "note": "Pay out weekly affiliate earnings"
  }'

The affiliate enters an amount and wallet address, your UI submits the payout request, Shoppex stores it, and your ops flow or webhook worker decides what happens next. Example response:

{
  "data": {
    "claim_id": "claim_456",
    "amount": 7,
    "status": "PENDING",
    "asset": "USDT",
    "address": "TQ2nBylQp1n7hT8t9r3V7A4C6X9K1M2P3Q",
    "network": "tron",
    "note": "Pay out weekly affiliate earnings"
  }
}

This request flow is intentionally safer than “blind auto payout”. It gives you an approval or ops step instead of pushing funds automatically.

6. Process Payout Requests In Your Merchant UI

If you are building a headless merchant dashboard or an ops backoffice, you can now process affiliate payout requests through the Dev API as well. The affiliate submits a payout request, your merchant tool lists pending requests, your ops user approves or rejects, and the affiliate sees the updated state in their portal.

List Requests

GET /dev/v1/affiliates/payout-requests

Approve Request

POST /dev/v1/affiliates/payout-requests/{id}/approve

Reject Request

POST /dev/v1/affiliates/payout-requests/{id}/reject

Complete Or Cancel

POST /dev/v1/affiliates/payout-requests/{id}/complete and POST /dev/v1/affiliates/payout-requests/{id}/cancel

curl https://api.shoppex.io/dev/v1/affiliates/payout-requests?status=pending \
  -H "Authorization: Bearer shx_your_api_key"

Example list response:

{
  "data": {
    "payout_requests": [
      {
        "id": "claim_456",
        "affiliate_customer_id": "cus_123",
        "affiliate_code": "creator123",
        "affiliate_email": "[email protected]",
        "status": "pending",
        "amount": 7,
        "currency": "USD",
        "payout_asset": "USDT",
        "payout_network": "tron",
        "payout_address": "TQ2nBylQp1n7hT8t9r3V7A4C6X9K1M2P3Q",
        "note": "Pay out weekly affiliate earnings"
      }
    ],
    "page": 1,
    "limit": 25,
    "total": 1
  }
}

Example action response:

{
  "data": {
    "status": "processing",
    "already_updated": false
  }
}

Use affiliates.read to list merchant-side payout requests and affiliates.write for approve, reject, complete, and cancel actions.

Recommended Scopes

A good starting scope set for this type of portal is:

Scope	Why you usually need it
`affiliates.read`	List affiliate applications, merchant payout requests, and partner ops data
`affiliates.write`	Approve or reject applications and process payout requests
`customers.read`	Read affiliate summaries and customer-linked data
`customers.write`	Convert balances and create payout requests
`orders.read`	Show order history or order-linked affiliate activity
`invoices.read`	Read invoice state for payment and attribution context

If the same integration also manages recurring billing, add subscription scopes separately.

Implementation Rule

Keep one clear source of truth:

Shoppex owns affiliate balances, claims, payout requests, and invoice attribution
your frontend owns branding, navigation, and UX

That split keeps the system clean and avoids fragile merchant-specific logic.

Best Fit

This setup is a strong fit when you want:

a fully branded customer portal
a branded affiliate dashboard
custom onboarding or checkout entry pages
Shoppex handling the accounting and payment-side complexity in the background

Getting Started

Core Concepts

Integrations

Headless Affiliate And Customer Portals

Overview

Your Frontend

Shoppex Backend

API-First Flow

What Shoppex Handles

Orders With Affiliate Attribution

Affiliate Stats And Balance

Convert To Store Balance

Crypto Payout Requests

Recommended Portal Experience

Orders

Affiliate

Balance Actions

Typical Integration Flow

Resolve And Attribute Affiliate Codes In A Custom Storefront

1. Create The Order

2. Start Payment With The Provider You Want

3. Read Affiliate Data For Your Frontend

Affiliate Summary

Convert To Balance

Payout Request

4. Convert Affiliate Balance Into Store Balance

5. Create A Crypto Payout Request

6. Process Payout Requests In Your Merchant UI

List Requests

Approve Request

Reject Request

Complete Or Cancel

Recommended Scopes

Implementation Rule

Best Fit

Getting Started

Core Concepts

Integrations

Documentation Index

​Overview

Your Frontend

Shoppex Backend

API-First Flow

​What Shoppex Handles

Orders With Affiliate Attribution

Affiliate Stats And Balance

Convert To Store Balance

Crypto Payout Requests

​Recommended Portal Experience

Orders

Affiliate

Balance Actions

​Typical Integration Flow

​Resolve And Attribute Affiliate Codes In A Custom Storefront

​1. Create The Order

​2. Start Payment With The Provider You Want

​3. Read Affiliate Data For Your Frontend

Affiliate Summary

Convert To Balance

Payout Request

​4. Convert Affiliate Balance Into Store Balance

​5. Create A Crypto Payout Request

​6. Process Payout Requests In Your Merchant UI

List Requests

Approve Request

Reject Request

Complete Or Cancel

​Recommended Scopes

​Implementation Rule

​Best Fit

Overview

What Shoppex Handles

Recommended Portal Experience

Typical Integration Flow

Resolve And Attribute Affiliate Codes In A Custom Storefront

1. Create The Order

2. Start Payment With The Provider You Want

3. Read Affiliate Data For Your Frontend

4. Convert Affiliate Balance Into Store Balance

5. Create A Crypto Payout Request

6. Process Payout Requests In Your Merchant UI

Recommended Scopes

Implementation Rule

Best Fit