Loyalty API

Read Call

QueryOrderDetails1

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_id string required

    The ID of the existing order to retrieve point details for.

  • new_order_polling boolean optional

    Set 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.

  • country string optional

    The 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.

  • currency string optional

    The checkout currency code.

  • locale string optional

    The checkout language, such as fr or fr-CA.

  • marketHandle string optional

    The Shopify market handle of the checkout.

  • timezone string optional

    The buyer's time zone.

  • shippingCountry string optional

    The shipping address country code.

  • billingCountry string optional

    The billing address country code.

Output

  • pts integer required

    The 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_rewards integer required

    Points 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.

  • lines array of OrderLineDetails1 required

    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 array of OrderAssetDetails1 optional

    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_preview integer optional

    Points 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_value string optional

    pts_optin_preview as formatted money, for example $6.00.

    Present together with pts_optin_preview.

  • pts_optin_preview_pending boolean optional

    True 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_info string required

    Debug 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: 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

Previous
LoggedOutBalance1