Loyalty API

Write Call

Unredeem1

Undo a redemption and return its points to the customer (refund points), or cancel an unused provisional coupon. Works only while the redemption is pending.

For provisional checkout coupons, no points were deducted when the coupon was created. Cancelling an eligible provisional redemption succeeds without returning points or recording a point refund. Coupon deactivation is scheduled in the background; success does not mean the external provider has finished deactivating the code.

Other eligible redemptions return the points that were deducted. Consumed, expired, or already cancelled provisional redemptions cannot be unredeemed.

An in-store redemption that has already been sent to a point of sale cannot be unredeemed, because Bubblehouse cannot withdraw that discount. It stays pending until the completed sale uses it.

Kind Write API call
Method POST
URL https://app.bubblehouse.com/api/v2023061/<shop>/Unredeem1
Authentication Customer TokenPartner Token for CustomerShop TokenPartner Token for Shop
You have a choice of making this call from your server using a shop token and specifying a customer ID, or making this call from a web browser/app using a customer token you have generated on the server.

Input

  • customer CustomerIdentity1 required if using a shop token

    A customer to operate upon, when using a shop token.

    If you're using a customer token and decide to pass this field (which we do not recommend), it must match the customer from the token.

  • change_bhid bubbleflake required

    The ID of the point balance change to reverse.

    This should be a change ID that was previously returned in the change_bhid field by RedeemPoints1 or RedeemOffer1, or listed in AvailableReward1.

  • force boolean optional

    Allow forced reversal where supported.

    Defaults to false. Requires a shop, customer-admin, or partner-shop token.

Output

  • success boolean required

    Indicates whether the redemption was successfully reversed or the provisional coupon was cancelled.

  • pts integer optional

    The number of points returned to the customer's balance. Omitted when zero, including successful provisional coupon cancellation.

Specific Errors

Status Error Reason & Examples
422 change_already_reverted

Returned when the change has already been reverted.

422 invalid_redemption_for_unredeem

Returned when the redemption cannot be unredeemed. Customer and partner-customer tokens can only unredeem unused pending coupon or in-store redemptions. Shop, customer-admin, and partner-shop tokens can also unredeem external (no_coupon) redemptions. Also returned for an in-store redemption already sent to a point of sale.

404 not_found

Returned when the specified change ID does not exist or does not belong to the customer.

API-wide Errors

Status Error Reason & Examples
404 no_customers_match_customer_identity

The customer identity ('customer' input parameter) does not match a known customer.

404 empty_customer_identity

All fields of the customer identity ('customer' input parameter) have been empty when using a shop token. You need to either specify a non-empty value for one of the customer identity fields, or use a customer token.

404 customer_identity_partially_mismatches_matched_customer

A customer has been matched by one of the fields of the customer identity ('customer' input parameter), but some non-empty fields do not match Bubblehouse data on that customer.

400 missing_customer_identity

The customer identity ('customer' input parameter) has not been specified when using a shop token. You need to either specify a non-empty value for one of the customer identity fields, or use a customer token.

403 customer_identity_does_not_match_token

API call is using a customer token, but the customer identity in API params does not match the customer from the token.

Global Errors

Status Error Reason & Examples
400 obsolete_global_api_version

The global API version you are trying to use is no longer supported.

429 rate_limit_exceeded

Your usage is over the rate limit. Ensure that you're not making duplicate calls, and contact our team for a rate limit increase.

For example: You are over the read limit per second for this customer

400 invalid_global_api_version

The global API version you are trying to use has never existed.

401 invalid_token

The provided authentication token is invalid or has expired.

For example: The token has expired

400 inaccessible_global_api_version

The global API version you are trying to use is not enabled on your account.

Previous
Status2