Edit with
This page documents every step a Shopify reviewer needs to set up, test, and verify the Carbonaa Carbon Offsets app — including the Shopify Billing API flow.
Carbonaa is a Shopify embedded app. Installation takes under minute.
Click "Add app" on the Carbonaa listing in the Shopify App Store. Shopify redirects you to the OAuth consent screen.
Carbonaa requests minimal scopes: read_orders, read_products, write_products. No billing scopes are requested at install — billing is initiated only when you add offset capacity.
After OAuth, the app loads inside the Shopify admin iframe at /ShopifyHome. You see the Carbonaa dashboard with a welcome state prompting you to add offset capacity.
The app automatically creates a "Carbon Offset by Carbonaa" product in your store (archived, not visible to customers directly). This product powers the customer opt-in checkbox at checkout. If auto-creation fails, a red banner appears with a "Complete Installation" button to retry.
This is the core billing flow. Carbonaa uses the Shopify Billing API (appPurchaseOneTimeCreate) — the merchant never leaves Shopify.
From the Shopify Workspace dashboard, click the green "Add First Offset Capacity" (or "Add Offset Capacity") button. This opens the Carbon Projects page in a new tab.
The Carbon Projects page shows live, verified carbon offset projects (Verra / Gold Standard) with real-time stock and pricing from ClimateTrade. Click "Buy Credits" on any project.
On the Buy Credits page, select a volume (e.g., 10 tonnes), enter your email (for certificate delivery) and organization name (appears on the certificate).
This calls the merchantInventoryCheckout backend function, which creates a Shopify one-time app charge via the Billing API. The merchant is redirected to a Shopify-hosted approval page (not a third-party checkout).
On the Shopify approval page, the merchant sees the exact amount, project name, and description. They can approve or decline. This is the Shopify Billing API's native accept/decline flow.
On approval, Shopify fires the app_purchases_one_time/update webhook. The webhook handler flips the MerchantCreditPurchase status to active and the merchant is redirected back to the workspace showing "Offset Capacity Activated".
Reinstall behavior (requirement 1.2.2)
If a merchant uninstalls and reinstalls the app, the billing flow works identically — each "Add Offset Capacity" creates a fresh appPurchaseOneTimeCreate charge. There is no stale charge state. The merchant can accept, decline, and request approval again on every reinstall.
A Theme App Extension adds an opt-in checkbox to the product page (or cart/checkout, configurable).
Carbonaa uses a Shopify Theme App Extension (not a ScriptTag) to render the offset opt-in checkbox. This is the modern, App Store-compliant approach. The checkbox appears on product pages by default.
When a customer views a product, they see a checkbox: "Make my order carbon-neutral (+$X.XX)". The price is calculated from the product's estimated CO₂ footprint.
When the customer checks the box, the "Carbon Offset by Carbonaa" variant is added to their cart. When they complete checkout, the orders/create webhook fires and Carbonaa processes the offset.
When an order containing the Carbon Offset product is placed, Shopify sends the orders/create webhook to Carbonaa.
Carbonaa deducts the CO₂ amount from the merchant's prepaid offset capacity. If capacity is insufficient, the order is queued and offset automatically when capacity is added.
A retirement certificate (from Verra/Gold Standard registry) is generated and emailed directly to the customer within 2-5 minutes.
Each capacity purchase generates an official retirement certificate, downloadable from the workspace dashboard. The certificate is verifiable on the Verra or Gold Standard registry.
When customers opt in and pay the offset fee, Carbonaa collects the fee via Shopify. The merchant's sell-side margin is collected using the Shopify Billing API Usage Records (appSubscriptionCreate + appUsageRecordCreate). One usage record is created per opted-in order — this is a real Shopify charge on the merchant's Shopify invoice.
appPurchaseOneTimeCreate mutation (offset capacity purchases)appSubscriptionCreate + appUsageRecordCreate (sell-side margin collection)app_purchases_one_time/update handles approval/declineCarbonaa does not require the reviewer to provide any API keys or secret keys. The app integrates with:
Simply install the app on your Shopify dev store and follow the steps above.
Questions during review? Contact amin@carbonaa.net