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

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

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

• market_currency string optional

  Currency configured for the document's market.

• 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

  URL of the uploaded file, if available.

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

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

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

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.