Extensions

Apps can extend certain core features of the Swell platform by hooking into native events and endpoints. A Swell App Extension is defined by its ability to respond to core events using functions, or its ability to tap into layers of the platform that serve distinct purposes such as these.

App extensions are configured in swell.json and referenced by functions. This allows you to configure multiple extensions in a single app.

{
  "id": "example_app",
  "type": "integration",
  "extensions": [
    {
      "id": "example",
      "type": "payment",
      "name": "My Payment Service"
    }
  ]
}

Extensions can be enabled when an app is installed, which causes their corresponding functions to be triggered by events. Functions can listen to any valid event, however there are specific events most relevant to extensions, as described later in this document.

New extension types and standard events may be introduced over time. The following extension types are currently available.

Each event described here is considered an "event hook", which means the event is is only called synchronously during the processing of a record. By default, they are called before the event occurs. This differs from regular model events which are called asynchronously by default.

Response properties listed below follow the corresponding standard Swell models.

Payment extensions are for integrating payment gateways, either with 3rd-party services or custom logic.

Payment events:

export const config: SwellConfig = {
  extension: "example",
  description: "Charge a credit card",
  model: {
    events: ["payment.charge"]
  },
};

export default async function (req: SwellRequest) {
  // ... perform charge logic

  return {
    success: true,
    transaction_id: '...',
  }
}

Shipping extensions are for integrating shipment rating and price calculation, either with 3rd-party services or custom logic.

Shipping events:

export const config: SwellConfig = {
  extension: "example",
  description: "Calculate shipping services",
  model: {
    events: ["order.shipping"]
  },
};

export default async function (req: SwellRequest) {
  // ... perform shipping calculation

  return {
    shipment_rating: {
      services: [
        {
          id: '...',
          price: 9.99
        }
      ],
      errors: [...], // optional
    }
  }
}

Tax extensions are for integrating tax calculation, either with 3rd-party services or custom logic.

Tax events:

export const config: SwellConfig = {
  extension: "example",
  description: "Calculate taxes",
  model: {
    events: ["order.taxes"]
  },
};

export default async function (req: SwellRequest) {
  // ... perform tax calculation

  return {
    taxes: [
      {
        id: '...',
        amount: 10
      }
    ],
    items: [ // optional
      {
        id: '...',
        taxes: [...]
      }
    ],
  }
}