Loyalty API
Write CallRedeemPoints1
Spend a customer's points for a discount coupon code (cash out points), or apply them to a subscription. Deducts the points and returns the code and its amount.
| 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
-
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.
-
ptsinteger requiredThe number of points to redeem.
-
coupon_currencystring optionalThe currency in which to issue the coupon, such as CAD.
When provided, the redemption value and coupon minimum order amount are converted from the store's base currency using the configured exchange rates. Currency codes are case-insensitive.
When omitted, the store's base currency is used.
The coupon issuer must support the requested currency. Cross-currency overrides are not supported for direct subscription discounts or credits. Pre-issued base-currency coupon inventory is not used for a different currency.
This does not change the currency of cart_subtotal or the returned amount; both remain in the store's base currency. Ignored when no_coupon is true.
Example:
"CAD" -
no_couponboolean optionalWhen 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.
-
apply_to_subscriptionboolean optionalApply the redeemed points to the customer's subscription instead of issuing a checkout coupon.
When true, Bubblehouse sends the redemption to the store's subscription platform. When false or omitted, this call redeems points as a coupon or external redemption, and
subscription_idis ignored.With no
subscription_id, Bubblehouse chooses one active subscription. Most platforms use the subscription with the most completed cycles. A platform that schedules by upcoming order uses the closest upcoming order. -
subscription_idstring optionalPlatform subscription id to receive the points. Use the same id you send on UpdateSubscriptions1.
The subscription must already be active for this customer. A miss returns
subscription_not_foundand does not spend points. Bubblehouse does not choose a different subscription.Platforms that apply points to the customer rather than to one subscription, such as a credit balance, reject this field with
bad_data. Omit it to keep that customer-level behavior.Example:
"SUB-1001" -
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
-
codestring requiredThe coupon code that was created for this redemption.
When
no_couponis true, this will be an empty string since no coupon code is generated. -
ptsinteger requiredThe number of points that were redeemed.
-
The monetary value of the points that were redeemed.
-
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
Unredeem1when that call is allowed (unused pending coupons for customer and partner-customer tokens; externalno_couponredemptions only for shop, customer-admin, and partner-shop tokens).Cancelling an eligible provisional coupon deactivates it without returning points, because no points were deducted when it was created.
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_codesarray of strings optionalList 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 | loyalty_unavailable |
Points cannot be redeemed because the loyalty program is not available in this context: the market's loyalty program is turned off, or the buyer's country is not eligible for the store's loyalty program. |
| 422 | subscription_not_found |
No active subscription matched. When subscription_id is set, it did not match an active subscription for this customer. When it is omitted, the customer has no eligible subscription. Points are not spent. |
| 422 | subscription_discount_not_applied |
The subscription platform did not apply the points. The customer's balance is unchanged. |
| 400 | bad_data |
subscription_id was sent to a platform that applies points to the customer rather than to one subscription. |
| 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. |
| 422 | minimum_completed_purchases_not_met |
The customer has not completed the minimum number of purchases required to redeem points or offers. |
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: |
| 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: |
| 400 | inaccessible_global_api_version |
The global API version you are trying to use is not enabled on your account. |