Skip to content
BloopBloopBloop Docs

Understanding the Bloop API and webhooks

The Bloop API and webhooks let your own systems work with your referral program. A typical use: your custom app sends each referrer their personal referral link and discount code over a channel Bloop does not cover, such as LINE or SMS.

Two tools work together:

Tool Direction Use it to
API Your server asks Bloop Look up a referrer by email, Shopify customer id or Bloop id, and sync every referrer
Webhooks Bloop calls your server React when a referrer joins, when a referral is pending, and when a referral succeeds

Version 1 covers the Referral Program and is read-only: you can read referrers and receive events, but you cannot create or change data through the API.

Who can use it

Section titled “Who can use it”

The API and webhooks are available on the Premium plan (Scale on older plans). On other plans the API & Webhooks page shows the banner “API and webhooks are not included in your plan” with View plans, and API calls return 403 plan_not_eligible. If your store is on a free plan and you need the API for a specific integration, contact support.

If you downgrade, the page shows “API and webhooks are paused”. Your keys and endpoints are kept but stop working: API calls return 403 plan_not_eligible and events are not delivered. You can still revoke keys, disable or delete endpoints and view delivery history. Everything works again as soon as you are back on an eligible plan, with nothing to set up again. Events that happen in between are never delivered.

If you uninstall Bloop, API calls return 403 shop_inactive and events are skipped. If you reinstall soon after, your keys and endpoints are still there, and they work again once the store is on an eligible plan. About 48 hours after an uninstall, Shopify asks Bloop to erase the store’s data, and the keys and endpoints are deleted with it.

What version 1 includes

Section titled “What version 1 includes”
  • GET /v1/me to check a key.
  • GET /v1/referrers to look up one referrer, or to list the referrers that changed since a point in time.
  • GET /v1/referrers/{id} to read one referrer by Bloop id.
  • The webhook events referrer.joined, referral.pending and referral.succeeded, plus webhook.test.

Each referrer comes with every campaign they belong to: share code, referral link, personal discount code, successful referrals and referral revenue.

Keep your key on your server

Section titled “Keep your key on your server”

An API key reads the email address, referral link and discount code of every referrer in your store. Treat it like a password.

  • Call the API from your server only. The API sends no CORS headers, so browsers block calls from a theme, a storefront script or any web page.
  • Never put a key in theme code, a mobile app or a code repository.
  • If a key leaks, revoke it in the app. A revoked key stops working within 60 seconds.
  • Keys don’t expire. Revoke the keys you no longer use, and review the list when the store changes owner: keys belong to the store, not to the person who created them.

Base URL and versions

Section titled “Base URL and versions”

The base URL is https://api.bloop.plus, and every path of version 1 starts with /v1, for example https://api.bloop.plus/v1/me. Within version 1, Bloop only makes changes that a correct client can ignore. See Understanding API versioning and compatibility.

Common mistakes to avoid

Section titled “Common mistakes to avoid”
  • Calling the API from the browser. It fails without CORS headers, and it would expose the key to every visitor.
  • Using webhooks as the only copy of your data. Delivery stops after 7 failed attempts. Use the API to fill gaps.
  • Branching on the plan name. plan in GET /v1/me is for display only.
  • Expecting an event for every change. Some changes send no event. Read Understanding the limitations of v1 before you design your integration.

Next steps

Section titled “Next steps”