ListOrders3

Returns Bubblehouse-side loyalty facts for orders in a shop.

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

This export is intended for tenant analytics and integrations that need a current-state order feed of loyalty facts known on the Bubblehouse side. Line items, paid amounts, and other commerce fields stay on the shop.

Rows are sorted by the updated cursor. The default sort is updated_desc.

Only orders that already have a non-zero update ID appear. Historical rows that were never filled into the update index, and orders whose update ID is still zero, are not returned. There is no order update-ID backfill.

Polling with updated_after follows the last saved update ID. An order that is later written without going through the order save path keeps its old update ID, so a cursor poll can miss that mutation. A full list still returns the current row.

Input

• fields string optional

  Which order fields to include in the response.

  Use a comma-separated filter string such as default, bhid,shopid,short, customer(email), customer(default), or all.

  In JSON and JSONL, use nested field names such as customer(bhid,id,email).

  In CSV, customer fields are flattened as customer_bhid, customer_id, customer_email, etc.

  The customer subobject supports customer field names from Customer2, together with the built-in aspects ids, default, basics, and all.

• format TabularDataFormat1 optional

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

• pretty boolean optional

  If true, pretty-prints JSON output.

• sort ExportSortOrder optional

  Sort order for the updated cursor.

  Supported values are updated_desc and updated_asc. The default is updated_desc.

• updated_after bubbleflake optional

  Only return rows with update IDs strictly greater than this value.

• updated_before bubbleflake optional

  Only return rows with update IDs strictly smaller than this value.

• limit integer optional

  The number of rows to return.

  When omitted or set to 0, the limit is 10000. Set limit to a negative number (for example -1) to stream every matching order. Use JSONL or CSV for large exports.

Output

The output is in a tabular data format. The exact format is determined by the format input parameter.

The exact set of fields depends on the fields filter string.

JSON and JSONL nest customer as an object (or null when the order has no matched shop customer). CSV flattens customer fields as customer_* columns.

• bhid bubbleflake required

  Unique ID of the order in the Bubblehouse system.

• updated bubbleflake required

  Order update/version ID used for polling.

• shopid string required but can be empty

  The online shop's order ID.

• short string required but can be empty

  The short name assigned to the order by the online shop, if any.

• time time optional

  When the order was placed, if known.

• canceled boolean required

  True when the order is canceled in Bubblehouse.

  Canceled orders still appear if they have an update ID. JSON uses a boolean. CSV uses true or false.

• pts_earned integer required

  Loyalty points awarded for this order.

• pts_redeemed integer required

  Points redeemed toward this order.

  This is the sum of points used on the order. It is not the shop's order total.

• multiplier string required

  The order's point multiplier as a decimal string.

  Examples: 1, 1.5. This is not milles or permyriad.

• redemption_discount_codes array of string required

  Coupon codes used to redeem points on this order.

  Always an array; empty when there are none. Sorted for a stable order. In CSV, the codes are joined with spaces.

• customer Customer2 optional

  Nested customer information for the matched customer.

  Use a subfilter such as customer(bhid,id,email), customer(email), or customer(default) to choose which customer fields to return. Guest orders and orders whose customer cannot be loaded emit JSON null.

  In CSV output, customer subfields are flattened with a customer_ prefix, such as customer_bhid, customer_id, and customer_email.

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.