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


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 be null if 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.


email

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.


email

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.


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