Self-Serve Billing for the Carbonmark API: From Sandbox Key to Production Retirement

Self-serve production access to the Carbonmark API is now enabled. Here is what changed, how to go live step by step, and two more places to embed verified carbon retirement.
For the past year we've had the pleasure of speaking with software innovators interested in building novel integrations for carbon offsetting. As is often the case, the technology or software documentation is not the primary blocker on getting started and deploying new tools; rather, it's the manual steps for onboarding and having everything in order on the business side.
Just as we've worked to enable automated offsetting via our API, we've been busy over the past few months ensuring that our onboarding experience can be just as intuitive.
With the new self-serve billing experience in the Developer Dashboard, a team can set up its business details, add funds by card or bank link, and create its own production API key. No call, no contract, no approval queue.
This guide covers what changed, how the balance works, the exact steps from a free sandbox key to a live retirement, and two more use cases: shipping and logistics software and travel and expense platforms.
Key Takeaways
- Carbonmark's API production access is now self-serve. A Self-serve account adds funds by card or bank link in the Developer Dashboard and creates production keys itself once business setup is complete and the first payment is credited.
- Funds are reserved per order, not per quote. A production order reserves its quoted cost, the amount is charged when the carbon credit retirement completes, and it is released if the order fails. Sandbox keys are free and never billed.
- Every production key carries a weekly spending limit, so an automated integration has a hard ceiling by design.
- Enterprise accounts remain available for larger or contracted volumes, invoiced monthly under an agreement with Carbonmark.
- Retirement is fractional from 0.001 tCO₂e (1 kg) for many credit types, which is what makes per-shipment and per-trip retirement practical inside other software.
What changed: production access without a lengthy onboarding process
Carbonmark API users can now choose between two account types on the Billing page of the Developer Dashboard: Self-serve, which pays from a balance funded by card or bank link, and Enterprise, which is designed for large volumes and is invoiced monthly.
Until now, production access followed onboarding with our team. That model still exists, and it is often still the right one for bespoke integrations and large transaction volumes of $5,000 or more per month. But this model is not a great fit for the agile software developer who wants to ship a small feature this week and find out whether customers use it.
The billing documentation sets out the two paths:
| Self-serve | Enterprise | |
|---|---|---|
| How you pay | Add funds by card or bank link in the Developer Dashboard. Retirements are paid from your balance. | Monthly invoice, arranged with Carbonmark sales. |
| Production keys | Available once business setup is complete and your first payment is credited. | Available after Carbonmark approves your account. |
| Good fit for | Getting to production quickly without a sales conversation. | Larger or contracted volumes. |
Sandbox keys sit outside both. They are free, they can be created before or after you choose an account type, and sandbox retirements never touch your balance.
One practical note: you choose the account type yourself, but changing it afterwards goes through Carbonmark. Pick the one that matches how you expect to pay over the next year, not just this month.
How the prepaid balance works
A Self-serve balance works like a prepaid account: you add funds first, each production order reserves its cost, and the charge lands only when the retirement completes.
The mechanics are simple.
- Quotes are free to create. Calling
POST /quotesdoes not reserve funds. Only orders do. - An order reserves its cost. When you submit an order with a production key, the order's cost (
cost_usdcfrom the quote) is reserved from your available balance. - Completion charges it. If the retirement completes, the reserved amount is charged. If the order fails, the reservation is released back to your balance.
- Available balance is what you can spend now: your funded balance minus the amounts reserved for orders still in progress. The dashboard shows a notice when it falls below $50.
Reserve, then charge or release. This is how we bring instant settlement for our merchants and increase the velocity of carbon market activity and project funding.
Limits are part of the design
Self-serve accounts have spending and funding limits, and the Dashboard and Billing pages show each limit alongside how much of it you have used.
| Limit | What it controls |
|---|---|
| Spend limit | Total retirement spend across all keys over a rolling period |
| Key spend limit | Retirement spend for one key over a rolling 7 days |
| Maximum per top-up | The largest single purchase |
| Top-up limit | Total purchases over a rolling period |
| Maximum balance | The most your balance can hold, including pending purchases |
Spend limits free up gradually as older spending moves out of the rolling period, and adding funds does not reset them. If you outgrow one, the Billing page has a Request a limit increase button.
How to get started: six steps from sandbox to production
Going live on a Self-serve account takes six steps: create a sandbox key, run a test retirement, choose Self-serve, complete business setup, add funds, and create a production key.
Step 1: Create a free sandbox key
Create an account or sign in at the Developer Dashboard, open Keys, and generate a sandbox key. Keys are shown only once, so copy and store yours securely.
Keep the key on your server. Never expose it in client-side code or commit it to a repository.
Step 2: Run a test retirement
The retirement workflow is the same in sandbox and production: get a price source, create a quote, place an order, confirm completion. Always use the versioned base URL. Version 20 is the current stable release.
Price. Ask /prices for the listings on a project. This example uses VCS-1146, a waste energy recovery project in the Republic of Korea, as the documentation does.
curl -G https://v20.api.carbonmark.com/prices \
--data-urlencode "projectIds=VCS-1146" \
--header "Accept: application/json"
Take the sourceId of a listing with enough liquidSupply. That value is your asset_price_source_id.
Quote. Lock a price for the quantity you want to retire.
curl --request POST \
--url https://v20.api.carbonmark.com/quotes \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"asset_price_source_id": "listing-8453-0xea39...1100",
"quantity_tonnes": 1
}'
The response returns a uuid and a cost_usdc. On November 13, 2026, this listing quoted $1.022 for one tonne.
Order. Place the retirement with the quote's uuid, the beneficiary, and a retirement message.
curl --request POST \
--url https://v20.api.carbonmark.com/orders \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: order-0001" \
--data '{
"quote_uuid": "07495f6c-8b02-465d-8fdd-4bcc2d2047e9",
"beneficiary_name": "Acme Logistics Ltd",
"retirement_message": "Test retirement of 1 tonne from VCS-1146"
}'
Confirm. Poll GET /orders with the quote_uuid until the status moves from SUBMITTED to COMPLETED or FAILED. Both are final, so stop polling at either.
curl -G https://v20.api.carbonmark.com/orders \
--data-urlencode "quote_uuid=07495f6c-8b02-465d-8fdd-4bcc2d2047e9" \
--header "Authorization: Bearer YOUR_API_KEY"
A completed order returns a transaction_hash, an on_chain_explorer_url, and a view_retirement_url: the public retirement receipt you will show your own users.
If the status is FAILED, the retirement did not happen. On a Self-serve account, the reserved amount is released back to your available balance.
Step 3: Choose Self-serve
When the sandbox flow works, open Billing in the Developer Dashboard and select Choose self-serve.
Step 4: Complete business setup
Enter five details: company name, legal entity name, company website, country, and how you will use the API. You can update them later from the Billing page.
Step 5: Add funds
Choose an amount and select Purchase. Review the processing fee and the total charge, then select Continue to Checkout to pay by card or bank link.
Three details save time here:
- The minimum purchase is $50. Your plan's maximum per purchase is shown on the Billing page.
- The fee is on top. Your balance increases by the amount you chose, and the processing fee is shown before you pay.
- Returning from checkout is not confirmation. Your balance updates once the payment is confirmed. Purchase History on the Billing page shows the status of every payment (ending in Completed when the funds are in your balance) and holds every receipt.
To put $50 in context: at the $1.022 example price above, it covers roughly 48 tonnes of retirements.
Step 6: Create a production key
Open Keys, create a key, and select Production. Set a weekly spending limit for the key. The dashboard shows the highest limit your plan allows.
Again, the key is shown once. Store it in your secrets manager, not in your codebase. Then swap the sandbox key for the production key in your integration.
Optional: harden your order calls. Add the two things below before real traffic arrives.
Send an Idempotency-Key with every order. For production keys on Self-serve accounts, POST /orders is idempotent. If a request times out, send the same request with the same key and you get the original order back instead of a second one. You are charged once. Use an identifier you already have, such as a shipment or booking ID.
Handle errors by code, not by message text. Self-serve accounts return structured errors with a stable code and a recovery object that tells your integration what to do next.
| Code | HTTP status | What it means | What to do |
|---|---|---|---|
PREPAID_INSUFFICIENT_BALANCE | 402 | Your available balance does not cover the order | Add funds, then retry |
PREPAID_KEY_SPEND_LIMIT | 409 | The order would exceed this key's weekly limit | Wait until next_available_at, or use a key with a higher limit |
PREPAID_ACCOUNT_SPEND_LIMIT | 409 | The order would exceed your account's spend limit | Wait until next_available_at, or request a limit increase |
PREPAID_QUOTE_INVALID | 400 | The quote has expired or was already used | Create a new quote |
If your balance or a limit does not cover an order, you get an error instead of an order. Nothing is half-submitted.
What teams have already built on the Carbonmark API
The Carbonmark API already powers per-order retirement in e-commerce, round-ups and offset-backed products in fintech, product-level climate claims, autonomous purchases by AI agents, and retirements triggered from carbon accounting software.
Self-serve billing shortens the path to every one of these. If you are deciding what to build, the earlier pieces are the fastest way in:
- E-commerce checkout. A storefront estimates an order's residual footprint and retires it on the spot. Our guide to carbon at checkout covers the full API flow, the hosted Checkout Service, and the TrueMoney Wallet integration that put offsetting in front of roughly 20 million users.
- Fintech products. Point-of-sale round-ups, offset-backed cards, merchant dashboards, and compensation for AI and cloud compute bursts: see five fintech use cases for carbon offsetting.
- Product climate claims. A retirement record linked from a Digital Product Passport replaces a "carbon neutral" label with proof a customer can check.
- AI agents. Through Carbonmark's x402 endpoint, agents discover, pay for, and retire credits autonomously, a separate pay-per-call route beside the API key model described here.
- Carbon accounting software. Carbonmark's carbon accounting integrations let a measured footprint flow straight into a retirement.
The pattern is the same in each. The software already knows when an emitting event happens. The API turns that event into a verified retirement with a public record.
Here are two more places where that pattern fits.
Use case 1: per-shipment retirement in shipping and logistics software
A transport management system, label-printing tool, or freight-quoting platform can retire carbon for each shipment at the moment it is booked, and attach the public retirement receipt to the tracking page and the invoice.
Freight is a large and measurable footprint. Freight transportation makes up 8% of global greenhouse gas emissions, and as much as 11% once warehouses and ports are included.
It is also a footprint that logistics software is unusually well placed to quantify. A shipment record already holds the weight, the distance, and the mode. The ISO 14083 standard, published in 2023 and applied to freight through the Smart Freight Centre's GLEC Framework, gives a common method for turning those fields into emissions per shipment.
Reduction comes first: mode shift, consolidation, better load factors, cleaner fleets. But a shipper cannot design out every tonne-kilometer this year. For the residual, per-shipment retirement is now a small integration.
How it works in the product:
- Calculate. When a shipment is booked or a label is created, the platform computes its emissions with its existing methodology. Say the result is 30 kg CO₂e (an illustrative figure).
- Quote and order. The platform calls
POST /quoteswithquantity_tonnes: 0.03, thenPOST /orderswith the shipper's legal name asbeneficiary_name, aretirement_messagenaming the shipment reference and lane, and the shipment ID as theIdempotency-Key. - Show the proof. When the order completes, the
view_retirement_urlgoes on the tracking page, the proof-of-delivery email, and the invoice line.
At the example listing price in this guide, that 30 kg retirement costs about three cents. The project you choose changes the number, and that choice is a quality decision, not just a price decision.
Where self-serve billing fits. The platform funds one balance and runs the retirement job on a production key with a weekly spending limit sized to expected volume. A PREPAID_INSUFFICIENT_BALANCE response becomes an internal alert to top up, not a failed customer shipment. Because orders are idempotent, a carrier webhook that fires twice does not retire twice.
One design decision to make early. The minimum retirement on most listings is 0.001 tonnes (1 kg). A small parcel can fall below that, so parcel-heavy platforms should aggregate: one retirement per shipper per day, with the shipment references carried in the retirement message or in the platform's own records.
Use case 2: per-trip retirement in travel and expense platforms
A corporate travel or expense management platform can retire carbon for each trip when it is booked or when the expense report is approved, so finance sees the emissions and the compensation on the same line item.
Aviation accounts for about 2.5% of global CO₂ emissions, and its contribution to warming to date is closer to 4% once non-CO₂ effects are counted. For a company whose people fly regularly, business travel is one of the few emissions sources it can see trip by trip.
Yet the usual corporate process is annual. Someone exports a year of travel data in January, estimates a total, and buys credits in one batch. The purchase is disconnected from the trips, the cost centers, and the people who booked them.
A travel and expense platform can close that gap, because it holds the itinerary at the moment of booking and the approval at the moment of spend.
How it works in the product:
- Set the policy. A finance admin switches on a rule: for example, compensate every approved flight, charged to the traveler's cost center.
- Calculate per trip. A round trip of 1,500 km each way in short-haul economy comes to about 0.41 tCO₂e, using the short-haul economy factor and 8% routing uplift from Carbonmark's event emissions calculator (2 legs × 1,500 km × 1.08 × 0.12576 kg per km). The flight emissions calculator gives the same kind of estimate trip by trip.
- Retire at approval. The platform quotes and orders that quantity with the company's legal name as beneficiary and a message such as "Trip TR-20418, Berlin to Barcelona return, November 2026."
- Report. The receipt URL attaches to the expense line. At period end, the sustainability lead exports a list of retirements instead of reconstructing one.
At the example listing price in this guide, that trip costs about $0.42 to compensate. A portfolio of forestry or removal credits will cost more, and many companies will want exactly that. Our guide to how businesses buy carbon credits covers the three-question quality check to run before fixing a default project.
Where self-serve billing fits. A platform can launch this as an opt-in feature without negotiating volume first: fund a balance, set a weekly key limit, and learn what adoption looks like. If the feature takes off, limits can be raised from the Billing page, and an Enterprise account with monthly invoicing is there when volumes are contracted.
Keep the claim precise. Retiring credits for a flight does not make the flight emission-free, and the travel policy (fewer trips, rail for short routes) still comes first.
- ❌ "All our business travel is carbon neutral."
- ✅ "In Q4 2026 we cut flight emissions 15% against the prior year and retired 212 tCO₂e against the remainder. Every retirement record is public: [link]."
Self-serve or Enterprise: which should you choose?
Choose Self-serve to reach production quickly and pay as you go by card or bank link. Choose Enterprise when volumes are large or contracted and a monthly invoice suits your finance team better.
A few honest trade-offs help with the decision:
- Self-serve is prepaid. Funds must be in the balance before an order is accepted. For a steady integration, that means monitoring the balance and topping up ahead of demand.
- Self-serve has limits. They protect you and us, and they can be raised on request, but a team that knows it will retire at high volume from day one may prefer to start with a conversation.
- Payment acceptance varies. Self-serve accounts pay by card or bank link, cards issued in some countries may not be accepted, and a payment that is refunded, disputed, or under review can restrict the account until it is resolved.
- Enterprise is invoiced. Completed production orders are included in a monthly invoice, under an agreement with Carbonmark.
Many teams will start on one and know within a quarter whether it still fits.
Frequently asked questions
What is Carbonmark API self-serve billing?
Carbonmark API self-serve billing is a prepaid account type in the Carbonmark Developer Dashboard. A business completes a short setup, adds funds by card or bank link, and creates its own production API keys. Retirements are paid from the balance, with no sales conversation or account approval required.
How do I get a production Carbonmark API key?
Sign in to the Carbonmark Developer Dashboard, choose Self-serve on the Billing page, complete business setup, and add funds by card or bank link. Once the first payment is credited, open Keys, create a key, select Production, and set its weekly spending limit. Enterprise accounts receive production keys after Carbonmark approves the account.
How much does it cost to start using the Carbonmark API in production?
The minimum top-up on a Self-serve account is $50, plus a processing fee that is shown before you pay. Sandbox keys are free and sandbox retirements are never billed. Each retirement then costs the amount returned in its quote.
When is my Carbonmark API balance charged?
A production order reserves its quoted cost from your available balance when it is accepted. The reserved amount is charged when the retirement completes and released back to your balance if the order fails. Creating a quote does not reserve or charge anything.
What happens if my balance runs out?
The API returns the error code PREPAID_INSUFFICIENT_BALANCE with HTTP status 402 instead of creating an order. Add funds on the Billing page and retry. The dashboard also shows a notice when your available balance falls below $50.
Can software retire carbon for a single shipment or business trip?
Yes. The Carbonmark API supports fractional retirement from 0.001 tCO₂e (1 kg) for many credit types, so a logistics platform can retire carbon per shipment and a travel and expense platform can retire it per trip. Each completed retirement returns a public receipt URL that can be attached to an invoice or expense line.
Start building
The first step costs nothing. Create a free sandbox key in the Developer Dashboard, run the four calls above, and look at the retirement receipt your users would see.
When you are ready for real retirements, choose Self-serve on the Billing page, add funds from $50, and create your production key. The API and integrations page has the overview, the developer docs have the detail, and our Solutions Team can help you choose a project portfolio that matches the claim you want to make.
Carbon markets have long been slower than the software that wants to use them. The API closed the technical gap. Self-serve billing closes the commercial one.


