CustomerQRCode1 - Loyalty API

Returns the customer's member QR code payload and a short-lived URL serving that QR code as a PNG image, for in-store identification flows.

Kind	Read API call
Method	GET or POST
URL	`https://app.bubblehouse.com/api/v2023061/<shop>/CustomerQRCode1`
Authentication	Customer TokenShop Token

You have a choice of making this call from your server using a shop token and specifying a customer ID, or making this call from a web browser/app using a customer token you have generated on the server.

This endpoint supplies the shared member QR code for one customer. Presenting this QR code in store identifies the customer to the merchant's point-of-sale integration; it is not a login token and does not authorize spending or reward selection.

Render payload yourself when you need presentation beyond the served image (custom colors, logos, or layout), or use image_url directly in an <img> tag. Both encode identical content.

Treat image_url as a bearer credential until expires_at. Set the image element’s referrerpolicy to no-referrer. Do not publish or log the URL.

The served image is a black-on-white PNG rendered at error-correction level M. Image responses may be cached privately for up to 5 minutes.

With a shop token, a missing or unknown customer fails with a standard customer identity error. With a customer token for a customer that Bubblehouse has not stored yet, the response is not usable: payload does not identify a stored member, and image_url is rejected.

This call is read-only: it never creates a customer, issues or downloads a wallet pass, or triggers any reward processing. Fetching image_url is also read-only.

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.
size integer optional

Requested image side in pixels. Clamped to the supported range of 64–1024; defaults to 256 when omitted or not positive.

Output

See CustomerQRCodeResult1.

Usage Examples

Retrieve the member QR code

Fetch the payload and image URL for a customer identified by Bubblehouse ID:

Request

{
  "customer": {
    "bhid": "0000018abc123def"
  },
  "size": 512
}

Response

{
  "enabled": true,
  "expires_at": "2026-09-22T13:00:00Z",
  "image_url": "https://app.bubblehouse.com/s/your-shop/member-qr.png?size=512\u0026auth=eyJhbGciOi...",
  "payload": "BH:1:0000018abc123def"
}

API-wide Errors

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

Global Errors

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