Customers
In Lemon Squeezy, a customer is created when they purchase a product for the first time.
A customer belongs to a Store and can have many Orders, Subscriptions, and License Keys.
The customer object
Attributes
store_id
The ID of the store this customer belongs to.
name
The full name of the customer
The email address of the customer.
status
The email marketing status of the customer. One of
subscribed- This customer is subscribed to marketing emails.unsubscribed- This customer has unsubscribed from marketing emails.archived- This customer has been archived and will no longer recieve marketing emails.requires_verification- The customers email address need to be verified (happens automatically).invalid_email- The customers email address has failed validation.bounced- The customers email has hard bounced.
city
The city of the customer.
region
The region of the customer.
country
The country of the customer.
total_revenue_currency
A positive integer in cents representing the total revenue from the customer (USD).
mrr
A positive integer in cents representing the monthly recurring revenue from the customer (USD).
status_formatted
The formatted status of the customer.
country_formatted
The formatted country of the customer.
total_revenue_currency_formatted
A human-readable string representing the total revenue from the customer (e.g. $9.99).
mrr_formatted
A human-readable string representing the monthly recurring revenue from the customer (e.g. $9.99).
urls
An object of customer-facing URLs. It contains:
customer_portal- A pre-signed URL to the Customer Portal, which allows customers to fully manage their subscriptions and billing information from within your application. The URL is valid for 24 hours from time of request. Will benullif the customer has not bought a subscription in your store.
created_at
An ISO 8601 formatted date-time string indicating when the object was created.
updated_at
An ISO 8601 formatted date-time string indicating when the object was last updated.
test_mode
A boolean indicating if the object was created within test mode.
Customer object
{
"type": "customers",
"id": "1",
"attributes": {
"store_id": 1,
"name": "Luke Skywalker",
"email": "[email protected]",
"status": "subscribed",
"city": null,
"region": null,
"country": "US",
"total_revenue_currency": 84332,
"mrr": 1999,
"status_formatted": "Subscribed",
"country_formatted": "United States",
"total_revenue_currency_formatted": "$843.32",
"mrr_formatted": "$19.99",
"urls": {
"customer_portal": "https://my-store.lemonsqueezy.com/billing?expires=1666869343&signature=82ae290ceac8edd4190c82825dd73a8743346d894a8ddbc4898b97eb96d105a5"
},
"created_at": "2022-12-01T13:01:07.000000Z",
"updated_at": "2022-12-09T09:05:21.000000Z",
"test_mode": false
}
}
Create a customer
Create a customer.
Attributes
name
The name of the customer.
The email of the customer.
city
The city of the customer. Optional.
region
The region of the customer. Optional.
country
The ISO 3166-1 two-letter country code for the customer (e.g. US, GB, etc). Optional.
Relationships
store
The store this customer belongs to.
POST /v1/customers
curl -X "POST" "https://api.lemonsqueezy.com/v1/customers"
-H 'Accept: application/vnd.api+json'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer {api_key}'
-d $'{
"data": {
"type": "customers",
"attributes": {
"name": "Luke Skywalker",
"email": "[email protected]",
"city": "New York",
"region": "NY",
"country": "US"
}
"relationships": {
"store": {
"data": {
"type": "stores",
"id": "1"
}
}
}
}
}'
Returns
Returns a customer object.
Response
{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://api.lemonsqueezy.com/v1/customers/1"
},
"data": {
"type": "customers",
"id": "1",
"attributes": {
"store_id": 1,
"name": "Luke Skywalker",
"email": "[email protected]",
"status": "subscribed",
"city": "New York",
"region": "NY",
"country": "US",
"total_revenue_currency": 0,
"mrr": 0,
"status_formatted": "Subscribed",
"country_formatted": "United States",
"total_revenue_currency_formatted": "0.00",
"mrr_formatted": "$0.00",
"urls": {
"customer_portal": null
},
"created_at": "2022-12-01T13:01:07.000000Z",
"updated_at": "2022-12-09T09:05:21.000000Z",
"test_mode": false
},
"relationships": {
"store": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/store",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/store"
}
},
"orders": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/orders",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/orders"
}
},
"subscriptions": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/subscriptions",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/subscriptions"
}
},
"license-keys": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/license-keys",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/license-keys"
}
}
},
"links": {
"self": "https://api.lemonsqueezy.com/v1/customers/1"
}
}
}
Retrieve a customer
Retrieves the customer with the given ID.
GET /v1/customers/:id
curl "https://api.lemonsqueezy.com/v1/customers/1"
-H 'Accept: application/vnd.api+json'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer {api_key}'
Returns
Returns a customer object.
Response
{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://api.lemonsqueezy.com/v1/customers/1"
},
"data": {
"type": "customers",
"id": "1",
"attributes": {
"store_id": 1,
"name": "Luke Skywalker",
"email": "[email protected]",
"status": "subscribed",
"city": null,
"region": null,
"country": "US",
"total_revenue_currency": 84332,
"mrr": 1999,
"status_formatted": "Subscribed",
"country_formatted": "United States",
"total_revenue_currency_formatted": "$843.32",
"mrr_formatted": "$19.99",
"urls": {
"customer_portal": "https://my-store.lemonsqueezy.com/billing?expires=1666869343&signature=82ae290ceac8edd4190c82825dd73a8743346d894a8ddbc4898b97eb96d105a5"
},
"created_at": "2022-12-01T13:01:07.000000Z",
"updated_at": "2022-12-09T09:05:21.000000Z",
"test_mode": false
},
"relationships": {
"store": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/store",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/store"
}
},
"orders": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/orders",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/orders"
}
},
"subscriptions": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/subscriptions",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/subscriptions"
}
},
"license-keys": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/license-keys",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/license-keys"
}
}
},
"links": {
"self": "https://api.lemonsqueezy.com/v1/customers/1"
}
}
}
Update a customer
Update a customer.
name
The name of the customer.
The email of the customer.
city
The city of the customer.
region
The region of the customer.
country
The ISO 3166-1 two-letter country code for the customer (e.g. US, GB, etc). Optional.
status
The email marketing status of the customer. Optional. One of:
archived- This customer has been archived and will no longer receive marketing emails.
PATCH /v1/customers/:id
curl -X "PATCH" "https://api.lemonsqueezy.com/v1/customers/1"
-H 'Accept: application/vnd.api+json'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer {api_key}'
-d $'{
"data": {
"type": "customers",
"id": "1",
"attributes": {
"name": "Anakin Skywalker",
"email": "[email protected]",
"status": "archived",
}
}
}'
Returns
Returns a customers object.
Customers object
{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://api.lemonsqueezy.com/v1/customers/1"
},
"data": {
"type": "customers",
"id": "1",
"attributes": {
"store_id": 1,
"name": "Anakin Skywalker",
"email": "[email protected]",
"status": "archived",
"city": null,
"region": null,
"country": "US",
"total_revenue_currency": 0,
"mrr": 0,
"status_formatted": "Archived",
"country_formatted": "United States",
"total_revenue_currency_formatted": "$0.00",
"mrr_formatted": "$0.00",
"urls": {
"customer_portal": null
},
"created_at": "2022-12-01T13:01:07.000000Z",
"updated_at": "2022-12-09T09:05:21.000000Z",
"test_mode": false
},
"relationships": {
"store": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/store",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/store"
}
},
"orders": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/orders",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/orders"
}
},
"subscriptions": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/subscriptions",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/subscriptions"
}
},
"license-keys": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/license-keys",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/license-keys"
}
}
},
"links": {
"self": "https://api.lemonsqueezy.com/v1/customers/1"
}
}
}
List all customers
Returns a paginated list of customers.
Parameters
store_id
Only return customers belonging to the store with this ID.
Only return customers where the email field is equal to this email address.
GET /v1/customers
curl "https://api.lemonsqueezy.com/v1/customers"
-H 'Accept: application/vnd.api+json'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer {api_key}'
curl "https://api.lemonsqueezy.com/v1/customers?filter[store_id]=11"
-H 'Accept: application/vnd.api+json'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer {api_key}'
Returns
Returns a paginated list of customer objects ordered by created_at (descending).
Response
{
"meta": {
"page": {
"currentPage": 1,
"from": 1,
"lastPage": 1,
"perPage": 10,
"to": 10,
"total": 10
}
},
"jsonapi": {
"version": "1.0"
},
"links": {
"first": "https://api.lemonsqueezy.com/v1/customers?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=-createdAt",
"last": "https://api.lemonsqueezy.com/v1/customers?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=-createdAt"
},
"data": [
{
"type": "customers",
"id": "1",
"attributes": {
"store_id": 1,
"name": "Luke Skywalker",
"email": "[email protected]",
"status": "subscribed",
"city": null,
"region": null,
"country": "US",
"total_revenue_currency": 84332,
"mrr": 1999,
"status_formatted": "Subscribed",
"country_formatted": "United States",
"total_revenue_currency_formatted": "$843.32",
"mrr_formatted": "$19.99",
"urls": {
"customer_portal": "https://my-store.lemonsqueezy.com/billing?expires=1666869343&signature=82ae290ceac8edd4190c82825dd73a8743346d894a8ddbc4898b97eb96d105a5"
},
"created_at": "2022-12-01T13:01:07.000000Z",
"updated_at": "2022-12-09T09:05:21.000000Z",
"test_mode": false
},
"relationships": {
"store": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/store",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/store"
}
},
"orders": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/orders",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/orders"
}
},
"subscriptions": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/subscriptions",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/subscriptions"
}
},
"license-keys": {
"links": {
"related": "https://api.lemonsqueezy.com/v1/customers/1/license-keys",
"self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/license-keys"
}
}
},
"links": {
"self": "https://api.lemonsqueezy.com/v1/customers/1"
}
},
{...},
{...},
]
}