Triggers API

Write Call

RecordCustomTrigger1

Report that a customer did a custom action, such as installing an app or completing a survey, to award the points or achievements set up for that trigger.

Kind Write API call
Method POST
URL https://app.bubblehouse.com/api/v2023061/<shop>/RecordCustomTrigger1
Authentication Customer TokenShop Token

To call with a customer token, enable the "Can be invoked as customer" checkbox on the selected custom trigger in Bubblehouse admin. Customer-admin and shop tokens can call regardless of this checkbox. The trigger’s enabled state and reward limits still apply. The most typical usage is making this call from your server using a shop token and specifying a customer ID.

After this call returns, its expected effect — i.e. awarding of points, unlocking of achievements, and other actions — might take a few seconds to be processed (or, in rare cases, longer).

The trigger information is checked for validity at the time of the call, and thus invalid trigger data will always be reported. Customer information might not be fully validated until later, however, and thus invalid customer data might not be reported directly.

A successful API request can be rejected by the trigger's configured reward limit or because the trigger is disabled. In that case ok remains true, accepted is false, and rejection_msg explains the customer-facing outcome.

Use this call for normal custom-event ingest. For customer-support Trigger Now, use AdjustCustomerState3 record_trigger. That action skips the trigger’s reward rate limit; this call still honors it.

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.

  • trigger string required

    Specifies the custom trigger; must match a slug of one of the triggers defined in Bubblehouse admin area.

Output

  • ok always true required

    Indicates a successful response.

  • accepted boolean required

    Whether the trigger occurrence was accepted for reward processing.

  • rejection_msg string optional

    Customer-facing explanation when the occurrence was not accepted.

Specific Errors

Status Error Reason & Examples
403 access_denied

The call uses an ordinary customer token but the trigger’s "Can be invoked as customer" checkbox is disabled. Customer-admin and shop tokens are exempt from this checkbox.

400 unknown_trigger

The specified trigger cannot be found.

Global Errors

Status Error Reason & Examples
401 invalid_token

The provided authentication token is invalid or has expired.

For example: The token has expired

Previous
Overview