How to Use the GoodAPI Plastic Removal API: A Developer Guide

Introduction: Automate Ocean Plastic Removal With a Single API Call

Removing ocean bound plastic from the environment used to require lengthy partnerships, manual invoicing, and zero developer tooling. GoodAPI changes that. With a single POST request, you can fund the collection and verified processing of ocean bound plastic bottles through our partner network.

This guide walks you through everything you need to integrate the GoodAPI plastic removal API into your application. Whether you are building a Shopify app, a SaaS product, or a custom checkout flow, you will be making verified plastic removal calls in under 10 minutes.

Full documentation is available at docs.thegoodapi.com.

Getting Your API Key

Before making any API calls, you need a GoodAPI account and an API key.

Step 1: Visit docs.thegoodapi.com and sign up for an account.

Step 2: Once registered, you will receive both a production API key and a test API key.

Step 3: Use the test key during development. It works exactly like the production key but does not incur charges or trigger real plastic removal events. Switch to the production key when you are ready to go live.

Your API key is passed in the Authorization header of every request. There is no OAuth flow or token exchange required. Authentication is as simple as including your key directly in the header.

The Plastic Removal Endpoint

The core endpoint for removing ocean bound plastic bottles is:

POST https://app.thegoodapi.com/rescue/plastic_bottles

This endpoint accepts a JSON body and returns a confirmation with details about the bottles rescued.

Request Headers

Every request requires two headers:

Authorization: YOUR_API_KEY
Content-Type: application/json

Request Body Parameters

The request body accepts the following parameters:

count (integer, required): The number of plastic bottles you want to rescue. This is the only required parameter. Each unit represents one ocean bound plastic bottle that will be collected and verified.

attribution (string, optional): A non-unique lookup key you can use to tag the removal event. This is useful for associating plastic removal with a specific customer, order, or campaign. You can later filter your removal history by this attribution key.

metadata (JSON object, optional): Arbitrary key-value pairs that you can attach to the removal event. Use this to store any additional context like order IDs, customer emails, product SKUs, or campaign identifiers.

idempotency_key (string, optional): A unique key to prevent duplicate removal events. If you send the same idempotency key twice, the second request will not trigger an additional removal. This is essential for webhook-driven integrations where retries might occur.

Code Examples

cURL

The simplest way to test the endpoint is with cURL:

curl --request POST \
  --url https://app.thegoodapi.com/rescue/plastic_bottles \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"count": 5, "attribution": "order-12345", "metadata": {"customer_email": "jane@example.com", "order_id": "12345"}}'

Replace YOUR_API_KEY with your test key to try it without charges.

Python

For Python applications, using the requests library:

import requests

url = "https://app.thegoodapi.com/rescue/plastic_bottles"
headers = {
    "Authorization": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "count": 5,
    "attribution": "order-12345",
    "metadata": {
        "order_id": "12345",
        "customer_email": "jane@example.com"
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Node.js

For Node.js applications using the built-in fetch API:

const response = await fetch('https://app.thegoodapi.com/rescue/plastic_bottles', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    count: 5,
    attribution: 'order-12345',
    metadata: {
      order_id: '12345',
      customer_email: 'jane@example.com'
    }
  })
});

const data = await response.json();
console.log(data);

PHP

For PHP applications:

$ch = curl_init('https://app.thegoodapi.com/rescue/plastic_bottles');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: YOUR_API_KEY',
  'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'count' => 5,
  'attribution' => 'order-12345',
  'metadata' => ['order_id' => '12345']
]));

$response = curl_exec($ch);
curl_close($ch);
echo $response;

Understanding the Response

A successful 200 response returns a JSON object with the following key fields:

total_rescued_bottles: The total number of bottles your account has rescued to date across all API calls.

total_rescued_bottles_month: The number of bottles rescued in the current billing month.

bottle_details: An array of objects containing the details of the bottles just rescued, including:

• id: A unique identifier for this rescue event.
• count: The number of bottles rescued in this call.
• fractional_count: For partial bottle counts if applicable.
• created_at: The timestamp of the rescue event.
• idempotency_key: The idempotency key if one was provided.
• metadata: The metadata object you passed in the request.
• attribution: The attribution string you passed in the request.
• refunded: Whether this rescue event has been refunded.

Pricing

Ocean bound plastic removal through GoodAPI costs $0.05 per bottle. Your first 100 bottles are free, giving you room to test the integration in production before committing to a paid volume.

GoodAPI bills monthly. At the end of each billing cycle, you receive an invoice for all production API calls made during that period. There are no upfront costs, no minimum commitments, and no contracts. You can scale up or down at any time.

For a Shopify store removing 3 bottles per order and processing 1,000 orders per month, the cost would be $150 per month. That works out to $0.15 per order, a negligible cost that delivers measurable environmental impact and a strong customer loyalty signal.

Best Practices for Integration

Use Idempotency Keys

If your integration is triggered by webhooks (such as Shopify order webhooks), always include an idempotency key. Webhooks can fire multiple times for the same event, and without an idempotency key, you could trigger duplicate removals. Use the order ID or transaction ID as your idempotency key to ensure each event is processed exactly once.

Use Attribution for Tracking

The attribution field is powerful for analytics. By tagging each removal with a customer email, order ID, or campaign name, you can later query your removal history to understand which customers, products, or campaigns drive the most impact. This data is invaluable for sustainability reporting and marketing.

Store Metadata Generously

The metadata field accepts any JSON object, so use it to store whatever context is relevant to your business. Common metadata includes order IDs, product names, store identifiers (for multi-store setups), and campaign tags. This makes it easy to reconcile your impact data with your business data.

Handle Errors Gracefully

Like any API, the plastic removal endpoint can return errors. Common scenarios include invalid API keys (401), malformed request bodies (400), and rate limiting. Implement proper error handling and retry logic with exponential backoff. For mission-critical integrations, consider queuing removal requests and processing them asynchronously.

Use Test Keys During Development

GoodAPI provides separate test and production API keys. The test key behaves identically to the production key but does not trigger real plastic removal or generate charges. Always develop and test with the test key, and only switch to the production key when deploying to your live environment.

Common Integration Patterns

E-Commerce: Remove Plastic Per Order

The most common pattern is triggering plastic removal after each completed order. In a Shopify store, this is handled automatically by the GoodAPI Shopify app. For custom integrations, listen for your order completion webhook and make a POST call to the plastic removal endpoint with the order details in the metadata.

SaaS: Remove Plastic Per Subscription

SaaS companies can tie plastic removal to subscription events. Plant trees or remove plastic when a user signs up, upgrades, or renews. This creates a tangible environmental benefit that customers associate with their subscription, increasing perceived value and reducing churn.

Marketing: Remove Plastic Per Campaign Action

Use plastic removal as a campaign incentive. Remove bottles when users complete a survey, sign up for a newsletter, leave a product review, or share on social media. The API’s flexibility means you can attach plastic removal to any digital action that your application can detect.

Multi-Impact: Combine Trees and Plastic

GoodAPI supports both tree planting (POST https://app.thegoodapi.com/plant/trees) and plastic removal (POST https://app.thegoodapi.com/rescue/plastic_bottles) through the same API key and authentication pattern. Many businesses call both endpoints on the same trigger to deliver a combined environmental impact with every transaction.

Displaying Your Impact to Customers

Removing ocean plastic behind the scenes is great, but showing your customers the impact is what drives loyalty and conversions. GoodAPI provides several tools for this.

Public Impact Dashboard. GoodAPI generates a public-facing dashboard that displays your total bottles rescued, trees planted, and project details. You can embed this dashboard on your website or link to it from your footer or sustainability page.

Widgets and Badges. Add impact counters and badges to your storefront that update in real time. Customers see “1,250 bottles rescued” growing with every order, creating a sense of shared achievement.

Post-Purchase Emails. Use the response data from the API call to personalize confirmation emails. Include the specific bottle count from the customer’s order alongside a link to your public dashboard. Integrations with Klaviyo and other email platforms make this seamless.

Certificates. GoodAPI provides monthly impact certificates that verify your total contributions. These certificates are useful for sustainability reports, social media content, and customer communications.

Verification and Transparency

Every bottle rescued through GoodAPI is verified by our collection and processing partners. The verification chain includes documented collection events with GPS data and timestamps, weigh-in records at processing facilities, processing certificates confirming the plastic was recycled or safely disposed of, and monthly aggregate reports delivered to your account.

This level of transparency means you can make credible environmental claims to your customers, investors, and certification bodies. Every number you share is backed by a verifiable data trail.

Frequently Asked Questions

What is the GoodAPI plastic removal API? The GoodAPI plastic removal API is a REST endpoint that allows developers to automatically fund the collection and processing of ocean bound plastic bottles with a simple POST request. Each API call triggers a verified removal event through GoodAPI’s partner network.

How much does it cost to remove ocean plastic via API? Ocean bound plastic removal through GoodAPI costs $0.05 per bottle. Your first 100 bottles are free. Billing is monthly with no minimum commitments or contracts.

What is the API endpoint for plastic removal? The endpoint is POST https://app.thegoodapi.com/rescue/plastic_bottles. It accepts a JSON body with the number of bottles to remove and optional attribution and metadata fields.

How do I authenticate with the GoodAPI? Pass your API key in the Authorization header of each request. No OAuth or token exchange is required. You receive both a test and production key when you create your account.

Can I use the API with Shopify? Yes. The GoodAPI Shopify app provides a no-code integration that handles plastic removal automatically per order. If you prefer a custom integration, you can use the REST API with Shopify webhooks to trigger removal on order completion.

Can I combine plastic removal with tree planting? Yes. GoodAPI provides separate endpoints for tree planting (POST /plant/trees) and plastic removal (POST /rescue/plastic_bottles). Both use the same API key and authentication pattern, so you can call both on the same trigger.

How is the plastic removal verified? Every removal is tracked through a chain of custody that includes collection documentation, GPS data, weigh-in records, and processing certificates. Monthly verification reports are available through your GoodAPI dashboard.

Is there a rate limit? GoodAPI is built to handle high-volume e-commerce workloads. For most use cases, rate limits will not be a concern. If you anticipate very high volumes, contact the GoodAPI team at hello@thegoodapi.com to discuss your needs.

Get Started

Integrating ocean bound plastic removal into your application takes minutes. Sign up at docs.thegoodapi.com to get your API key, test with the sandbox environment, and go live when you are ready.

Every API call you make funds the collection and verified processing of ocean bound plastic, creating real environmental impact that you can share with your customers and stakeholders.

Visit thegoodapi.com to learn more about our platform, or dive straight into the plastic removal endpoint documentation to start building.