Add-ons API Reference

Your add-on JavaScript executes in a DedicatedWorkerGlobalScope, and thus you don't have access to document, window, or any other objects available in a normal browser context.

You do have access to these four global functions:

authenticatedFetch

This function is similar to the browser's fetch function, but it automatically adds the necessary Authorization header to make requests to the Planning Center API on behalf of the user.

const response = await authenticatedFetch(
  'https://api.planningcenteronline.com/people/v2/me'
);
const data = await response.json();
console.log(data);

The function returns a Promise that resolves to a Response object, just like the standard fetch API.

authenticatedIntegratorFetch

This function is similar to authenticatedFetch, but it makes requests to your (the Integrator's) API instead of the Planning Center API. It automatically adds the necessary Authorization header using the token obtained from your OAuth Server.

const response = await authenticatedIntegratorFetch(
  'https://your-api.example.com/send-message',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      message: 'Hello, World!',
      recipients: [1, 2, 3]
    })
  }
);
const data = await response.json();
console.log(data);

Like authenticatedFetch, this function returns a Promise that resolves to a Response object.

addOnEnvironment

This function returns a string indicating which environment your add-on is currently running in. This is useful for conditional logic or debugging.

const env = addOnEnvironment();
console.log(env); // "testing", "beta", or "production"

if (env === 'testing') {
  console.log('Running in testing mode');
}

Possible return values:

• "testing" - Your add-on is in testing mode and only visible to your organization
• "beta" - Your add-on is in beta and available to organizations that have opted in
• "production" - Your add-on is publicly available to all Planning Center organizations

onRender

This is the main entry point for your add-on. You must call this function to mount your React app. It receives an args object that contains context about where and how your add-on is being rendered.

import { Avatar, Button, Text } from '@planningcenter/add-ons-ui';

onRender((args) => {
  const { location, closeModal, currentPersonId, currentOrganizationId } = args;

  console.log('Rendering at:', location);
  console.log('Current person:', currentPersonId);
  console.log('Current organization:', currentOrganizationId);

  return (
    <>
      <Text>Hello from {location}!</Text>
      <Button onClick={() => closeModal()}>Close</Button>
    </>
  );
});

args Object

The args object passed to onRender contains:

• location - A string indicating the insertion point where your add-on is being rendered (e.g., "people.list.send_message")
• currentPersonId - The ID of the currently logged-in user
• currentOrganizationId - The ID of the current organization
• Additional properties specific to each insertion point (see Insertion Points for details)