@checkoutpage/sdk 0.1.32 → 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
@@ -369,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
@@ -460,6 +552,52 @@ A theme that any of your pages uses, archived ones included, or that is your sto
 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