Skip to main content
POST
/
v1
/
customers
curl -X POST https://api.flexprice.io/v1/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_12345",
    "name": "Acme Corporation",
    "email": "billing@acme.com",
    "address_line1": "123 Main Street",
    "address_city": "San Francisco",
    "address_state": "CA",
    "address_postal_code": "94105",
    "address_country": "US",
    "metadata": {
      "plan_tier": "enterprise",
      "account_manager": "jane_doe"
    }
  }'

{
  "id": "cust_abc123xyz789",
  "external_id": "user_12345",
  "name": "Acme Corporation",
  "email": "billing@acme.com",
  "address_line1": "123 Main Street",
  "address_line2": "",
  "address_city": "San Francisco",
  "address_state": "CA",
  "address_postal_code": "94105",
  "address_country": "US",
  "parent_customer_id": null,
  "metadata": {
    "plan_tier": "enterprise",
    "account_manager": "jane_doe"
  },
  "environment_id": "env_prod_001",
  "tenant_id": "tenant_001",
  "status": "published",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "created_by": "user_admin",
  "updated_by": "user_admin"
}
Use this endpoint when onboarding a new billing customer (e.g., sign-up or CRM sync). Ideal for linking via external_id to your app’s user ID.

​
Request Body

​
external_id
string
required
The unique identifier from your system to reference this customer. This is required and should match your internal user or account ID.
​
name
string
The full name or company name of the customer.
​
email
string
The customer’s email address. Must be a valid email format if provided.
​
address_line1
string
The primary address line. Maximum 255 characters.
​
address_line2
string
The secondary address line. Maximum 255 characters.
​
address_city
string
The city name. Maximum 100 characters.
​
address_state
string
The state, province, or region name. Maximum 100 characters.
​
address_postal_code
string
The ZIP code or postal code. Maximum 20 characters.
​
address_country
string
The two-letter ISO 3166-1 alpha-2 country code (e.g., “US”, “GB”, “CA”).
​
metadata
object
Additional key-value pairs for storing extra information about the customer.
{
  "internal_id": "user_12345",
  "signup_source": "web"
}
​
parent_customer_id
string
The internal FlexPrice ID of the parent customer for hierarchical customer relationships.
​
parent_customer_external_id
string
The external ID of the parent customer from your system. Provide either parent_customer_id or parent_customer_external_id, but not both.
​
integration_entity_mapping
array
Provider integration mappings for this customer (e.g., Stripe, Razorpay, PayPal).
​
skip_onboarding_workflow
boolean
default:false
When true, prevents the customer onboarding workflow from being triggered. Used internally to prevent infinite loops.

​
Response

​
id
string
The unique FlexPrice customer ID (e.g., cust_abc123).
​
external_id
string
The external identifier you provided.
​
name
string
The customer’s name or company name.
​
email
string
The customer’s email address.
​
address_line1
string
Primary address line.
​
address_line2
string
Secondary address line.
​
address_city
string
City name.
​
address_state
string
State or region name.
​
address_postal_code
string
Postal code.
​
address_country
string
Two-letter country code.
​
parent_customer_id
string
The parent customer ID if this is a child customer.
​
metadata
object
Custom metadata key-value pairs.
​
environment_id
string
The environment ID this customer belongs to.
​
tenant_id
string
The tenant ID this customer belongs to.
​
status
string
The status of the customer (e.g., published).
​
created_at
string
ISO 8601 timestamp of when the customer was created.
​
updated_at
string
ISO 8601 timestamp of when the customer was last updated.
​
created_by
string
The ID of the user who created the customer.
​
updated_by
string
The ID of the user who last updated the customer.
curl -X POST https://api.flexprice.io/v1/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_12345",
    "name": "Acme Corporation",
    "email": "billing@acme.com",
    "address_line1": "123 Main Street",
    "address_city": "San Francisco",
    "address_state": "CA",
    "address_postal_code": "94105",
    "address_country": "US",
    "metadata": {
      "plan_tier": "enterprise",
      "account_manager": "jane_doe"
    }
  }'

{
  "id": "cust_abc123xyz789",
  "external_id": "user_12345",
  "name": "Acme Corporation",
  "email": "billing@acme.com",
  "address_line1": "123 Main Street",
  "address_line2": "",
  "address_city": "San Francisco",
  "address_state": "CA",
  "address_postal_code": "94105",
  "address_country": "US",
  "parent_customer_id": null,
  "metadata": {
    "plan_tier": "enterprise",
    "account_manager": "jane_doe"
  },
  "environment_id": "env_prod_001",
  "tenant_id": "tenant_001",
  "status": "published",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "created_by": "user_admin",
  "updated_by": "user_admin"
}