Skip to content

felixonmars/lemonsqueezy.js

BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

16 Commits
.gitattributes
.gitattributes
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
index.js
index.js
 
 
package.json
package.json
 
 

Repository files navigation

The official Lemon Squeezy JavaScript SDK

Introduction

This is the official JavsScript SDK for Lemon Squeezy, helping make it easy to incorporate billing into your JavaScript application.

Please read the API introduction page to understand how the API works.

Installation

Install the package

Install with npm install @lemonsqueezy/lemonsqueezy.js

Create an API key

Create a new API key from Settings > API in your Lemon Squeezy dashboard.

Add this API key into your project, for example as LEMONSQUEEZY_API_KEY in your .env file.

Usage

Basic usage

import LemonSqueezy from '@lemonsqueezy/lemonsqueezy.js'
const ls = new LemonSqueezy(process.env.LEMONSQUEEZY_API_KEY);

const products = await ls.getProducts()

Parameters for requests should be passed in an object. For list methods, these parameters are used for filtering and for list pagination. For create and update methods, these parameters contain the values for the request.

const subscriptions = await ls.getSubscriptions({ storeId: 123, perPage: 50 })

const subscription = await ls.getSubscription({ id: 123, include: 'subscription-invoices' })

const subscription = await ls.cancelSubscription({ id: 123 })

Including related resources

You can use include in every "read" method to pull in related resources (works for both individual and list methods).

const product = await ls.getProduct({ id: 123, include: 'variants' })

Pagination

Endpoints that return a list of results can be paged using optional page and perPage values. If perPage is omitted, the API returns the default of 10 results per page. perPage should be a value between 1 and 100.

// Querying a list of orders for store #3, 50 records per page, page 2, including store and customer related resoueces
const order = await ls.getOrders({ storeId: 3, perPage: 50, page: 2, include: 'store,customer' })

Looping lists

You can also use page and perPage to loop lists of results.

"List" method responses contain a meta.page object, which describes the pagination of your request.

{
  "meta": {
    "page": {
      "currentPage": 1,
      "from": 1,
      "lastPage": 16,
      "perPage": 10,
      "to": 10,
      "total": 154
    }
  },
  ...
}

In this example, you can use the lastPage value to check if you are on the last page of results.

let hasNextPage = true
let perPage = 100
let page = 1
let variants = []
while (hasNextPage) {
  const resp = await ls.getVariants({ perPage, page });
  
  variants = variants.concat(resp['data'])

  if (resp.meta.page.lastPage > page) {
    page += 1
  } else {
    hasNextPage = false
  }
}

Handling errors

Each method will throw an exception if there are issues with the request. JSON will be returned containing error details.

Use try { ... } catch { ... } to access this object. Error messages will be available in a list in errors.

// "something" is not a valid value for `include`
try {
  const subscriptions = await ls.getSubscriptions({ include: 'something' })
} catch (err) {
  // `err` is an object like this:
  //  {
  //   "jsonapi": {
  //     "version": "1.0"
  //   }
  //   "errors": [
  //     {
  //       "detail": "Include path something is not allowed.",
  //       "source": {
  //         "parameter": "include"
  //       },
  //       "status": "400",
  //       "title": "Invalid Query Parameter"
  //     }
  //   ]
  // }
}

Notes

Do not use this package directly in the browser. as this will expose your API key. This would give anyone full API access to your Lemon Squeezy account and store(s).

Methods

getUser()

Get the current user.

Returns a User object.

API reference.

Parameters

None.

Example

const user = await ls.getUser()

getStores(parameters)

Get the current user's stores.

Returns a list of Store objects.

API reference.

Parameters

Parameter Type Required Default Notes
perPage number 10
page number 1
include string Comma-separated list of object names:
  • products
  • discounts
  • license-keys
  • subscriptions
  • webhooks

Example

const stores = await ls.getStores()

const stores = await ls.getStores({ include: 'products' })

getStore(parameters)

Get a store.

Returns a Store object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
include string - - Comma-separated list of object names:
  • products
  • discounts
  • license-keys
  • subscriptions
  • webhooks

Example

const store = await ls.getStore({ id: 123 })

getProducts(parameters)

Get a list of products.

Returns a list of Product objects.

API reference.

Parameters

Parameter Type Required Default Notes
storeId number - - Filter products by store.
perPage number - 10
page number - 1
include string - - Comma-separated list of object names:
  • store
  • variants

Example

const products = await ls.getProducts()

const products = await ls.getProducts({ storeId: 123, perPage: 50, include: 'variants' })

getProduct(parameters)

Get a product.

Returns a Product object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
include string - - Comma-separated list of object names:
  • store
  • variants

Example

const product = await ls.getProduct({ id: 123 })

getVariants(parameters)

Get a list of variants.

Returns a list of Variant objects.

API reference.

Parameters

Parameter Type Required Default Notes
productId number - - Filter variants by product.
perPage number - 10
page number - 1
include string - - Comma-separated list of object names:
  • product
  • files

Example

const variants = await ls.getVariants()

const variants = await ls.getVariants({ productId: 123, perPage: 50, include: 'product' })

getVariant(parameters)

Get a variant.

Returns a Variant object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
include string - - Comma-separated list of object names:
  • product
  • files

Example

const variant = await ls.getVariant({ id: 123 })

getCheckouts(parameters)

Get a list of checkouts.

Returns a list of Checkout objects.

API reference.

Parameters

Parameter Type Required Default Notes
storeId number - - Filter checkouts by store.
variantId number - - Filter checkouts by variant.
perPage number - 10
page number - 1
include string - - Comma-separated list of object names:
  • store
  • variant

Example

const checkouts = await ls.getCheckouts()

const checkouts = await ls.getCheckouts({ storeId: 123, perPage: 50 })

getCheckout(parameters)

Get a checkout.

Returns a Checkout object.

API reference.

Parameters

Parameter Type Required Default Notes
id string Yes - Checkout IDs are UUIDs.
include string - - Comma-separated list of object names:
  • store
  • variant

Example

const checkout = await ls.getCheckout({ id: 'edc0158c-794a-445d-bfad-24ab66baeb01' })

createCheckout(parameters)

Create a checkout.

This method allows you to retrieve a product's checkout URL (using store and variant IDs) or create fully customised checkouts (using additional attributes).

Returns a Checkout object.

API reference.

Parameters

Parameter Type Required Default Notes
storeId number Yes -
variantId number Yes -
attributes Object - - An object of values used to configure the checkout.

Example

let attributes = {
  checkout_data: {
    email: 'user@gmail.com',
    discount_code: '10PERCENT',
    custom: {
      user_id: 123
    }
  },
  product_options: {
    redirect_url: 'https://customredirect.com'
  },
  checkout_options: {
    dark: true,
    logo: false
  }
}

const checkout = await ls.createCheckout({ storeId: 123, variantId: 123, attributes })

getCustomers(parameters)

Get a list of customers.

Returns a list of Customer objects.

API reference.

Parameters

Parameter Type Required Default Notes
storeId number - - Filter customers by store.
email string - - Filter customers by email address.
perPage number - 10
page number - 1
include string - - Comma-separated list of object names:
  • license-keys
  • orders
  • store
  • subscriptions

Example

const customers = await ls.getCustomers()

const customers = await ls.getCustomers({ email: 'customer@gmail.com', include: 'orders,license-keys,subscriptions' })

getCustomer(parameters)

Get a customer.

Returns a Customer object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
include string - - Comma-separated list of object names:
  • license-keys
  • orders
  • store
  • subscriptions

Example

const customer = await ls.getCustomer({ id: 123 })

getOrders(parameters)

Get a list of orders.

Returns a list of Order objects.

API reference.

Parameters

Parameter Type Required Default Notes
storeId number - - Filter orders by store.
userEmail string - - Filter orders by email address.
perPage number - 10
page number - 1
include string - - Comma-separated list of object names:
  • customer
  • discount-redemptions
  • license-keys
  • order-items
  • store
  • subscriptions

Example

const orders = await ls.getOrders()

const orders = await ls.getOrders({ email: 'customer@gmail.com', include: 'orders,license-keys,subscriptions' })

getOrder(parameters)

Get an order.

Returns an Order object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
include string - - Comma-separated list of object names:
  • customer
  • discount-redemptions
  • license-keys
  • order-items
  • store
  • subscriptions

Example

const order = await ls.getOrder({ id: 123 })

getFiles(parameters)

Get a list of files.

Returns a list of File objects.

API reference.

Parameters

Parameter Type Required Default Notes
variantId number - - Filter files by variant.
perPage number - 10
page number - 1
include string - - Comma-separated list of object names:
  • variant

Example

const files = await ls.getFiles()

const files = await ls.getFiles({ variantId: 123 })

getFile(parameters)

Get a file.

Returns a File object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
include string - - Comma-separated list of object names:
  • variant

Example

const file = await ls.getFile({ id: 123 })

getOrderItems(parameters)

Get a list of order items.

Returns a list of Order item objects.

API reference.

Parameters

Parameter Type Required Default Notes
orderId number - - Filter order items by order.
productId number - - Filter order items by product.
variantId number - - Filter order items by variant.
perPage number - 10
page number - 1
include string - - Comma-separated list of object names:
  • order
  • product
  • variant

Example

const orderItems = await ls.getOrderItems()

const orderItems = await ls.getOrderItems({ order: 123 })

getOrderItem(parameters)

Get an order item.

Returns an Order item object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
include string - - Comma-separated list of object names:
  • order
  • product
  • variant

Example

const orderItem = await ls.getOrderItem({ id: 123 })

getSubscriptions(parameters)

Get a list of subscriptions.

Returns a list of Subscription objects.

API reference.

Parameters

Parameter Type Required Default Notes
storeId number - - Filter subscriptions by store.
orderId number - - Filter subscriptions by order.
orderItemId number - - Filter subscriptions by order item.
productId number - - Filter subscriptions by product.
variantId number - - Filter subscriptions by variant.
status string - - Filter subscriptions by status. Options:
  • on_trial
  • active
  • paused
  • past_due
  • unpaid
  • cancelled
  • `expired
perPage number - 10
page number - 1
include string - - Comma-separated list of object names:
  • store
  • customer
  • order
  • order-item
  • product
  • variant

Example

const subscriptions = await ls.getSubscriptions()

const subscriptions = await ls.getSubscriptions({ storeId: 123, status: 'past_due' })

getSubscription(parameters)

Get a subscription.

Returns a Subscription object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
include string - - Comma-separated list of object names:
  • store
  • customer
  • order
  • order-item
  • product
  • variant

Example

const subscription = await ls.getSubscription({ id: 123 })

updateSubscription(parameters)

Update a subscription: change plan or billing anchor.

Returns a Subscription object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
productId number If changing plans - ID of product when changing plans.
variantId number If changing plans - ID of variant when changing plans.
proration string - - Set the proration when changing plans.
  • Use immediate to charge a prorated amount immediately
  • Use disable to charge a full amount immediately
  • If proration is not included, proration will occur at the next renewal date
billingAnchor number - - Change the billing day used for renewal charges. Must be a number between 1 and 31.

Example

const subscription = await ls.updateSubscription({ id: 123, productId: 123, variantId: 123 })

cancelSubscription(parameters)

Cancel a subscription.

Returns a Subscription object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -

Example

const subscription = await ls.cancelSubscription({ id: 123 })

resumeSubscription(parameters)

Resume a cancelled subscription.

Returns a Subscription object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -

Example

const subscription = await ls.resumeSubscription({ id: 123 })

pauseSubscription(parameters)

Pause a subscription (halt payment renewals).

Returns a Subscription object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
mode string - void Type of pause:
  • void - your product or service is unavailable to customers
  • free - the user should get free access
resumesAt string - - Date to automatically resume the subscription (ISO 8601 format datetime).

Example

const subscription = await ls.pauseSubscription({ id: 123 })

unpauseSubscription(parameters)

Un-pause a paused subscription.

Returns a Subscription object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -

Example

const subscription = await ls.unpauseSubscription({ id: 123 })

getSubscriptionInvoices(parameters)

Get a list of subscription invoices.

Returns a list of Subscription invoice objects.

API reference.

Parameters

Parameter Type Required Default Notes
storeId number - - Filter subscription invoices by store.
status string - - Filter subscription invoices by status. Options:
  • paid
  • pending
  • void
  • refunded
refunded boolean - - Filter subscription invoices by refunded.
subscriptionId number - - Filter subscription invoices by subscription.
perPage number - 10
page number - 1
include string - - Comma-separated list of object names:
  • store
  • subscription

Example

const subscriptionInvoices = await ls.getSubscriptionInvoices()

const subscriptionInvoices = await ls.getSubscriptionInvoices({ storeId: 123, refunded: true })

getSubscriptionInvoice(parameters)

Get a subscription invoice.

Returns a Subscription invoice object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
include string - - Comma-separated list of object names:
  • store
  • subscription

Example

const subscriptionInvoice = await ls.getSubscriptionInvoice({ id: 123 })

getDiscounts(parameters)

Get a list of discounts.

Returns a list of Discount objects.

API reference.

Parameters

Parameter Type Required Default Notes
storeId number - - Filter discounts by store.
perPage number - 10
page number - 1
include string - - Comma-separated list of object names:
  • store
  • variants
  • discount-redemptions

Example

const discounts = await ls.getDiscounts()

const discounts = await ls.getDiscounts({ storeId: 123, include: 'discount-redemptions' })

getDiscount(parameters)

Get a discount.

Returns a Discount object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
include string - - Comma-separated list of object names:
  • store
  • variants
  • discount-redemptions

Example

const discount = await ls.getDiscount({ id: 123 })

createDiscount(parameters)

Create a discount.

Returns a Discount object.

API reference.

Parameters

Parameter Type Required Default Notes
storeId number Yes -
name string Yes - The reference name of the discount.
code string Yes - The discount code. Can contain uppercase letters and numbers, between 3 and 256 characters.
amount string Yes - Either a fixed amount in cents or a percentage:
  • 1000 means $10 when amount_type is fixed
  • 10 means 10% when amount_type is percent
amountType string - percent The type of discount. Options:
  • percent
  • fixed
duration string - once How many times the discount should apply (for subscriptions only). Options:
  • once - only the first payment.
  • repeating - applies for months defined in durationInMonths.
  • forever - applies to every subscription .payment
durationInMonths number - - How many months the discount should apply when duration is repeating.
variantIds number[] - - Limit discount to certain variants.
List of variant IDs like [1,2,3].
maxRedemptions number - - Limit the total amount of redemptions allowed.
startsAt string - - Date the discount code starts on (ISO 8601 format datetime).
expiresAt string - - Date the discount code expires on (ISO 8601 format datetime).

Example

const options = {
  storeId: 123,
  name: 'Summer sale',
  code: 'SUMMERSALE',
  amount: 30,
  amountType: 'percent',
  duration: 'repeating',
  durationInMonths: 3,
  startsAt: '2023-07-31T08:00:00.000000Z'
}
const discount = await ls.createDiscount(options)

deleteDiscount(parameters)

Delete a discount.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -

Example

await ls.deleteDiscount({ id: 123 })

getDiscountRedemptions(parameters)

Get a list of discount redemptions.

Returns a list of Discount redemption objects.

API reference.

Parameters

Parameter Type Required Default Notes
discountId number - - Filter discount redemptions by discount.
orderId number - - Filter discount redemptions by order.
perPage number - 10
page number - 1
include string - - Comma-separated list of object names:
  • discount
  • order

Example

const discountRedemptions = await ls.getDiscountRedemptions()

const discountRedemptions = await ls.getDiscountRedemptions({ orderId: 123, include: 'discount,order' })

getDiscountRedemption(parameters)

Get a discount redemption.

Returns a Discount redemption object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
include string - - Comma-separated list of object names:
  • discount
  • order

Example

const discountRedemption = await ls.getDiscountRedemption({ id: 123 })

getLicenseKeys(parameters)

Get a list of license keys.

Returns a list of License key objects.

API reference.

Parameters

Parameter Type Required Default Notes
storeId number - - Filter license keys by store.
orderId number - - Filter license keys by order.
orderItemId number - - Filter license keys by order item.
productId number - - Filter license keys by product.
perPage number - 10
page number - 1
include string - - Comma-separated list of object names:
  • store
  • customer
  • order
  • order-item
  • product
  • license-key-instances

Example

const licenseKeys = await ls.getLicenseKeys()

const licenseKeys = await ls.getLicenseKeys({ storeId: 123 })

getLicenseKey(parameters)

Get a license key.

Returns a License key object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
include string - - Comma-separated list of object names:
  • store
  • customer
  • order
  • order-item
  • product
  • license-key-instances

Example

const licenseKey = await ls.getLicenseKey({ id: 123 })

getLicenseKeyInstances(parameters)

Get a list of license key instances.

Returns a list of License key instance objects.

API reference.

Parameters

Parameter Type Required Default Notes
licenseKeyId number - - Filter license key instances by license key.
perPage number - 10
page number - 1
include string - - Comma-separated list of object names:
  • store
  • customer
  • order
  • order-item
  • product
  • license-key-instances

Example

const licenseKeys = await ls.getLicenseKeys()

const licenseKeys = await ls.getLicenseKeys({ licenseKeyId: 123 })

getLicenseKeyInstance(parameters)

Get a license key instance.

Returns a License key instance object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
include string - - Comma-separated list of object names:
  • store
  • customer
  • order
  • order-item
  • product
  • license-key-instances

Example

const licenseKey = await ls.getLicenseKey({ id: 123 })

getWebhooks(parameters)

Get a list of webhooks.

Returns a list of Webhook objects.

API reference.

Parameters

Parameter Type Required Default Notes
storeId number - - Filter webhooks by store.
perPage number - 10
page number - 1
include string - - Comma-separated list of object names:
  • store

Example

const webhooks = await ls.getWebhooks()

const webhooks = await ls.getWebhooks({ storeId: 123 })

getWebhook(parameters)

Get a webhook.

Returns a Webhook object.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -
include string - - Comma-separated list of object names:
  • store

Example

const webhook = await ls.getWebhook({ id: 123 })

createWebhook(parameters)

Create a webhook.

Returns a Webhook object.

API reference.

Parameters

Parameter Type Required Default Notes
storeId number Yes -
url string Yes - The endpoint URL that the webhooks should be sent to.
events string[] Yes - A list of webhook events to receive. See all options
secret string Yes - A signing secret used to secure the webhook. Must be between 6 and 40 characters.

Example

const options = {
  storeId: 123,
  url: 'https://myapp.com/webhook/',
  events: [
    'subscription_created',
    'subscription_updated'
  ],
  secret: 'randomstring'
}
const webhook = await ls.createWebhook(options)

updateWebhook(parameters)

Update a webhook.

Returns a Webhook object.

API reference.

Parameters

Parameter Type Required Default Notes
id number - -
url string - - The endpoint URL that the webhooks should be sent to.
events string[] - - A list of webhook events to receive. See all options
secret string - - A signing secret used to secure the webhook. Must be between 6 and 40 characters.

Example

const options = {
  id: 123,
  url: 'https://myapp.com/webhook/',
}
const webhook = await ls.updateWebhook(options)

deleteWebhook(parameters)

Delete a webhook.

API reference.

Parameters

Parameter Type Required Default Notes
id number Yes -

Example

await ls.deleteWebhook({ id: 123 })

About

Official JavaScript SDK for Lemon Squeezy.

docs.lemonsqueezy.com/api

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

No packages published

Languages

  • JavaScript 100.0%