ListHistory1

Returns a list of changes to Bubblehouse API objects.

Kind	Read API call
Method	GET or POST / OPTIONS
URL	https://app.bubblehouse.com/api/v20230601/<shop>/ListHistory1
Authentication	Shop Token

Note that the output is in a tabular data format determined by the format parameter.

Endpoint is self-documented. You may send OPTIONS request to the endpoint URL to observe full list of supported topics and their fields.

Input

• topics list required

  Comma-separated list of topics you are interested in.

  Each topic corresponds to one or more change kind.

  Each topic extends base set of values to accomodate different change kinds (see the "Output" section).

  Topics are organized hierarchically, meaning, that if you specify topic that has subtopics, then changes matching subtopics would be included.

  Endpoint is self-documented. You may send OPTIONS request to the endpoint URL to observe full list of supported topics and their fields.

  Non-exhaustive list of topics served here as an example: pts, pts:earned, pts:earned:src, pts:earned:reward, pts:earned:ref, pts:earned:ref:sent, pts:earned:ref:recv, etc.

• format TabularDataFormat1 optional

  The response format you want: JSON, JSONL or CSV.

• start_time time optional

  The earliest time of changes that you're interested in.

• end_time bubbleflake optional

  The latest time of changes that you're interested in.

  If live=true, then streaming would stop at the specified time.

• limit integer optional

  The number of objects to return.

  The default limit is 1000 (unless you're streaming), but feel free to use any number here. You can set the limit to -1 or a very large number to disable it; Bubblehouse will be happy to stream the entire history of the shop. If you picked the JSON output format, be careful when processing a potentially huge response this generates.

  If live=true, then streaming would stop at the specified time.

• live boolean optional

  If true, live-streams new entries instead of stopping when reaching the newest entry. Requires a streaming-friendly output format (JSONL or CSV).

• indent boolean optional

  Applicable only for JSON and JSONL. If true, dotted field names would be expanded into nested objects.

• dry boolean optional

  Return only bare-minimum information about each event.

Output

• chg.bhid bubbleflake required

  Unique ID of the change in the Bubblehouse system.

• chg.time time required

  Time when the event was recorded in the Bubblehouse system (RFC3339).

• chg.area ChangeArea1 required

  An enum defining the shape of the change object (ie which other fields are relevant).

• chg.kind ChangeType1 required

  Determines the exact change that has occurred.

• chg.desc string required

  A user-visible description of the change, suitable for a history page

• subj.bhid bubbleflake required

  Unique ID of the subject of change in the Bubblehouse system.

  Typically customer, but may be any other object changes for are tracked by the Bubblehouse system.

  Use related subj.type to correctly identify subject of change.

• subj.type ObjectType1 required

  Type of the subject of change in the Bubblehouse system.

  Typically customer, but may be any other object changes for are tracked by the Bubblehouse system.

• subj.* any optional

  Fields specific for given subject type.

  Endpoint is self-documented. You may send OPTIONS request to the endpoint URL to observe full list of supported topics and their fields.

• obj.bhid bubbleflake optional

  Unique ID of the object caused the change in the Bubblehouse system.

  Change type related object that caused given subject to observe given change.

  Use related obj.type to correctly identify subject of change.

  For example: For points earned from points source it would be a points source ID. For points lost due to order refund it would be an order ID.

  May be empty if no object is currently exposed for given event.

• obj.type ObjectType1 optional

  Type of the object of change in the Bubblehouse system.

  May be empty if no object is currently exposed for given event.

• obj.* any optional

  Fields specific for given object type.

  Additional fields vary by object type. For vendible redemptions (chg.kind="vendible_redemption"), the following product and variant fields may be included:

  obj.product_bhid - Bubblehouse product ID (hex string) of the product associated with the redeemed vendible

  obj.product_shopid - External/ecommerce platform product ID (numeric string)

  obj.variant_bhid - Bubblehouse variant ID (hex string) of the specific variant associated with the vendible

  obj.variant_shopid - External/ecommerce platform variant ID (numeric string)

  Note: Product and variant fields are only present for vendibles that have an associated product variant configured. They will be null or absent for vendibles without variant associations.

  Endpoint is self-documented. You may send OPTIONS request to the endpoint URL to observe full list of supported topics and their fields.

• <i>anything</i> any optional

  Any other fields associated with the event.

  For example: For points-related events Bubblehouse would provide fields such as pts.delta, pts.amount and others.

  Endpoint is self-documented. You may send OPTIONS request to the endpoint URL to observe full list of supported topics and their fields.

Specific Errors

Status	Error	Reason & Examples
401	bad_request

Global Errors

Status	Error	Reason & Examples
401	invalid_token	The provided authentication token is invalid or 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.