Troubleshooting

Check your Authorization header — it must use HTTP Basic Auth in the format Basic base64(clientId:clientSecret). Verify your Client ID and Client Secret are correct for the environment you're targeting. See the Authentication guide.

Every request requires an Authorization: Basic ... header. Omitting the header or supplying incorrect credentials returns 401. Ensure the Base64-encoded string encodes exactly clientId:clientSecret. See the Authentication guide.

Sandbox and production credentials are separate. Using sandbox credentials against the production environment (or vice versa) will fail authentication. Use the correct credential pair for each environment. See Environments.

Bamboo blocks requests from IPs that are not on your allowlist, even with valid credentials. Add your server's IP address to the allowlist via the Bamboo Client Portal or by contacting support.

Regenerating your Client Secret invalidates the old one immediately. Update every integration that uses the old secret. The Client ID stays the same — only the Client Secret changes after regeneration.

If the catalog returns an empty items array, check your filter parameters. CurrencyCode, CountryCode, or Name filters may not match any products. Try calling the endpoint without filters first, then narrow results from there. See Get catalog v2.

CountryCode must be a 2-letter ISO code (e.g., US, GB) and CurrencyCode must be a 3-letter ISO code (e.g., USD, GBP). Mixing them up or using the wrong value returns an empty result.

v1 returns a flat brands array with no filtering or pagination. v2 supports filtering by currency, country, name, product ID, and brand ID, plus pagination and target-currency display. Both versions are actively supported. See Get catalog v2 and Get catalog v1.

The sandbox catalog mirrors live catalog structure for realistic testing. Sandbox accounts, balances, and orders are fully isolated from production. Orders created in sandbox are associated with the sandbox channel. See Get catalog v2.

TargetCurrencyconverts display pricing to a single settlement currency without changing the underlying product denomination. It does not affect the product's native currency or the amount charged to your account.

Check the error reason code in the 400 response from Place Order. Common causes: InsufficientBalance (top up your account), InvalidProductIds (verify the product ID from the catalog), InvalidDenomination (value outside minFaceValue/maxFaceValue), UserNotEnabled (contact support). See Place Order.

When order status is PartialFailed, at least one card succeeded and at least one failed. Inspect each item's cards array for individual card statuses. Only cards with status Sold contain valid redemption codes. See Get Order.

Place Order returns a requestId. Use that value with Get Order to retrieve full order details and purchased card codes. If the order status is Pending, Bamboo has not finished processing — retry the endpoint or wait for the webhook callback. See Get Order.

Only deliver card codes to end users after the card status is Sold. Do not release codes from orders in Pending, Processing, or Failed state.

The clientReferenceNumber field in the Orders report equals the RequestId you submitted when placing the order. Use it to map Bamboo orders back to your internal records. See Orders.

Confirm your endpoint URL is a publicly accessible HTTPS URL. Check delivery attempts in the Bamboo Webhooks portal under Test Messages. Bamboo retries failed deliveries automatically. See Webhooks.

Bamboo has two notification systems. Svix webhooks deliver productupdated.v1 and ordercompleted.v1 events with signature verification via the Webhooks portal. Notification URL callbacks are order-status POST callbacks to a URL you configure via the API. See Webhooks and Notification.

Verify the three Svix headers — svix-id, svix-timestamp, and svix-signature — using your Webhook Secret and the Svix library. An incorrect secret or a modified request payload will cause verification to fail. See Webhooks.

Your endpoint must return HTTP 2xx to confirm receipt. Non-2xx responses cause Bamboo to retry delivery. Return 200 immediately and handle any heavy processing asynchronously.

Call GET /api/Integration/v1/notification to view the currently stored callback URL and secret key for your account. See Get Notification.

The sandbox and production environments use the same base URL structure but require different credentials. Ensure your integration uses the correct credential pair for the environment you intend to target. See Environments.

Each environment has its own Client ID and Client Secret. You cannot use sandbox credentials for production requests or vice versa. Obtain separate credentials for each environment from the Bamboo Client Portal.

Always validate new integrations in sandbox before moving to production. Sandbox orders, accounts, and balances are fully isolated from production. Sandbox reports and transactions return sandbox-only activity. See Environments.