RedeemPoints1

Creates a coupon code to redeem the customer's loyalty points.

Kind	Write API call
Method	POST
URL	https://app.bubblehouse.com/api/v2023061/<shop>/RedeemPoints1
Authentication	Customer TokenPartner Token for CustomerShop TokenPartner Token for Shop

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.

• pts integer required

  The number of points to redeem.

• no_coupon boolean optional

  When true, deducts points but does not generate a coupon code.

  Use this when the caller has already created and applied their own internal coupon or discount in their system. The points will be deducted from the customer's balance, but no Shopify coupon code will be created or returned.

  This is primarily used by partner integrations that manage their own coupon systems and only need Bubblehouse to track the point redemption.

• cart_subtotal monetary optional

  The current cart subtotal amount.

  Provide this value when the redemption is happening in the context of a purchase (e.g., checkout, POS) to enable minimum order value validation. If the shop has configured a minimum order value for point redemptions, this value will be checked against that threshold.

  This parameter is optional and can be omitted for non-purchase contexts (e.g., converting points to gift cards, subscription discounts).

Output

• code string required

  The coupon code that was created for this redemption.

  When no_coupon is true, this will be an empty string since no coupon code is generated.

• pts integer required

  The number of points that were redeemed.

• amount monetary required

  The monetary value of the points that were redeemed.

• change_bhid bubbleflake required

  The ID of the point balance change record created by this redemption.

  This ID can be used later to reference this redemption, or to undo it via Unredeem1 when that call is allowed (unused pending coupons for customer and partner-customer tokens; external no_coupon redemptions only for shop, customer-admin, and partner-shop tokens). It will be a valid Bubblehouse ID when points are successfully redeemed, or zero when no change was made (though this should not normally happen for successful redemptions).

• remove_coupon_codes array of strings optional

  List of coupon codes that should be removed from the customer's cart.

  This is used in provisional redemption scenarios where previously applied codes need to be replaced.

Specific Errors

Status	Error	Reason & Examples
422	insufficient_points	Attempting to redeem more points than the customer has.
422	points_below_redeemable_minimum	Attempting to redeem fewer points than the minimum threshold set up in the admin portal.
422	points_disabled	You have not enabled points in the admin portal.
422	points_spending_disabled	You have not enabled spending of points in the admin portal (although points are enabled in general).
422	customer_read_only	This customer’s loyalty program is read-only. They cannot perform this action themselves. Shop and customer-admin tokens still can.
422	minimum_order_value_not_met	The cart subtotal is below the minimum order value required for point redemption.

API-wide Errors

Status	Error	Reason & Examples
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.
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.
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.
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	no_customers_match_customer_identity	The customer identity ('customer' input parameter) does not match a known customer.

Global Errors

Status	Error	Reason & Examples
400	invalid_global_api_version	The global API version you are trying to use has never existed.
400	obsolete_global_api_version	The global API version you are trying to use is no longer supported.
400	inaccessible_global_api_version	The global API version you are trying to use is not enabled on your account.
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.
401	invalid_token	The provided authentication token is invalid or has expired.