Sellers API

The Sellers API allows you to manage marketplace sellers with MyBerryFlow's unique deferred KYC approach. Sellers can start earning immediately with minimal information, while compliance verification happens in the background.

Create a seller

Create a new seller account with minimal information. The seller can start earning immediately while KYC verification happens later based on revenue thresholds.

curl -X POST https://api.myberryflow.com/api/sellers/create-deferred-account-for-seller-as-default \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "seller@example.com",
    "country": "US"
  }'

Response

{
  "sellerId": "seller_abc123",
  "marketplaceId": "mp_xyz789", 
  "email": "seller@example.com",
  "country": "US",
  "status": "active",
  "onboardingType": "deferred",
  "canReceivePayments": true,
  "canReceivePayouts": false,
  "kycStatus": "not_required",
  "kycThreshold": 10000,
  "totalRevenue": 0,
  "stripeAccountId": "acct_1234567890",
  "createdAt": "2024-01-15T10:30:00Z"
}

List sellers

Retrieve a list of all sellers for your marketplace.

curl -X GET https://api.myberryflow.com/api/sellers/list \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json"

Response

{
  "data": [
    {
      "sellerId": "seller_abc123",
      "email": "seller@example.com", 
      "country": "US",
      "status": "active",
      "kycStatus": "not_required",
      "totalRevenue": 5000,
      "canReceivePayments": true,
      "canReceivePayouts": false,
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "sellerId": "seller_def456",
      "email": "seller2@example.com",
      "country": "CA", 
      "status": "pending_onboarding",
      "kycStatus": "required",
      "totalRevenue": 12000,
      "canReceivePayments": true,
      "canReceivePayouts": false,
      "createdAt": "2024-01-14T15:20:00Z"
    }
  ],
  "hasMore": false,
  "count": 2
}

Seller Status Lifecycle

Understanding seller statuses is key to managing your marketplace:

Status Types

• pending - Seller account created, awaiting Stripe account setup
• active - Seller can receive payments to platform account
• pending_onboarding - Seller hit KYC threshold, needs identity verification
• restricted - Seller account has compliance issues
• verified - Seller completed KYC, can receive direct payouts

KYC Status Types

• not_required - Below revenue threshold, no KYC needed
• required - Above threshold, KYC verification needed
• pending - KYC submission in review
• completed - KYC verification successful
• failed - KYC verification failed, seller needs to resubmit

Deferred KYC Model

How it works:

1. Minimal onboarding - Seller provides email and country only
2. Immediate payments - Can start receiving payments to your platform account
3. Revenue tracking - MyBerryFlow tracks seller revenue automatically
4. Automatic KYC trigger - When threshold is reached, seller gets notified to complete verification
5. Direct payouts - After KYC completion, seller can receive direct payouts

Webhook Events

MyBerryFlow sends webhooks for important seller events:

• seller.created - New seller account created
• seller.kyc_required - Seller hit revenue threshold, needs KYC
• seller.kyc_submitted - Seller submitted KYC information
• seller.verified - Seller completed KYC verification
• seller.kyc_failed - KYC verification failed

{
  "type": "seller.kyc_required",
  "data": {
    "sellerId": "seller_abc123",
    "email": "seller@example.com",
    "totalRevenue": 10000,
    "kycThreshold": 10000,
    "onboardingUrl": "https://connect.stripe.com/setup/..."
  },
  "created": "2024-01-15T12:00:00Z"
}