Skip to main content

​
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.
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

1

Create the order

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

Start provider payment

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

Render affiliate dashboard data

Your dashboard reads affiliate stats and balance data from Shoppex.
4

Handle balance actions

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

​
1. Create The Order

Create the invoice or order from your frontend or backend and attach the affiliate code. Simple example:
  • your backend calls the invoice create flow
  • it includes affiliate_code: "creator123"
  • Shoppex stores the affiliate attribution on the invoice
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. Simple example:
  • create the invoice
  • create a Stripe or PayPal payment session
  • send the customer into that provider flow
  • 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
Simple 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
  }'
Simple example:
  • affiliate balance has 25
  • user enters 10
  • Shoppex creates the balance claim
  • Shoppex 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. Simple example: the API stores a payout request, then 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"
  }'
Simple example:
  • affiliate enters an amount and wallet address
  • your UI submits the payout request
  • Shoppex stores the request cleanly
  • 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.
A good starting scope set for this type of portal is:
ScopeWhy you usually need it
customers.readRead affiliate summaries and customer-linked data
customers.writeConvert balances and create payout requests
orders.readShow order history or order-linked affiliate activity
invoices.readRead invoice state for payment and attribution context
If the same integration also manages recurring billing, add subscription scopes separately.

​
Good 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