Re: [w3c/payment-request] Support for gift cards and discount codes (#145)

Weirdly, I thought I had already put together a proposal for this, but can't find it on Github.

Here is another one.

## Proposal
Note: I wrote the following in such a way that we can just spin off a separate "Payment Request API: Coupons" spec. That way, this doesn't need to block on the main Payment Request API spec. It also makes it easier to shop around.  

## Additions to `PaymentOptions` dictionary

```JS
partial dictionary PaymentOptions {
 boolean requestCoupon;
}
```

### `requestCoupon` member
Indicates that the merchant allows a coupon to be applied during request for payment.

## Additions to `PaymentDetailsUpdate` dictionary

```JS
partial dictionary PaymentDetailsUpdate {
  DOMString couponCode;
  boolean couponAccepted;
  CouponErrors couponErrors;
}
```

### `couponCode` member
Serves as a placeholder coupon, which gets pre-populated in the payment sheet.

For example:
```JS
// fill it in, but don't apply it
request.show({ couponCode: "SPRING-SALE" });

// Show it, and apply it!
request.show({
  couponCode: "SPRING-SALE",
  couponAccepted: true,
});
```

### `couponAccepted` member
Tells the browser to stop allowing the user to change the coupon code, and signal to the user that the code was accepted.

For example:

```JS
ev.updateWith({
   couponCode: "SPRING-SALE",
   couponAccepted: true,
});
```

### `couponErrors` member
Allows the merchant to signal errors related to the coupon code.

For example:
```JS
ev.updateWith({
   couponErrors: { code: "Code already used." },
});
```

## `CouponErrors` dictionary

```JS
dictionary CouponErrors {
  DOMString code;
}
```

### `code` member
The error corresponding to this particular code. See `couponErrors` member for example. 

## Additions to `PaymentRequest` interface

```JS
partial interface PaymentRequest {
  attribute EventHandler oncouponchange;
  readonly attribute DOMString? couponCode;
}
```

### `oncouponchange` attribute
Fires when the user changes the coupon.

### `couponCode` attribute
Allows merchants to access the updated coupon code during the request for payment.

### Additions to `PaymentResponse` interface

```JS
partial interface PaymentResponse {
  readonly attribute DOMString? couponCode;
}
```

### `couponCode` attribute
Allows merchants to access the updated coupon code in the response.


## Example of usage 

```JS
async function doPaymentRequest() {
  const options = { requestCoupon: true };
  const request = new PaymentRequest(methods, details, options);
  request.oncouponchange = ev => {
    const promise = applySweetSweetSavings(request, details, ev);
    ev.updateWith(promise);
  };
  const response = await request.show();
  //...
  await response.complete("success");
  // post it somewhere, including the `couponCode` applied
  fetch("/invoices", {
    method: "POST",
    body: JSON.stringify(response.toJSON()),
  });
}

async function applySweetSweetSavings({ couponCode }, { displayItems }) {
  const couponErrors = await validateCouponCode(couponCode);
  if (couponErrors) {
    return { couponErrors };
  }
  // It's good, update total, add display item, whatever...
  const { newTotal, additionalDisplayItem } = applySweetSavings(couponCode);
  return {
    couponAccepted: true,
    total: newTotal,
    displayItems: [...displayItems, additionalDisplayItem].flatten(),
  };
}
```

Thoughts? 


-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/payment-request/issues/145#issuecomment-386505992