ListDocuments3

Returns a list of uploaded receipts and documents processed by Bubblehouse.

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

The returned records are sorted by Bubblehouse document ID.

Use the fields filter string to choose which receipt-export fields to include. The default field set follows the legacy receipt CSV export column surface, including document, customer, moderation, line-item, seller, and extras-form columns.

In JSON and JSONL, use nested field names such as bhid, upload_time, doc_time, number, url, individual_urls, customer(...), items, spend_bucket(...), and extra(...).

In CSV, use the legacy flat export column names such as doc_bhid, upload_date, doc_date, doc_number, doc_url, customer_email, items_title, spend_bucket_min, and extra_campaign_id.

Use markets to limit results to one or more market keys, market API names, or regions. Region filters include the selected region and all descendant markets. Use ROOT for the default market.

Use campaigns to limit results to one or more receipt upload campaign API names.

The markets and campaigns inputs are convenience filters, not an authorization boundary. A shop token accepted by this method remains trusted for all receipts in the tenant.

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

Input

• fields string optional

  Which document fields to include in the response.

  Use a comma-separated filter string such as default, bhid,status,amount, customer(default), customer(email), doc_bhid,status,customer_email, or all.

  For JSON and JSONL, use document field names such as bhid, upload_time, doc_time, number, url, individual_urls, customer(...), items, spend_bucket(...), entity_seller_bhid, entity_seller_title, and extra(...).

  For CSV, use the legacy flat export column names such as doc_bhid, customer_bhid, customer_id, customer_email, doc_url, items_title, spend_bucket_min, spend_bucket_max, and extra_campaign_id.

  The customer subobject supports customer field names from Customer2, together with the built-in aspects ids, default, basics, and all. The spend_bucket subobject supports min and max. The extra subobject supports receipt extras-form field names.

• format TabularDataFormat1 optional

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

• pretty boolean optional

  If true, pretty-prints JSON output.

• sample integer optional

  Return every Nth matching document.

  For example, sample=10 returns every tenth document after all other filters are applied.

• limit integer optional

  The number of objects to return.

  The default limit is 10000. You may use a very large number to stream more results, but be careful with JSON output if you expect a large response.

• status ReceiptStatus optional

  Only return documents with the specified receipt status.

• markets array optional

  Only return documents from the specified markets or regions.

  Each value may be a market key, market API name, or other configured market alias accepted by the shop's market configuration.

  A region value includes documents from the selected region and all descendant markets. ROOT matches default-market documents, including legacy documents stored with a blank market key.

  Omitting this input or passing an empty array applies no market filter. Blank values and unknown values return Bad Request before streaming starts.

• campaigns array optional

  Only return documents attributed to the specified receipt upload campaigns.

  Values are receipt upload campaign API names.

  Omitting this input or passing an empty array applies no campaign filter. Blank values and unknown values return Bad Request before streaming starts.

• after_id bubbleflake optional

  Only return documents with Bubblehouse IDs strictly greater than this one.

• before_id bubbleflake optional

  Only return documents with Bubblehouse IDs strictly smaller than this one.

• after_time time optional

  Only return documents uploaded strictly after this time.

• before_time time optional

  Only return documents uploaded strictly before this time.

• reverse boolean optional

  If true, returns matching documents in reverse Bubblehouse ID order.

Output

• bhid bubbleflake required

  Unique ID of the document in the Bubblehouse system.

  In CSV output, the corresponding flat field name is doc_bhid.

• public_id string required but can be empty

  Public-facing receipt or document ID, when available.

• market_key string optional

  Market API name associated with the document, when the document belongs to a non-default market.

  For campaign-attributed documents, this uses the campaign-applied market API name after the stored non-default document market still resolves. If the stored non-default market key no longer resolves, the stored key is returned instead. Default-market documents return an empty value.

• market_currency string optional

  Currency configured for the document's market.

  For campaign-attributed documents, this uses the campaign-applied market configuration.

• amount_currency string optional

  Currency used for the matched amount used by receipt processing.

• doc_currency string optional

  Currency extracted from the receipt or document.

• status ReceiptStatus required

  Current moderation or processing status of the document.

• number string required but can be empty

  Store receipt or invoice number, when available.

  In CSV output, the corresponding flat field name is doc_number.

• upload_time time required

  When the document was uploaded to Bubblehouse.

  In CSV output, the corresponding flat field name is upload_date.

• doc_time time optional

  Purchase time extracted from the document, if known.

  In CSV output, the corresponding flat field name is doc_date.

• url string optional

  Effective full-document download URL, if available.

  For single-file documents, this is the direct uploaded-file URL. For multi-file documents, this is a signed ZIP download URL for the whole document.

  In CSV output, the corresponding flat field name is doc_url.

• individual_urls array optional

  Direct uploaded-file URLs for each file in upload order.

  Available in JSON and JSONL when explicitly requested or when using fields=all. It is not part of the default JSON/JSONL field set and is not available in CSV output.

• amount money optional

  Matched purchase amount used for receipt processing.

• pts integer required

  The number of loyalty points assigned to this document.

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

  In CSV output, customer subfields are flattened with a customer_ prefix. The legacy receipt export fields include customer_bhid, customer_id, and customer_email.

• decision_time time optional

  When the document was accepted, rejected, or otherwise decided, if a decision has been made.

  In CSV output, the corresponding flat field name is decision_date.

• decision_cause string optional

  How the document decision was made, such as review or automated processing.

• decision_user string optional

  Email address of the Bubblehouse user who made the document decision, when available.

• items array optional

  Line items matched on the document, when available.

  Each item contains product_id, variant_id, title, qty, and amount.

  In CSV output, these values are exposed through the legacy flat columns items_product_id, items_variant_id, items_title, items_qty, and items_amount.

• spend_bucket object optional

  Spend-bucket range for the matched amount, when configured.

  The object contains min and max.

  For campaign-attributed documents, the range uses the campaign-applied spend bucket thresholds and spend bucket currency.

  In CSV output, these values are exposed as spend_bucket_min and spend_bucket_max.

• entity_seller_bhid bubbleflake optional

  Bubblehouse ID of the matched seller entity, when seller matching is configured and the document matched a seller.

  Seller entities are commonly used for authorized dealers, retailers, stores, or other approved sellers configured for receipt validation.

  In CSV output, the corresponding flat field name is also entity_seller_bhid.

• entity_seller_title string optional

  Display title of the matched seller entity, when seller matching is configured and the document matched a seller.

  Seller entities are commonly used for authorized dealers, retailers, stores, or other approved sellers configured for receipt validation.

  In CSV output, the corresponding flat field name is also entity_seller_title.

• pub_comment string optional

  Public comment associated with the document decision or review.

• priv_note string optional

  Internal note associated with the document decision or review.

• suspicion_reason string optional

  Reason the document was flagged as suspicious, when applicable.

• rejection_reason string optional

  Reason the document was rejected, when applicable.

• extra object optional

  Receipt extras-form values, when configured.

  Receipt extras come from the shop's configured receipt upload form fields. Use a subfilter such as extra(receipt_type) or extra(all).

  In CSV output, simple form fields are exposed as extra_<field_api_name>. Compound form fields are flattened as extra_<field_api_name>_<subfield>.

Specific Errors

Status	Error	Reason & Examples
400	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.