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


email

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


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.

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", "created_at": "2022-12-01T13:01:07.000000Z", "updated_at": "2022-12-09T09:05:21.000000Z", "test_mode": false } }

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", "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.


email

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", "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" } }, {...}, {...}, ] }