npm package: @flowglad/fgp-openclaw
Description: OpenClaw plugin for Flowglad Pay — agent tools for purchasing, credentials, and job management
Latest version: 0.2.0

# @flowglad/fgp-openclaw

OpenClaw plugin for [Flowglad Pay](https://flowgladpay.com) — gives AI agents the ability to purchase products, sign up for services, and manage jobs, credentials, payment methods, and shipping addresses.

## Prerequisites

- An [OpenClaw](https://openclaw.ai) instance (self-hosted or cloud)
- A [Flowglad Pay](https://flowgladpay.com) account with an API key
- Node.js >= 18

## Getting Your API Key

1. Sign in to the [Flowglad Pay dashboard](https://app.flowgladpay.com)
2. Navigate to **Settings > API Keys**
3. Create a new key — it will start with `pk_`
4. Copy it for the plugin configuration below

## Installation

Install the plugin via npm:

```bash
npm install @flowglad/fgp-openclaw
```

Then add it to your OpenClaw configuration file (`openclaw.json` or equivalent). The array form registers the plugin with default settings, while the object form lets you provide configuration inline:

```json
{
  "plugins": {
    "@flowglad/fgp-openclaw": {
      "apiKey": "pk_your_api_key_here"
    }
  }
}
```

## Configuration

The plugin requires an API key and accepts an optional custom endpoint.

### Via the OpenClaw Control UI

When configuring through the UI, the **API Key** field is marked as sensitive and will be masked. The **API Endpoint** field defaults to `https://app.flowgladpay.com/api` and only needs to be changed for self-hosted deployments.

### Config reference

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `apiKey` | `string` | Yes | — | Flowglad Pay API key (`pk_...`) |
| `endpoint` | `string` | No | `https://app.flowgladpay.com/api` | API base URL. Override for self-hosted or local dev (`http://localhost:3001/api`). |

## Agent Tools

Once installed, the following tools are available to any OpenClaw agent with access to this plugin.

### Purchasing

#### `flowglad_buy`

Submit a purchase job to Flowglad Pay. An autonomous agent will visit the URL, add items to cart, and complete checkout using a virtual payment card. Streams events until the job completes (or returns immediately with `noWait`). For complex orders (signups, multi-item, fallback options), use `flowglad_order` instead.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `url` | `string` | Yes | — | URL of the product to purchase |
| `maxSpend` | `number` | No | `1500` | Maximum spend in cents ($15) |
| `paymentMethodId` | `string` | No | default | Payment method to charge |
| `shippingAddressId` | `string` | No | — | Shipping address for physical goods |
| `noWait` | `boolean` | No | `false` | Return immediately after submission |

**Example agent prompt:** *"Buy the Pro plan at https://example.com/pricing"*

**Returns (wait mode):**
```json
{
  "jobId": "job_abc123",
  "status": "completed",
  "result": {
    "success": true,
    "productObtained": "Pro Plan",
    "credentials": "cred_xyz"
  },
  "events": [
    { "type": "job_started", "message": "Agent navigating to vendor" },
    { "type": "done", "message": "Job completed" }
  ]
}
```

#### `flowglad_order`

Submit a structured BuyNode order to Flowglad Pay for complex purchases (multiple items, fallback options, signups).

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `order` | `object` | Yes | — | BuyNode order tree (see below) |
| `maxSpend` | `number` | No | `1500` | Maximum spend in cents |
| `paymentMethodId` | `string` | No | default | Payment method to charge |
| `shippingAddressId` | `string` | No | — | Shipping address |
| `noWait` | `boolean` | No | `false` | Return immediately |

**BuyNode types:**

| Kind | Fields | Description |
|------|--------|-------------|
| `item` | `url`, `label?`, `constraints?` | Purchase a single product |
| `signup` | `url`, `label?` | Sign up for a service |
| `goal` | `url`, `intent`, `label?` | Achieve a freeform goal on a site |
| `one-of` | `options: BuyNode[]` | Try options in order, use first success |
| `all-of` | `items: BuyNode[]` | Complete all items |

**Example order:**
```json
{
  "kind": "all-of",
  "items": [
    { "kind": "signup", "url": "https://example.com/signup" },
    { "kind": "item", "url": "https://example.com/pricing", "constraints": [{ "kind": "max-price", "cents": 2000 }] }
  ]
}
```

### Job Management

#### `flowglad_list_jobs`

List recent purchase jobs. Returns job ID, status, vendor, and timestamps. Use `status` to filter. Default limit is 20.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | `number` | No | Maximum number of jobs to return |
| `status` | `string` | No | Filter: `created`, `retry`, `active`, `completed`, `failed`, `cancelled` |

#### `flowglad_get_job`

Get full details for a specific job including status, result, and agent steps. Check `result.success` and `result.credentials` (credential ID if account was created).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `jobId` | `string` | Yes | Job ID to look up |

#### `flowglad_get_job_events`

Get high-level business events for a job (e.g. "navigated to checkout", "payment submitted"). Human-readable milestones. Useful for giving the user a progress summary.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `jobId` | `string` | Yes | Job ID |

#### `flowglad_cancel_job`

Cancel a running job. Only works on jobs with status `created`, `retry`, or `active`.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `jobId` | `string` | Yes | Job ID to cancel |

### Credentials

#### `flowglad_list_credentials`

List all stored credentials (account logins created by the agent during signup jobs). Returns credential IDs and metadata. Use `flowglad_get_credential` to retrieve actual username/password.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `vendor` | `string` | No | Filter by vendor name |

#### `flowglad_get_credential`

Retrieve a stored credential (username, password, etc.) created by the agent during a signup job. The credential ID is available in the completed job's `result.credentials` field.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `credentialId` | `string` | Yes | Credential ID |

### Payment Methods

#### `flowglad_list_payment_methods`

List the payment methods (virtual cards) registered on the account. Use the ID when submitting a job. No parameters.

#### `flowglad_get_payment_method`

Get details for a specific payment method by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `paymentMethodId` | `string` | Yes | Payment method ID |

### Shipping Addresses

#### `flowglad_list_shipping_addresses`

List the shipping addresses registered on the account. Use the ID as `shippingAddressId` when submitting a job. No parameters.

#### `flowglad_get_shipping_address`

Get details for a specific shipping address by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `shippingAddressId` | `string` | Yes | Shipping address ID |

## Agent Tool Access Control

To restrict which tools an agent can use, configure allowlists/denylists in your OpenClaw agent config:

```json
{
  "agents": {
    "list": [
      {
        "name": "purchasing-agent",
        "tools": {
          "allow": ["flowglad_buy", "flowglad_list_jobs", "flowglad_get_job"]
        }
      }
    ]
  }
}
```

## Error Handling

When the Flowglad Pay API returns an error, the response typically includes `error` and `status` fields:

```json
{
  "error": "Job not found",
  "status": 404
}
```

Network errors or unexpected failures may surface as unstructured error messages. Common API error codes:

| Status | Meaning |
|--------|---------|
| `401` | Invalid or missing API key |
| `404` | Resource not found |
| `422` | Validation error (e.g. invalid URL, missing required field) |
| `429` | Rate limited — retry after backoff |

## Local Development

To test against a local Flowglad Pay instance:

```json
{
  "plugins": {
    "@flowglad/fgp-openclaw": {
      "apiKey": "pk_devkey_local_testing_only_not_for_production",
      "endpoint": "http://localhost:3001/api"
    }
  }
}
```

See the [Flowglad Pay docs](https://docs.flowgladpay.com) for instructions on running the server locally.