README.md — sigil-lemonsqueezy

1# sigil-lemonsqueezy

3Lemon Squeezy API client library for Sigil. Provides functions for managing

4products, checkouts, orders, subscriptions, webhooks, and license keys via

5the [Lemon Squeezy API](https://docs.lemonsqueezy.com/api).

7## Features

9- **JSON:API parsing** — Helpers for extracting data, attributes,

10 relationships, and included resources from JSON:API responses

11- **Products & Variants** — List and retrieve products and their variants

12- **Checkouts** — Create checkout URLs with custom data, product options,

13 and pricing overrides

14- **Orders & Order Items** — List and retrieve orders and line items

15- **Subscriptions** — List, retrieve, update, and cancel subscriptions

16- **Webhooks** — CRUD operations plus HMAC-SHA256 signature verification

17- **License Keys** — Manage keys via the main API; validate, activate, and

18 deactivate via the unauthenticated License API

19- **Pagination** — Built-in support for page-based pagination and filtering

21## Modules

23| Module | Description |

24|--------|-------------|

25| `(lemonsqueezy)` | Core client, auth, JSON:API helpers, pagination |

26| `(lemonsqueezy product)` | Products and variants |

27| `(lemonsqueezy checkout)` | Checkout creation and retrieval |

28| `(lemonsqueezy order)` | Orders, order items, subscriptions |

29| `(lemonsqueezy webhook)` | Webhook CRUD and signature verification |

30| `(lemonsqueezy license)` | License key management and validation |

32## Quick Start

34```scheme

35(import (lemonsqueezy)

36 (lemonsqueezy product)

37 (lemonsqueezy order)

38 (lemonsqueezy checkout))

40;; Create a client with your API key

41(define client (ls-client api-key: "your-api-key"))

43;; List products

44(define products (ls-products client))

45(for-each (lambda (p)

46 (display (ls-product-name p))

47 (display " - ")

48 (display (ls-product-price-formatted p))

49 (newline))

50 products)

52;; Get a single product

53(define product (ls-product-get client "123"))

55;; Create a checkout with custom data

56(define checkout

57 (ls-create-checkout client "1" "10"

58 #{ checkout-data: #{ email: "[email protected]"

59 custom: #{ user_id: "42" } } }))

60(display (ls-checkout-url checkout))

62;; List orders with filtering

63(define orders

64 (ls-orders client #{ filter: #{ store_id: "1" } }))

65```

67## Webhooks

69Verify incoming webhook signatures and parse event payloads:

71```scheme

72(import (lemonsqueezy)

73 (lemonsqueezy webhook))

75;; Verify the X-Signature header

76(if (ls-verify-webhook signing-secret raw-request-body x-signature-header)

77 (let ((event (parse-webhook-event raw-request-body)))

78 (let ((event-name (ls-webhook-event-name event))

79 (custom-data (ls-webhook-event-custom-data event)))

80 ;; Dispatch by event name

81 (cond

82 ((string=? event-name "order_created")

83 ;; Grant access using custom_data.user_id

84 (grant-access (dict-ref custom-data user_id:)))

85 ((string=? event-name "subscription_expired")

86 ;; Revoke access

87 (revoke-access (dict-ref custom-data user_id:))))))

88 (error "Invalid webhook signature"))

89```

91## License Keys

93The License API endpoints (validate, activate, deactivate) do not require

94an API key and are designed for use in client applications:

96```scheme

97(import (lemonsqueezy license))

99;; Validate a license key (no auth needed)

100(define result (ls-validate-license "38b1460a-5104-4067-a91d-77b872934d51"))

101(if (ls-license-validation-valid result)

102 (display "License is valid!")

103 (display "License is invalid"))

104

105;; Activate a license key

106(define activation

107 (ls-activate-license "38b1460a-5104-4067-a91d-77b872934d51" "mysite.com"))

108

109;; Deactivate

110(ls-deactivate-license "38b1460a-5104-4067-a91d-77b872934d51" "instance-uuid")

111```

112

113## JSON:API Helpers

114

115Lemon Squeezy uses JSON:API format. The core module provides helpers:

116

117```scheme

118;; Extract data from a response

119(jsonapi-data response) ; single resource

120(jsonapi-data-list response) ; list of resources

121(jsonapi-attr resource name:) ; get attribute

122(jsonapi-attrs resource) ; full attributes dict

123

124;; Relationships

125(jsonapi-relationship-id resource store:) ; single relationship ID

126(jsonapi-relationship-ids resource variants:) ; has-many relationship IDs

127

128;; Included resources

129(jsonapi-included response) ; all included

130(jsonapi-find-included response "variants" "10") ; find by type+id

131

132;; Pagination

133(jsonapi-pagination-meta response) ; => #{ current-page: 1 last-page: 3 ... }

134(ls-paginate (lambda (page) ...)) ; auto-paginate all pages

135```

136

137## Pagination and Filtering

138

139All list endpoints accept an options dict:

140

141```scheme

142;; Paginate

143(ls-products client #{ page: 2 per-page: 50 })

144

145;; Filter

146(ls-subscriptions client #{ filter: #{ status: "active" product_id: "1" } })

147

148;; Include related resources

149(ls-products client #{ include: "variants,store" })

150

151;; Auto-paginate all pages

152(ls-paginate

153 (lambda (page)

154 (ls-get/json client

155 (string-append

156 (ls-api-url client "v1" "products")

157 (build-query-string (ls-list-params #{ page: page per-page: 100 }))))))

158```

159

160## Building

161

162```bash

163sigil deps install

164sigil build

165sigil test

166```

167

168## Dependencies

169

170- sigil-stdlib (core, dict, string, struct, crypto)

171- sigil-http (HTTP client)

172- sigil-json (JSON parsing)

173

174## API Coverage

175

176| Resource | Operations |

177|----------|-----------|

178| Products | list, get |

179| Variants | list, get |

180| Checkouts | create, get, list |

181| Orders | list, get |

182| Order Items | list, get |

183| Subscriptions | list, get, update, cancel |

184| Webhooks | create, get, list, update, delete, verify |

185| License Keys | list, get, update (main API) |

186| License API | validate, activate, deactivate (no auth) |

187

188## License

189

190BSD-3-Clause