@checkoutpage/sdk 0.1.31 → 0.1.33

package/README.md

@@ -127,6 +127,40 @@ const results = await checkoutpage.coupons.create({
 });
 ```
 
+Without `rules` a coupon discounts the whole order on every checkout page and event. `rules`
+limits it, one rule per checkout page or event, combined with OR:
+
+- Checkout pages: `wholeOrder`, `prices` (only when the customer buys one of `priceIds`, and
+  only that price is discounted) or `pricesAndBumps` (only when the customer buys one of
+  `priceIds` **and** one of `bumpProductIds`, and both are discounted).
+- Events: `wholeOrder`, `tickets` or `ticketsAndAddOns`, the same with `ticketTypeIds` and
+  add-ons.
+- An empty or missing `priceIds`, `ticketTypeIds` or `bumpProductIds` means all of them,
+  including ones added later. `priceIds` are the `id`s of the page's main product `prices`, not
+  Stripe price ids.
+
+```typescript
+const results = await checkoutpage.coupons.create({
+  type: 'percent',
+  label: 'Monthly plus workbook',
+  code: 'BUNDLE20',
+  percentOff: 20,
+  duration: 'once',
+  rules: [
+    {
+      pageId,
+      appliesTo: 'pricesAndBumps',
+      priceIds: [monthlyPriceId],
+      bumpProductIds: [workbookProductId],
+    },
+    { pageId: eventId, appliesTo: 'tickets', ticketTypeIds: [vipTicketTypeId] },
+  ],
+});
+```
+
+`pageIds` and `ticketTypeIds` are deprecated in favour of `rules`. They still work, but only
+without `rules`, and responses derive them from the rules.
+
 ### Subscriptions
 
 #### List subscriptions
@@ -241,6 +275,67 @@ const pageBookings = await checkoutpage.bookings.list({
 });
 ```
 
+#### Create a booking
+
+`bookings.create` issues a real booking without collecting card payment: tickets
+are issued, the customer gets a confirmation email with the ticket PDF, and
+booking webhooks fire. Field values are addressed by `fieldId`, and every field
+the event marks as required must be supplied.
+
+```typescript
+const { data: booking } = await checkoutpage.bookings.create({
+  eventId: '67fcbdac6a91c25ef2d3534a',
+  tickets: { '65f4a1c2e4a9f3d2b1c0a9e8': 2 },
+  fields: [
+    { fieldId: '507f1f77bcf86cd799439030', value: 'ada@example.com' },
+    { fieldId: '507f1f77bcf86cd799439031', value: 'Ada Lovelace' },
+  ],
+  paymentOption: { manualType: 'invoice' },
+});
+
+console.log(booking.status); // 'unpaid'
+console.log(booking.amountDue); // 5000, settled outside checkout
+```
+
+#### Create a complimentary booking
+
+There are two ways to settle a booking, and exactly one of them is required.
+Pass `paymentOption`, as above, and the booking is recorded as `unpaid` with the
+amount as its balance due, settled outside checkout. Pass `complimentary: true`
+instead and the tickets are issued at no charge: the booking is recorded as
+`paid` with `amount`, `amountPaid` and `amountDue` of 0 and
+`isComplimentary: true`, while the ticket lines keep their face value and
+`complimentaryDiscountAmount` records what they would have cost. `complimentary`
+cannot be combined with `paymentOption` or `couponId`.
+
+```typescript
+const { data: booking } = await checkoutpage.bookings.create({
+  eventId: '67fcbdac6a91c25ef2d3534a',
+  tickets: { '65f4a1c2e4a9f3d2b1c0a9e8': 2 },
+  fields: [
+    { fieldId: '507f1f77bcf86cd799439030', value: 'ada@example.com' },
+    { fieldId: '507f1f77bcf86cd799439031', value: 'Ada Lovelace' },
+  ],
+  complimentary: true,
+});
+
+console.log(booking.status); // 'paid'
+console.log(booking.amount); // 0
+console.log(booking.complimentaryDiscountAmount); // 5000 (2 x 2500 face value)
+```
+
+#### Filter complimentary bookings
+
+```typescript
+const complimentary = await checkoutpage.bookings.list({
+  isComplimentary: 'true',
+});
+
+const paidFor = await checkoutpage.bookings.list({
+  isComplimentary: 'false',
+});
+```
+
 ### Products
 
 #### Get a product
@@ -249,6 +344,15 @@ const pageBookings = await checkoutpage.bookings.list({
 const product = await checkoutpage.products.get('product_id');
 ```
 
+#### List products
+
+```typescript
+const products = await checkoutpage.products.list({
+  search: 'shirt',
+  limit: 20,
+});
+```
+
 #### Update a product
 
 ```typescript
@@ -299,6 +403,64 @@ await checkoutpage.checkoutPages.create({
 > report them by mirroring the product — but new integrations should set them
 > under `productData` or via `products.update()`.
 
+### Order bumps
+
+An order bump is an extra product offered on a checkout page or event (shown as
+an add-on on an event). Create the order bump product once, then offer it on as
+many pages as you like.
+
+#### Create an order bump product
+
+Order bump products use a single one-time price, which can have a setup fee or be
+pay what you want. Recurring prices and payment plans are refused with a
+`ValidationError`.
+
+```typescript
+const { data: bump } = await checkoutpage.products.create({
+  role: 'orderbump',
+  title: 'Gift wrapping',
+  price: { amount: 500, currency: 'usd' },
+  callToActionText: 'Yes! Add gift wrapping',
+  shortDescription: 'Wrapped in recycled paper with a handwritten note.',
+});
+
+const bumps = await checkoutpage.products.list({ role: 'orderbump' });
+```
+
+#### Offer it on a page
+
+The same methods are on `checkoutpage.events.orderBumps` for events.
+
+```typescript
+await checkoutpage.checkoutPages.orderBumps.create('page_id', {
+  productId: bump.id,
+  preselected: true,
+});
+
+const { data: placed } = await checkoutpage.checkoutPages.orderBumps.list('page_id');
+
+await checkoutpage.checkoutPages.orderBumps.update('page_id', bump.id, {
+  allowQuantity: true,
+});
+
+// List every order bump on the page, once, in the new order
+await checkoutpage.checkoutPages.orderBumps.reorder('page_id', {
+  productIds: ['other_bump_id', bump.id],
+});
+
+// Stops offering it on this page; the product is kept
+await checkoutpage.checkoutPages.orderBumps.delete('page_id', bump.id);
+```
+
+#### Delete an order bump product
+
+Only order bump products that have never been bought can be deleted. A product
+still offered on a page is refused unless you pass `fromAllPages: true`.
+
+```typescript
+await checkoutpage.products.delete(bump.id, { fromAllPages: true });
+```
+
 ### Files
 
 #### Upload an image
@@ -327,6 +489,115 @@ const result = await checkoutpage.files.upload({
 console.log('File uploaded:', result.data.id);
 ```
 
+### Themes
+
+A theme is a page design you can reuse across checkout pages, events and forms. `list()` returns
+your own themes (`scope: 'seller'`) and the built-in ones (`scope: 'global'`), which are read-only.
+
+#### List themes
+
+```typescript
+const { data: themes, has_more } = await checkoutpage.themes.list();
+
+const builtIn = await checkoutpage.themes.list({ scope: 'global' });
+```
+
+#### Create a theme
+
+```typescript
+const { data: theme } = await checkoutpage.themes.create({
+  name: 'Brand',
+  // Optional: start from a copy of a built-in theme or one of yours
+  baseThemeId: builtIn.data[0].id,
+  variables: { tokens: { colorPrimary: { light: '#4f46e5' } } },
+});
+```
+
+`variables` takes the same shape as a page's `themeOverrides`. A copy of a built-in theme does not
+follow your store's brand colour, so set `tokens.colorPrimary` if you want it. A name another of
+your themes already uses is rejected with a `ConflictError`.
+
+#### Get and update a theme
+
+```typescript
+const { data: theme } = await checkoutpage.themes.get(themeId);
+
+const { data: updated } = await checkoutpage.themes.update(themeId, {
+  name: 'Brand v2',
+  variables: { tokens: { colorPrimary: { light: '#0f766e' }, radius: null } },
+});
+```
+
+Every page that uses the theme changes too. Keys you leave out keep their value, and `null` resets a
+property, or everything under a key. Built-in themes can't be changed: copy one with `baseThemeId`.
+
+#### Use a theme on a page
+
+```typescript
+await checkoutpage.checkoutPages.update(pageId, { themeId: theme.id });
+```
+
+`events` and `forms` take `themeId` on `create` and `update` too, and page responses include it.
+Changing a page's theme replaces the page's own theme settings, including ones set in the
+dashboard such as custom CSS, so the page looks like the theme. `themeOverrides` sent in the same
+request apply on top, and the page's locale is kept.
+
+#### Delete a theme
+
+```typescript
+const { data: deleted } = await checkoutpage.themes.delete(themeId);
+```
+
+A theme that any of your pages uses, archived ones included, or that is your store's default theme,
+can't be deleted and throws a `ConflictError`. Move those pages to another theme with `themeId`
+first.
+
+### Form layout
+
+`formLayout` arranges a page's form, top to bottom: fields, headings, dividers, the discount code
+box and groups that put up to 4 items side by side. Checkout pages, events and forms take it on
+`create` and `update`, and page responses always include it. On `create`, reference a field by
+`fieldKey`, the `key` you gave it in `fields` in the same request.
+
+```typescript
+import type { CreateFormLayout } from '@checkoutpage/sdk';
+
+const formLayout: CreateFormLayout = [
+  { type: 'heading', id: 'your-details', text: 'Your details', level: 'heading' },
+  {
+    type: 'group',
+    id: 'name-row',
+    columns: 2,
+    items: [
+      { type: 'field', fieldKey: 'first-name' },
+      { type: 'field', fieldKey: 'last-name' },
+    ],
+  },
+  { type: 'divider', id: 'divider-1' },
+  { type: 'discount-code' },
+];
+
+const { data: page } = await checkoutpage.checkoutPages.create({
+  name: 'Workshop',
+  productData: { title: 'Workshop', price: { amount: 4900, currency: 'usd' } },
+  fields: [
+    { label: 'Email', element: 'email', type: 'email', required: true },
+    { key: 'first-name', element: 'text', label: 'First name' },
+    { key: 'last-name', element: 'text', label: 'Last name' },
+  ],
+  showCouponCodeField: true,
+  formLayout,
+});
+```
+
+Responses and `update` reference fields by `fieldId` (the `FormLayout` type). `update` replaces the
+whole layout, so read `page.formLayout`, change it and send it back. Fields the layout leaves out
+are added after it. A `fieldKey` that matches no field, a field id that is not on the page, or a
+`discount-code` item on a form, throws a `ValidationError`. The `discount-code` item only places
+the box: `showCouponCodeField` switches it on, and a saved placement is returned while the box is
+off too. More item types may be added later: skip any type you do not recognise when reading, and
+send it back as you received it when updating.
+
 ### Webhooks
 
 #### List webhook endpoints
@@ -362,8 +633,36 @@ saveSecret(webhook.secret);
 > and a URL already registered on the account is rejected with a `ConflictError`.
 
 > The create response is the **only** place the signing `secret` is ever returned.
-> It is not included in `list()` responses and cannot be retrieved later — store it
-> when you create the endpoint. Omit `secret` to have one generated for you.
+> It is not included in `list()` or `get()` responses and cannot be retrieved later, so store
+> it when you create the endpoint. Omit `secret` to have one generated for you.
+
+#### Get a webhook endpoint
+
+```typescript
+const { data: webhook } = await checkoutpage.webhooks.get(webhookId);
+
+console.log(webhook.status, webhook.deliveryCount, webhook.lastFailureAt);
+```
+
+The signing `secret` is not included.
+
+#### Update a webhook endpoint
+
+```typescript
+const { data: updated } = await checkoutpage.webhooks.update(webhookId, {
+  url: 'https://example.com/hooks/checkoutpage-v2',
+  events: ['payment.paid', 'checkout_page.updated', 'product.updated'],
+});
+
+// Pause deliveries without deleting the endpoint, then resume them
+await checkoutpage.webhooks.update(webhookId, { status: 'inactive' });
+await checkoutpage.webhooks.update(webhookId, { status: 'active' });
+```
+
+Only the fields you send change. `events` and `customHeaders` replace the existing values rather
+than merging with them. A new `url` must use https and must not already be registered on another of
+your webhooks (`ValidationError` / `ConflictError`). The signing secret cannot be changed through
+the API.
 
 #### Delete a webhook endpoint
 
@@ -373,6 +672,39 @@ const { data: deleted } = await checkoutpage.webhooks.delete(webhook.id);
 
 Deliveries stop immediately and the endpoint no longer appears in `list()`.
 
+### Test mode
+
+Switch a checkout page, event or form into test mode with `testmode: true`. While it is on, every
+purchase on that page is a test purchase: no money is taken, the buyer gets the product for free,
+and the records are created with `livemode: false`.
+
+```typescript
+await checkoutpage.checkoutPages.update(pageId, { testmode: true });
+
+const { data: pagesInTestMode } = await checkoutpage.checkoutPages.list({ testmode: true });
+
+// Turn it off to take real payments again
+await checkoutpage.checkoutPages.update(pageId, { testmode: false });
+```
+
+`events` and `forms` take the same field on `create`, `update` and `list`. Page responses carry
+`testmode` and `testmodeEnabledAt` (when test mode was switched on, `null` while it is off).
+
+#### Read test records
+
+Pass `livemode: false` to read test records from payments, bookings, subscriptions, subscription
+payments, invoices, submissions and tickets:
+
+```typescript
+const { data: testPayments } = await checkoutpage.payments.list({ pageId, livemode: false });
+const { data: testPayment } = await checkoutpage.payments.get(paymentId, { livemode: false });
+const pdf = await checkoutpage.bookings.downloadTicketPdf(bookingId, { livemode: false });
+```
+
+Without `livemode`, reads return records in the mode of your API key. A live key (`sk_live_`)
+reads live data by default and test data with `livemode: false`. A test key (`sk_test_`) only
+reads test data: `livemode: true` with a test key throws an `AuthenticationError` (403).
+
 ## Error Handling
 
 The SDK provides typed error classes for different error scenarios: