ImpactAPI Documentation
    • Introduction
    • Quick Start
    • Authentication
    • Donation Sessions
    • Error Handling
    • Pagination
    • Metadata
    • Endpoints
    • Customers
    • Donation Intents
    • Donation Sessions
    • Vendors
    • Campaigns
API Version: v1.0
Back to dashboard
ImpactAPI Documentation

API Endpoints

Complete reference for all available ImpactAPI endpoints.

Campaigns

Campaigns represent the charitable causes available for donations. Each campaign is associated with one or more impact metrics that define what types of impact (trees planted, meals served, etc.) are tracked for donations to that campaign.

GET/campaigns

Returns a list of all active campaigns available on the platform. Each campaign includes its configured impact metrics with impact-to-dollar ratios.

This endpoint is useful for:

  • Displaying available campaigns to donors during donation flow
  • Understanding what impact metrics are tracked for each campaign
  • Building campaign selection interfaces
const response = await fetch("https://testing.impactapi.co/campaigns", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

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

Customers

Customers represent end-users or donors in your organization. Use customers to track and attribute donations to specific individuals for impact tracking and personalized reporting. Customer records support flexible metadata storage for custom fields like email addresses.

GET/customers

Retrieves a paginated list of customers that belong to your organization.

Query Parameters

external_id
stringOptional

Filter customers by external ID. Returns only customers with the exact matching external_id.

per_page
integerOptional

Number of results per page (1-100). Defaults to 10.

page
integerOptional

Page number (minimum 1). Defaults to 1.

sort_by
stringOptional

Field to sort by. Currently supports "created_at", "name", "updated_at". Defaults to "created_at".

sort_order
stringOptional

Sort direction: "asc" or "desc". Defaults to "desc".

const response = await fetch("https://testing.impactapi.co/customers?per_page=10&page=1", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

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

Request Body

external_id
stringOptional

Your external system's unique identifier for this customer (max 255 characters). Must be unique within your organization.

name
stringOptional

The customer's name. Maximum 255 characters.

metadata
objectOptional

Flexible key-value pairs for storing custom information. Commonly used for email addresses, customer source, or other tracking data.

const response = await fetch("https://testing.impactapi.co/customers", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_id: "customer-456",
    name: "Jane Doe",
    metadata: {
      email: "[email protected]",
      source: "web",
      customer_since: "2025-01-01"
    }
  }),
});

const data = await response.json();
console.log(data);
GET/customers/{id}
Get customer details

Retrieves complete details for a specific customer by their unique ID.

const customerId = "01K7HWG38CC1HZR23TVG950A9N";

const response = await fetch(`https://testing.impactapi.co/customers/${customerId}`, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
PATCH/customers/{id}
Update customer details

Updates an existing customer's information. This is a partial update - only the fields you provide will be modified.

Request Body

external_id
stringOptional

Your external system's unique identifier for this customer (max 255 characters). Must be unique within your organization, or null to clear. Omit to leave unchanged.

name
stringOptional

The customer's updated display name (max 255 characters), or null to clear. Omit to leave unchanged.

metadata
objectOptional

Custom JSON object to merge with existing customer metadata, or null to clear all metadata. Omit to leave unchanged.

const customerId = "01K7HWG38CC1HZR23TVG950A9N";

const response = await fetch(`https://testing.impactapi.co/customers/${customerId}`, {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_id: "customer-456-updated",
    name: "Jane Smith",
    metadata: {
      email: "[email protected]",
      source: "mobile",
      updated: true
    }
  }),
});

const data = await response.json();
console.log(data);
DELETE/customers/{id}
Delete a customer

Permanently deletes a customer record. This action cannot be undone. Note that deleting a customer does not affect historical donation sessions or transactions that reference this customer.

const customerId = "01K7HWG38CC1HZR23TVG950A9N";

const response = await fetch(`https://testing.impactapi.co/customers/${customerId}`, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
GET/customers/{id}/impact_metrics

Returns the total environmental and social impact generated through a specific customer's donations. Shows impact metrics like trees planted, meals served, plastic removed, etc., based on actual confirmed donations.

Query Parameters

date_from
stringOptional

Start date for filtering impacts (YYYY-MM-DD format). Example: 2024-01-01

date_to
stringOptional

End date for filtering impacts (YYYY-MM-DD format). Example: 2024-12-31

const response = await fetch("https://testing.impactapi.co/customers/{id}/impact_metrics?date_from=2024-01-01&date_to=2024-12-31", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
GET/customers/{id}/donation_intents

Returns a paginated list of donation intents attributed to this customer. Only session-based donations are included (customer_id is null for direct API donations). Each donation intent includes campaign information and calculated impact metrics.

Query Parameters

per_page
integerOptional

Number of results per page (1-100). Defaults to 10.

page
integerOptional

Page number (minimum 1). Defaults to 1.

sort_by
stringOptional

Field to sort by. Currently only supports "created_at". Defaults to "created_at".

sort_order
stringOptional

Sort direction: "asc" or "desc". Defaults to "desc".

date_from
stringOptional

Filter to intents created on or after this date (YYYY-MM-DD).

date_to
stringOptional

Filter to intents created on or before this date (YYYY-MM-DD).

const response = await fetch("https://testing.impactapi.co/customers/{id}/donation_intents?per_page=10&page=1", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

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

Donation Intents

A donation intent represents a commitment by your organization to make a donation. These intents are tracked throughout your billing cycle, and at the end of the cycle, your organization will be charged for the total amount of all donation intents created during that period.

POST/donation_intents
Create a new donation intent

Create one or more donation intents. You can batch create up to 50 donation intents in a single request.

Send an array of donation intent objects directly.

Request Body

Array item
objectRequired

Each object in the array represents a donation intent.

const response = await fetch("https://testing.impactapi.co/donation_intents", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify([
    { amount: 1000, campaign_identifier: "trees-for-the-future" }
  ]),
});

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

Retrieves a paginated list of donation intents for your organization.

Query Parameters

per_page
integerOptional

Number of results per page (1-100). Defaults to 10.

page
integerOptional

Page number (minimum 1). Defaults to 1.

sort_by
stringOptional

Field to sort by. Currently only "created_at" is supported. Defaults to "created_at".

sort_order
stringOptional

Sort direction: "asc" or "desc". Defaults to "desc".

const response = await fetch("https://testing.impactapi.co/donation_intents?per_page=10&page=1", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
GET/donation_intents/{id}
Get donation intent details

Retrieves full details for a specific donation intent by ID.

const intentId = "01K7HWJ38PYD8PBW9KXFCNGS4C";

const response = await fetch(`https://testing.impactapi.co/donation_intents/${intentId}`, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
PUT/donation_intents/{id}/cancel
Cancel donation intent

Permanently cancels and deletes a donation intent. This is a hard delete and cannot be undone.

const intentId = "01K7HWJ38PYD8PBW9KXFCNGS4C";

const response = await fetch(`https://testing.impactapi.co/donation_intents/${intentId}/cancel`, {
  method: "PUT",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

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

Donation Sessions

Donation sessions manage the donation allocation process with a 24-hour expiration. Sessions can be interactive (customer chooses campaign) or non-interactive (pre-allocated donations). Interactive sessions return a session_secret for client-side use.

POST/sessions
Create a new donation session

Primary endpoint for initiating the donation flow. Creates a temporary session that expires after 24 hours.

Request Body

type
stringRequired

The type of donation session to create.

Possible values:

add_onportion_of_sales_choiceportion_of_sales
amount
integerOptional

Amount in cents (1 to 1,000,000,000). Required for interactive sessions (add_on, portion_of_sales_choice). Must be null for non-interactive sessions.

available_campaigns
array of stringsOptional

Array of campaign slugs to offer to the customer. Required for interactive sessions (add_on, portion_of_sales_choice). Cannot be used with non-interactive sessions.

allocations
array of objectsOptional

Pre-allocated donations (1-10 allocations). Required for non-interactive sessions (portion_of_sales). Cannot be used with interactive sessions.

customer_id
stringOptional

Optional customer ID (ULID format) to associate with this session.

vendor_id
stringOptional

Optional vendor ID (ULID format) to associate with this session.

metadata
objectOptional

Custom key-value pairs for storing additional session information (order_id, transaction_id, etc.).

expires_in
integerOptional

Session expiration time in minutes. Defaults to 1440 (24 hours). Min: 15, Max: 1440.

approximated
booleanOptional

Indicates whether the impact display values are approximated. For visual/UI purposes only. Defaults to false.

Session Types
  • add_on: Interactive - customer chooses campaign for add-on donation
  • portion_of_sales_choice: Interactive - customer chooses which campaign receives portion of sale
  • portion_of_sales: Non-interactive - pre-allocated donations (no user interaction)
const response = await fetch("https://testing.impactapi.co/sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "add_on",
    available_campaigns: ["trees-for-the-future", "cleanhub"],
    amount: 500,
    customer_id: "01K7HWG38CC1HZR23TVG950A9N",
    metadata: {
      source: "checkout",
      order_id: "ORD-12345"
    },
    expires_in: 60
  }),
});

const data = await response.json();
console.log(data);
GET/sessions/{sessionId}
Get donation session details

Retrieves the current state of a donation session, including full campaign details with impact metrics. Supports both Session Authentication (X-Session-Secret header) and API Key Authentication.

Note: GET responses include detailed impact_metrics for each campaign with full information (emoji, icon, verb forms, conversion rates, etc.), while POST create responses have simplified campaign data. Use this GET endpoint when you need rich campaign details for displaying impact calculations to users.

const sessionId = "01K7HWH8ANDSRNC6JK38SY6E45";

const response = await fetch(`https://testing.impactapi.co/sessions/${sessionId}`, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
PATCH/sessions/{sessionId}
Update session details

Partially updates session information such as metadata, vendor_id, or customer_id. This is a PATCH operation - only fields included in the request will be modified.

Request Body

metadata
objectOptional

Can be updated regardless of session status. If omitted, existing metadata unchanged. If sent as null, clears all metadata. If sent as object, merges with existing.

vendor_id
stringOptional

Can only be updated if session is active and not expired. Set to null to dissociate vendor from session.

customer_id
stringOptional

Can only be updated if session is active and not expired. Set to null to dissociate customer from session.

approximated
booleanOptional

Indicates whether the impact display values are approximated. Can be updated regardless of session status. Omit to leave unchanged.

const sessionId = "01K7HWH8ANDSRNC6JK38SY6E45";

const response = await fetch(`https://testing.impactapi.co/sessions/${sessionId}`, {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    metadata: {
      order_id: "ORD-12345",
      utm_source: "email"
    },
    customer_id: "01K7HWG38CC1HZR23TVG950A9N"
  }),
});

const data = await response.json();
console.log(data);
PUT/sessions/{sessionId}/allocations
Save allocations for non-interactive session

Finalizes donation allocations for portion_of_sales sessions only. Requires API key authentication.

Request Body

allocations
arrayRequired

Array of 1-10 allocation objects

const sessionId = "01K7HWJ8BNEF9SK7LM4GZT3C2P";

const response = await fetch(`https://testing.impactapi.co/sessions/${sessionId}/allocations`, {
  method: "PUT",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    allocations: [
      {
        campaign_identifier: "trees-for-the-future",
        amount: 300
      },
      {
        campaign_identifier: "cleanhub",
        amount: 200
      }
    ]
  }),
});

const data = await response.json();
console.log(data);
POST/sessions/{sessionId}/choose_campaign
Choose campaign for interactive session

Allows customer to select which campaign they want to support. For interactive sessions (add_on, portion_of_sales_choice) only. Requires X-Session-Secret header.

Request Body

campaign_identifier
stringOptional

The campaign slug the customer wants to support. Can be null to opt out of donation.

Possible values:

trees-for-the-futureplastic-fischeryellow-roomscleanhubreefgen
const sessionId = "01K7HWH8ANDSRNC6JK38SY6E45";
const sessionSecret = "dn3iumLKuU1OxJlZFMAwJQSkrch0blaExPINfoN8nSpRI6GZuH1QyYtAH84ZRPvC";

const response = await fetch(`https://testing.impactapi.co/sessions/${sessionId}/choose_campaign`, {
  method: "POST",
  headers: {
    "X-Session-Secret": sessionSecret,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_identifier: "trees-for-the-future"
  }),
});

const data = await response.json();
console.log(data);
POST/sessions/{sessionId}/process
Lock session for payment processing

Transitions a session to processing status, locking customer interactions while keeping the session open for backend confirmation. Use this endpoint when the customer clicks "Place Order" and before capturing payment.

Request Body

extends_by
integerOptional

Extends session expiration by this many minutes. Defaults to 10080 (7 days). Min: 60, Max: 43200 (30 days).

Processing Status Behavior
  • Customer Auth: Locked - customers cannot modify the session
  • API Key Auth: Full access - session remains modifiable
  • Lifecycle: processing → confirmed (success) or processing → expired (timeout)
const sessionId = "01K7HWH8ANDSRNC6JK38SY6E45";

const response = await fetch(`https://testing.impactapi.co/sessions/${sessionId}/process`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    extends_by: 10080
  }),
});

const data = await response.json();
console.log(data);
POST/sessions/{sessionId}/confirm
Confirm donation session

Converts a donation session into finalized donation intents. This operation is idempotent - calling it multiple times returns the same result.

const sessionId = "01K7HWH8ANDSRNC6JK38SY6E45";

const response = await fetch(`https://testing.impactapi.co/sessions/${sessionId}/confirm`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

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

Vendors

Vendors represent merchants, stores, or business locations in your organization. Use vendors to track and attribute donations to specific business locations for reporting and attribution purposes.

GET/vendors

Retrieves a paginated list of vendors that belong to your organization.

Query Parameters

external_id
stringOptional

Filter vendors by external ID. Returns only vendors with the exact matching external_id.

per_page
integerOptional

Number of results per page (1-100). Defaults to 10.

page
integerOptional

Page number (minimum 1). Defaults to 1.

sort_by
stringOptional

Field to sort by. Currently supports "created_at", "name", "updated_at". Defaults to "created_at".

sort_order
stringOptional

Sort direction: "asc" or "desc". Defaults to "desc".

const response = await fetch("https://testing.impactapi.co/vendors?per_page=10&page=1", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
POST/vendors
Create a new vendor

Creates a new vendor record for tracking donations and transactions from a specific merchant, store, or business location.

Request Body

external_id
stringOptional

Your external system's unique identifier for this vendor (max 255 characters). Must be unique within your organization.

name
stringOptional

The vendor's name. Maximum 255 characters.

metadata
objectOptional

Flexible key-value pairs for storing custom information about the vendor (location, type, manager, etc.).

const response = await fetch("https://testing.impactapi.co/vendors", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_id: "store-123",
    name: "Downtown Coffee Shop",
    metadata: {
      location: "123 Main St",
      type: "retail",
      manager: "John Doe"
    }
  }),
});

const data = await response.json();
console.log(data);
GET/vendors/{id}
Get vendor details

Retrieves complete details for a specific vendor by their unique ID.

const vendorId = "01K7HWG14S22R5C925AFY6TX60";

const response = await fetch(`https://testing.impactapi.co/vendors/${vendorId}`, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
PATCH/vendors/{id}
Update vendor details

Updates an existing vendor's information. This is a partial update - only the fields you provide will be modified. Metadata fields are merged, not replaced.

Request Body

external_id
stringOptional

Your external system's unique identifier for this vendor (max 255 characters). Must be unique within your organization, or null to clear. Omit to leave unchanged.

name
stringOptional

The vendor's updated display name (max 255 characters), or null to clear. Omit to leave unchanged.

metadata
objectOptional

Custom JSON object to merge with existing vendor metadata, or null to clear all metadata. Omit to leave unchanged.

const vendorId = "01K7HWG14S22R5C925AFY6TX60";

const response = await fetch(`https://testing.impactapi.co/vendors/${vendorId}`, {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_id: "store-123-updated",
    name: "Downtown Coffee Shop - Main Branch",
    metadata: {
      manager: "Jane Smith",
      phone: "555-0123"
    }
  }),
});

const data = await response.json();
console.log(data);
DELETE/vendors/{id}
Delete a vendor

Permanently deletes a vendor record. This action cannot be undone.

const vendorId = "01K7HWG14S22R5C925AFY6TX60";

const response = await fetch(`https://testing.impactapi.co/vendors/${vendorId}`, {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
GET/vendors/{id}/impact_metrics

Returns the total environmental and social impact generated through a specific vendor's donations. Shows impact metrics like trees planted, meals served, plastic removed, etc., based on actual confirmed donations made at this vendor location.

Query Parameters

date_from
stringOptional

Start date for filtering impacts (YYYY-MM-DD format). Example: 2024-01-01

date_to
stringOptional

End date for filtering impacts (YYYY-MM-DD format). Example: 2024-12-31

const response = await fetch("https://testing.impactapi.co/vendors/{id}/impact_metrics?date_from=2024-01-01&date_to=2024-12-31", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
GET/vendors/{id}/donation_intents

Returns a paginated list of donation intents attributed to this vendor. Only session-based donations are included (vendor_id is null for direct API donations). Each donation intent includes campaign information and calculated impact metrics.

Query Parameters

per_page
integerOptional

Number of results per page (1-100). Defaults to 10.

page
integerOptional

Page number (minimum 1). Defaults to 1.

sort_by
stringOptional

Field to sort by. Currently only supports "created_at". Defaults to "created_at".

sort_order
stringOptional

Sort direction: "asc" or "desc". Defaults to "desc".

date_from
stringOptional

Filter to intents created on or after this date (YYYY-MM-DD).

date_to
stringOptional

Filter to intents created on or before this date (YYYY-MM-DD).

const response = await fetch("https://testing.impactapi.co/vendors/{id}/donation_intents?per_page=10&page=1", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.IMPACT_API_KEY}`,
  },
});

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