EstimateAccrual1 - Bubblehouse API

Estimates how many loyalty points a customer would earn for a given order, with support for tier preview based on customer data.

Method	GET or POST
Kind	Read-Only
URL	`https://app.bubblehouse.com/api/v2023061/<shop>/EstimateAccrual1`
Authentication	AnonymousCustomer TokenShop Token

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.

This function allows you to predict how many points would be awarded for a specific order before it's actually placed or processed. This is useful for showing customers their potential point earnings during the checkout process.

The function uses the same Order2 format as the UpdateOrders4 call, making it easy to estimate points for an order before submitting it.

If customer identity is not provided or the customer doesn't exist, the function behaves as if invoked on an empty customer record.

EstimateAccrual1 can preview tier changes based on customer data provided in the order. If the order includes customer tags that would result in a different tier, the API calculates what tier the customer would be in based on the provided tags, and returns an accurate estimate based on the previewed tier, but does not persist the tier change beyond the scope of the call.

Input

customerCustomerIdentity1optional
Identity of the customer placing the order (optional if included in the order object).
orderOrder2required
The order to estimate points for, using the same format as UpdateOrders4.
The order object can include customer data with tags, which will be used to preview tier changes for tag-based tier systems. The customer data in the order (including tags) affects the tier calculation but is not saved to the database.
For tag-based tiers, include the customer's tags in order.customer.tags to get accurate point estimates based on the tier those tags would grant.

Output

ptsintegerrequired
The estimated number of points the customer would earn for this order.
linesarray of OrderLineDetails1required
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.
accrual_debug_infostringrequired
Debug information about how the points were calculated.
This is intended for development and troubleshooting, not for displaying to end users.

Usage Examples

Basic Point Estimation

For a simple point estimation without tier changes:

Request

{
  "order": {
    "id": "ORDER-123",
    "amount_subtotal": "100.00",
    "amount_spent": "110.00"
  }
}

Response

{
  "pts": 100,
  "lines": [
    {
      "id": "ORDER-123",
      "subtotal": "100.00",
      "accrual_amount": "100.00",
      "pts": 100,
      "multiplier": 1
    }
  ],
  "accrual_debug_info": "Base earning: 100 points (1:1 ratio)"
}

The customer earns 100 points based on the order amount. No tier changes occur in this basic scenario.

Estimation with Tier Preview

When using tag-based tiers, include customer tags to preview tier-specific multipliers:

Request

{
  "order": {
    "id": "ORDER-456",
    "amount_subtotal": "100.00",
    "amount_spent": "110.00",
    "customer": {
      "id": "CUST-789",
      "tags": [
        "VIP",
        "Premium"
      ]
    }
  }
}

Response

{
  "pts": 200,
  "lines": [
    {
      "id": "ORDER-456",
      "subtotal": "100.00",
      "accrual_amount": "100.00",
      "pts": 200,
      "multiplier": 2,
      "tier_id": "TIER-VIP",
      "tier_name": "VIP Member"
    }
  ],
  "accrual_debug_info": "VIP tier multiplier applied: 2x points"
}

With the VIP tag, the customer receives a 2x multiplier on their points, earning 200 points instead of 100.

Specific Errors

Status	Error	Reason & Examples
None.

API-wide Errors

Status	Error	Reason & Examples
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. `{"id":"missing_customer_identity"}`
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. `{"id":"empty_customer_identity"}`
404	no_customers_match_customer_identity	The customer identity ('customer' input parameter) does not match a known customer. `{"id":"no_customers_match_customer_identity"}`
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. `{"id":"customer_identity_partially_mismatches_matched_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. `{"id":"customer_identity_does_not_match_token"}`

Global Errors

Status	Error	Reason & Examples
401	invalid_token	The provided authentication token is invalid or has expired. `{"id":"invalid_token","message":"The token has expired"}`
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. `{"id":"rate_limit_exceeded","message":"You are over the read limit per second for this customer"}`
400	obsolete_global_api_version	The global API version you are trying to use is no longer supported. `{"id":"obsolete_global_api_version"}`
400	invalid_global_api_version	The global API version you are trying to use has never existed. `{"id":"invalid_global_api_version"}`
400	inaccessible_global_api_version	The global API version you are trying to use is not enabled on your account. `{"id":"inaccessible_global_api_version"}`