Document error states for applyDiscountCodeChange

[edhgoose]

Please list the related package(s)

If this related to specific APIs or components, please list them here

Is your feature request related to a problem? Please describe.

According to the error state documentation for applyDiscountCodeChange, the error message is:

A message that explains the error. This message is useful for debugging. It is not localized, and therefore should not be presented directly to the buyer.

Given the message shouldn't be displayed to the buyer, we want to show a relevant, actionable, useful message to the buyer. For instance, I would assume (but do not know) that an error could be that the discount requires certain criteria to be fulfilled.

It's unclear what the possible error states could be, and therefore it's difficult to determine what localised messaging we should provide to the user.

Furthermore, the docs says:

This method will return an error if the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.

Which is unclear because it's not clear if that's something we can detect beforehand (so we don't even try to apply a discount) or whether we should show a message. Further documentation on what the behaviour should be in this case, and how we can action it appropriately would be greatly appreciated.

We intend, in the meantime, to capture the message and record it via something like Sentry, but this requires us to monitor errors we will see and then build localised messaging off those errors.

It would be great to document the messages or types of failures that could be possible so we can provide actionable messaging and build logic to prevent a bad experience.

Describe the changes you are looking for

Clear documentation of the types of errors that are possible, and guidance on what localised messaging should be shown to users.

For instance, a table showing something like:

• Code inactive -> Show a message showing their code isn't available
• Minimum spend -> Show a message requiring the user to spend more.

etc etc.

Describe alternatives you’ve considered

Guess work and trying out a few things to see what happened.

e.g. we got one message:

Reduction code couldn't be mapped to neither a gift card or discount.

This turned out to be because the discounts weren't setup correctly. This one we'd assume we'd want to capture, alert our shopify admins, and provide a message saying either to contact support or try again later.

Additional context

[edhgoose]

Documenting for reference the ones I've found so far:

• Reduction code couldn't be mapped to neither a gift card or discount. (This one I think means the code doesn't exist in Shopify)
• CODE couldn't be used with your existing discounts. (I'm guessing this one means that if you've already got a discount, then you can't add this one too)
• CODE discount code isn’t available to you right now. (No idea what this one means).

[edhgoose]

Also:

• Could not add discount code (No idea why this one occurs).

[edhgoose]

• CODE discount code is not valid for items in your cart. (This one makes sense!)

[edhgoose]

• CODE discount code has already been used. (Makes sense too).

[edhgoose]

Found another one:

• Discount code not valid on orders containing gift cards. (Guess that one makes sense as well).

[edhgoose]

Ah. And another one which looks like a failure mode:

• Server failed to fulfill the request and to identify the exact issue.

[edhgoose]

Here's a new one:

• Error: Negotiation was stale.

Dunno what that means.

[edhgoose]

And another:

• Discount codes are not valid during our Black Friday sale

Not sure how that one works - I guess that must be set somewhere within the store? Curious.

[edhgoose]

As requested in #2521, I have re-raised this issue as: https://community.shopify.dev/t/feature-request-document-error-states-for-applydiscountcodechange/6406