Loyalty API
Read CallQueryOrderDetails1
Points earned by one placed order: per-line breakdown, the rewards and achievements it unlocked, and the calculation trace. Tells why an order earned that many points, or none.
| Kind | Read API call |
|---|---|
| Method | GET or POST |
| URL | https://app.bubblehouse.com/api/v2023061/<shop>/QueryOrderDetails1 |
| Authentication | AnonymousCustomer TokenShop Token |
This function allows you to get detailed information about points earned for an existing order. It returns the same data structure as EstimateAccrual1, but works with placed orders using their order ID instead of requiring an Order2 object.
This is useful for displaying point earning details to customers after an order has been placed.
Anonymous calls succeed only when Bubblehouse has enabled them for that shop. Anonymous order details inside widget config are a separate switch that Bubblehouse also has to enable.
Guests and ordinary customer tokens (a logged-in buyer) receive an empty accrual_debug_info. Customer-admin, partner, shop, admin, integration, staff, user, and block-preview tokens still receive the trace, and they are not limited to their own order.
When the shop maintains the opt-in preview, an ordinary customer token reading its own order while that customer has not joined the loyalty program but can join it also receives pts_optin_preview, pts_optin_preview_value, and pts_optin_preview_pending. This includes customers who declined the program earlier, unless the shop turns that off. Everyone else gets none of them. A missing order still returns 404, so a caller waiting for a just-placed order keeps asking until the order is found and pts_optin_preview_pending is absent.
Input
-
order_idstring requiredThe ID of the existing order to retrieve point details for.
-
new_order_pollingboolean optionalSet to true when repeatedly asking for an order that was just placed and may not be in Bubblehouse yet.
The response is the same, including 404 order not found, but those 404s are not recorded as failures.
-
countrystring optionalThe buyer's country code, as the checkout reports it.
Optional buyer context, the same fields Bubblehouse checkout widgets send. When given, pts_optin_preview_value uses the market the widget showing this order uses. Other outputs are unaffected.
-
currencystring optionalThe checkout currency code.
-
localestring optionalThe checkout language, such as fr or fr-CA.
-
marketHandlestring optionalThe Shopify market handle of the checkout.
-
timezonestring optionalThe buyer's time zone.
-
shippingCountrystring optionalThe shipping address country code.
-
billingCountrystring optionalThe billing address country code.
Output
-
ptsinteger requiredThe number of order-accrual points earned for this order.
This only includes points from the order amount. It does not include bonus points from achievements or ways-to-earn triggered by the order (see pts_from_rewards).
-
pts_from_rewardsinteger requiredPoints earned from achievements and ways-to-earn triggered by this order.
The sum of pts_earned across all entries in the assets array. Does not include the standard order-accrual points (the pts field). The total points earned from this order is pts + pts_from_rewards.
-
Detailed breakdown of point calculations for each order line item.
Each line item includes information about the subtotal, accrual amount, points, and any applicable multipliers or discounts.
-
Assets (achievements and ways-to-earn) that were unlocked by this order.
Each entry includes the asset definition and the points the customer earned from unlocking it. This shows which achievements or bonus point rewards the customer received when the order was processed.
-
pts_optin_previewinteger optionalPoints the calling customer would have right after joining the loyalty program now.
Their current points balance plus eligible earlier orders plus the welcome bonus when joining would pay it. Never negative. Present only for the calling customer before they join; can be 0.
-
pts_optin_preview_valuestring optionalpts_optin_preview as formatted money, for example $6.00.
Present together with pts_optin_preview.
-
pts_optin_preview_pendingboolean optionalTrue while this order does not count in pts_optin_preview yet but will, for example until its payment completes.
Omitted when false. Ask again until it is absent to show the final pts_optin_preview.
-
accrual_debug_infostring requiredDebug information about how the points were calculated.
This is intended for development and troubleshooting, not for displaying to end users. Guests and ordinary customer tokens receive an empty string. Customer-admin, partner, shop, admin, integration, staff, user, and block-preview tokens receive the trace.
Specific Errors
| Status | Error | Reason & Examples |
|---|---|---|
| 404 | order not found |
The specified order ID does not exist. An ordinary customer token also gets this when the order belongs to someone else. |
| 403 | access_denied |
Anonymous access is off for this shop. Bubblehouse has to turn it on. The public message is: QueryOrderDetails1 requires authentication unless Bubblehouse configures your store to allow anonymous calls. |
| 429 | too_many_requests |
The caller exceeded the order-detail rate limit. The public message is: QueryOrderDetails1 is rate-limited. |
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 | inaccessible_global_api_version |
The global API version you are trying to use is not enabled on your account. |
| 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: |