Merchants API

The Merchants API allows you to manage merchant accounts, including retrieving merchant details, checking onboarding status, and configuring dunning settings.

Overview

A merchant represents a single business entity using Lumen. All other resources, such as customers, plans, and subscriptions, are scoped to a merchant.

Authentication

All API requests require authentication via merchant credentials.

Endpoints

Get Current Merchant

Retrieves the details of the authenticated merchant.

GET https://api.getlumen.dev/v1/merchants/current

Response

{
  "id": "merch_123",
  "legalName": "Acme Inc.",
  "displayName": "Acme",
  "defaultCurrency": "USD"
}

Get Merchant by ID

Retrieves a specific merchant by their ID.

GET https://api.getlumen.dev/v1/merchants/{id}

Update Current Merchant

Updates the details of the authenticated merchant.

POST https://api.getlumen.dev/v1/merchants/current

Check Onboarding Status

Checks the onboarding status of the merchant, verifying if they have configured plans, a payment provider, and tax settings.

GET https://api.getlumen.dev/v1/merchants/checkonboarding

Response

{
  "hasPlans": true,
  "hasPaymentProvider": true,
  "hasTax": true
}

Create Merchant (Onboarding)

Creates a new merchant account. This endpoint is typically used during the onboarding process and is not available via API keys.

POST https://api.getlumen.dev/v1/merchants/onboarding-create-merchant

Get Dunning Configuration

Retrieves the dunning configuration for the merchant.

GET https://api.getlumen.dev/v1/merchants/dunning-config

Update Dunning Configuration

Updates the dunning configuration for the merchant.

POST https://api.getlumen.dev/v1/merchants/dunning-config

Get Payment Provider

Retrieves the configured payment provider for the merchant.

GET https://api.getlumen.dev/v1/merchants/payment-provider

Get Merchant Data from Stripe

Retrieves merchant data from Stripe to pre-fill onboarding fields. Requires a Stripe secret key.

POST https://api.getlumen.dev/v1/merchants/merchant-data