ListReferrals3

Returns flattened referral send and referral outcome rows for a shop.

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

This export is intended for tenant analytics and integrations that need a current-state referral feed.

Default mode returns one row per recorded referral, plus one sent-only row for each referral send that has not produced a recorded referral.

Set only_sent_referrals=true to return one row per referral send. This includes sends that later produced recorded referrals.

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

Before using cursor polling for historical data, the shop must have referral update IDs initialized and the referral update indexes reindexed. Existing zero-update rows are not visible through update cursors until this rollout maintenance has run.

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

Input

• fields string optional

  Which referral fields to include in the response.

  Use a comma-separated filter string such as default, bhid,updated,send_bhid,status, referrer(email), referee(email), attached_assets(api_name,status,coupon_code), or all.

  In JSON and JSONL, use nested field names such as referrer(...), referee(...), referrer_coupon, and attached_assets(...).

  The referrer and referee subobjects support customer field names from Customer2. The attached_assets array supports fields from AttachedAssetDetails1.

  In CSV, customer fields are flattened as referrer_bhid, referrer_email, referee_bhid, referee_email, etc.

  CSV includes one pair of dynamic fields for each enabled per-referral achievement with a configured API name: attached_asset_<achievement_api_name>_status and attached_asset_<achievement_api_name>_coupon_code.

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

  The default limit is 10000. Use JSONL or CSV for large exports.

• only_sent_referrals boolean optional

  Return one row per referral send instead of the default flattened referral outcome feed.

  When true, the response includes all referral sends, including sends that already have recorded referral rows.

Output

• bhid bubbleflake required

  Stable row ID.

  Recorded referral rows use the referral ID. Sent-only rows use the referral send ID.

• updated bubbleflake required

  Row update/version ID used for polling.

• send_bhid bubbleflake required

  Referral send ID. Rows produced from the same send share this value.

• sent_at time optional

  When the referral send was last sent or created.

• channel ReferralChannel1 optional

  Referral send channel, such as email, sms, link, or direct.

• destination string optional

  Referral send target or destination.

• referral_code string optional

  Active referral code for the send, when available.

• link string optional

  Referral link for the send, when meaningful.

• referrer Customer2 optional

  Customer who sent the referral.

  In CSV output, this is flattened into fields such as referrer_bhid, referrer_email, and referrer_phone.

• registered_at time optional

  When the referred customer referral row was registered.

• finalized_at time optional

  When the referral was approved or rejected.

• status ReferralStatus3 required

  Public referral status: invited, qualified, approved, or rejected.

• status_label string required

  Human-readable status label, including the configured rejection reason label for rejected referrals.

• rejection_reason string optional

  Stable rejection reason code for rejected referrals.

• referee Customer2 optional

  Referred customer, when a recorded referral exists.

  In CSV output, this is flattened into fields such as referee_bhid, referee_email, and referee_phone.

• reward_pts integer optional

  Points awarded to the referrer for the referral.

• reward_pts_value money optional

  Monetary value of reward_pts in the referral venue and market.

• reward_amount money optional

  Monetary reward awarded to the referrer for the referral.

• referrer_coupon_code string optional

  Primary referrer reward coupon code or display value.

• referrer_coupon object optional

  Structured referrer reward coupon data in JSON and JSONL output.

  Null when the referral has no referrer reward coupon. CSV output uses referrer_coupon_code instead.

• attached_assets array of AttachedAssetDetails1 required

  Attached asset details included in JSON and JSONL output.

  Only enabled per-referral achievements with a configured API name are included. Unnamed achievements are omitted.

  Use attached_assets(...) in the fields filter to choose subfields. The default subfields are api_name, title, status, and coupon_code.

  coupon_code is null when the asset has no awarded coupon data.

• attached_asset_<achievement_api_name>_status AttachedAssetStatus optional

  CSV status column generated for each enabled per-referral achievement with an API name.

• attached_asset_<achievement_api_name>_coupon_code string optional

  CSV awarded coupon code/display value generated for each enabled per-referral achievement with an API name.

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.