UploadReceipt1

Uploads a receipt image for manual review and point crediting.

Kind	Write API call
Method	POST
URL	https://app.bubblehouse.com/api/v2023061/<shop>/UploadReceipt1
Authentication	Customer TokenShop Token

This endpoint accepts multipart/form-data requests with the receipt image in the file field and JSON input in the data field.

The uploaded receipt will be queued for review. Points will be credited after the receipt is approved.

Self-upload must be enabled for the store to use this endpoint.

If the store's form configuration includes fields with customer_field set to first_name or last_name and the save_to_customer_data flag enabled, submitted values will automatically update the customer's name. Fields with save_to_customer_extras enabled will save their values to the customer's extras map, keyed by the field's API name.

Input

• customer CustomerIdentity1 required if using a shop token

  A customer to operate upon, when using a shop token.

  If you're using a customer token and decide to pass this field (which we do not recommend), it must match the customer from the token.

• market string optional

  The market key for multi-market stores.

  Optional. If provided, the receipt will be associated with the specified market. Use the market's API name (e.g., 'uk-store'), not locale codes.

• form_data object optional

  Additional form field values if the store has configured a receipt upload form.

  The structure depends on the store's form configuration. If the store requires form fields, validation errors will be returned if required fields are missing or invalid. Error messages are translatable and may vary by locale or market.

Output

• document_id bubbleflake required

  The unique ID of the uploaded document.

• public_id string required

  A human-readable reference ID for the receipt (e.g., 'RCP-001').

• status ReceiptStatus required

  The current status of the uploaded receipt.

  Typically 'processing' for stores with automatic processing enabled, or 'pending' otherwise.

Specific Errors

Status	Error	Reason & Examples
422	receipt_upload_disabled	Receipt upload is not enabled for this store. Contact Bubblehouse to enable receipt uploads.
422	missing_uploaded_file	The 'file' field is required but was not provided in the multipart form data.
422	invalid_form_data	The form data provided does not match the store's form configuration. Check the 'fields' key in the error details for specific validation errors. Error messages may be customized per locale or market through the translation system.

API-wide Errors

Status	Error	Reason & Examples
404	empty_customer_identity	All fields of the customer identity ('customer' input parameter) have been empty when using a shop token. You need to either specify a non-empty value for one of the customer identity fields, or use a customer token.
404	customer_identity_partially_mismatches_matched_customer	A customer has been matched by one of the fields of the customer identity ('customer' input parameter), but some non-empty fields do not match Bubblehouse data on that customer.
403	customer_identity_does_not_match_token	API call is using a customer token, but the customer identity in API params does not match the customer from the token.
400	missing_customer_identity	The customer identity ('customer' input parameter) has not been specified when using a shop token. You need to either specify a non-empty value for one of the customer identity fields, or use a customer token.
404	no_customers_match_customer_identity	The customer identity ('customer' input parameter) does not match a known customer.

Global Errors

Status	Error	Reason & Examples
400	inaccessible_global_api_version	The global API version you are trying to use is not enabled on your account.
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.
400	obsolete_global_api_version	The global API version you are trying to use is no longer supported.
400	invalid_global_api_version	The global API version you are trying to use has never existed.
401	invalid_token	The provided authentication token is invalid or has expired.