> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trolley

> Trolley Scenario seeding parameters, nested fields, and examples

Use `trolley` in `twins` and put this configuration under `seed_config.trolley`.

Trolley payouts and recipient-management platform with recipients and payout accounts, batches and payments, invoices, offline payments, balances, Trust verification, and webhooks.

## Example seed

This is the complete Scenario request body for [creating a Scenario](https://docs.argalabs.com/api-reference/post-create-a-scenario.md). You can also import it with `arga test-runner scenarios import --file scenario.json`.

```json theme={null}
{
  "name": "Trolley eval fixture",
  "twins": [
    "trolley"
  ],
  "seed_config": {
    "trolley": {
      "seed": "scenario-trolley",
      "environment": "sandbox",
      "initial_balances": {
        "USD": "10000.00",
        "CAD": "5000.00",
        "EUR": "2500.00"
      },
      "recipients": [
        {
          "id": "R-scenario-ada",
          "type": "individual",
          "firstName": "Ada",
          "lastName": "Lovelace",
          "email": "ada@example.test",
          "referenceId": "creator-ada",
          "address": {
            "street1": "1 Example Way",
            "city": "Seattle",
            "region": "WA",
            "country": "US"
          },
          "accounts": [
            {
              "recipientAccountId": "A-scenario-ada-usd",
              "type": "bank-transfer",
              "currency": "USD",
              "country": "US",
              "accountHolderName": "Ada Lovelace",
              "accountNum": "000123456789",
              "bankId": "021000021",
              "primary": true
            }
          ]
        }
      ],
      "batches": [
        {
          "id": "B-scenario-august",
          "description": "August creator payouts",
          "currency": "USD",
          "payments": [
            {
              "id": "P-scenario-ada",
              "recipient": {
                "id": "R-scenario-ada"
              },
              "amount": "250.00",
              "currency": "USD",
              "memo": "Creative services"
            }
          ]
        }
      ],
      "invoices": [
        {
          "id": "I-scenario-ada",
          "recipientId": "R-scenario-ada",
          "invoiceNumber": "INV-ADA-001",
          "description": "Creative services",
          "lines": [
            {
              "invoiceLineId": "IL-scenario-ada",
              "description": "Design work",
              "unitAmount": {
                "value": "250.00",
                "currency": "USD"
              }
            }
          ]
        }
      ],
      "subscriptions": [
        {
          "id": "S-scenario-events",
          "target": "https://hooks.example.test/trolley",
          "model": "*",
          "action": "*",
          "status": "active"
        }
      ]
    }
  }
}
```

## Parameters

The following fields belong directly inside `seed_config.trolley`. Required nested fields are marked in their tables. Provider-native objects can contain service-specific fields beyond the representative record shapes below.

| Parameter | Type | Description |
| - | - | - |
| `seed` | `string` | Deterministic seed used by this twin. |
| `environment` | `"sandbox" / "live"` | Environment. |
| `initial_balances` | `map<string, string>` | Initial balances keyed by identifier or resource name. |
| `recipients` | `object[]` | Recipients fixtures in provider-native format. |
| `batches` | `object[]` | Batches fixtures in provider-native format. |
| `invoices` | `object[]` | Invoices fixtures in provider-native format. |
| `subscriptions` | `object[]` | Event subscriptions. |
| `base_time` | `string` | Reference clock for repeatable fixtures. Omit to use the current clock. |
| `signature_window_seconds` | `integer` | Signature window seconds, in seconds. Minimum: 1. Maximum: 300. |
| `auto_deliver_webhooks` | `boolean` | Enable automatic delivery of configured twin webhooks. |
| `rate_limiting_enabled` | `boolean` | Enable request rate limiting. |
| `sandbox_rate_limit_per_minute` | `integer` | Sandbox rate limit per minute. Minimum: 1. |
| `live_rate_limit_per_minute` | `integer` | Live rate limit per minute. Minimum: 1. |
| `ip_rate_limit_per_minute` | `integer` | Ip rate limit per minute. Minimum: 1. |
| `webhook_secret` | `string` | Webhook secret. |
| `merchant_id` | `string` | Merchant id. |
| `merchant_name` | `string` | Merchant name. |
| `default_currency` | `string` | Default currency. |
| `credentials` | `TrolleyCredential[]` | Credentials fixtures in provider-native format. |
| `offline_payments` | `object[]` | Offline payments fixtures in provider-native format. |
| `verifications` | `object[]` | Verifications fixtures in provider-native format. |
| `failure_rules` | `FailureRule[]` | Deterministic failure-injection rules. |

## Resource fields

These tables describe the record shapes used by the example. Keep native field names and casing. Map keys such as property names, IDs, and metadata keys are supplied by your fixture.

### `recipients[]`

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | Explicit resource identifier, when supported. |
| `type` | `string` | Type. |
| `firstName` | `string` | FirstName. |
| `lastName` | `string` | LastName. |
| `email` | `string` | Main account email address. |
| `referenceId` | `string` | ReferenceId. |
| `address` | `object` | Address. |
| `accounts` | `object[]` | Accounts fixtures in provider-native format. |

### `recipients[].accounts[]`

| Parameter | Type | Description |
| - | - | - |
| `recipientAccountId` | `string` | RecipientAccountId. |
| `type` | `string` | Type. |
| `currency` | `string` | Currency. |
| `country` | `string` | Country. |
| `accountHolderName` | `string` | AccountHolderName. |
| `accountNum` | `string` | AccountNum. |
| `bankId` | `string` | BankId. |
| `primary` | `boolean` | Enable or set primary behavior. |

### `batches[]`

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | Explicit resource identifier, when supported. |
| `description` | `string` | Description. |
| `currency` | `string` | Currency. |
| `payments` | `object[]` | Payments fixtures in provider-native format. |

### `batches[].payments[]`

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | Explicit resource identifier, when supported. |
| `recipient` | `object` | Recipient. |
| `amount` | `string` | Amount. |
| `currency` | `string` | Currency. |
| `memo` | `string` | Memo. |

### `invoices[]`

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | Explicit resource identifier, when supported. |
| `recipientId` | `string` | RecipientId. |
| `invoiceNumber` | `string` | InvoiceNumber. |
| `description` | `string` | Description. |
| `lines` | `object[]` | Lines fixtures in provider-native format. |

### `invoices[].lines[]`

| Parameter | Type | Description |
| - | - | - |
| `invoiceLineId` | `string` | InvoiceLineId. |
| `description` | `string` | Description. |
| `unitAmount` | `object` | UnitAmount. |

### `subscriptions[]`

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | Explicit resource identifier, when supported. |
| `target` | `string` | Target. |
| `model` | `string` | Model. |
| `action` | `string` | Action. |
| `status` | `string` | Status. |

## Typed configuration objects

Named object types in the parameter table use these fields.

### FailureRule

| Parameter | Type | Description |
| - | - | - |
| `method` | `string` | Method. |
| `path` | `string` | **Required.** Path. |
| `status_code` | `integer` | Status code. Minimum: 100. Maximum: 599. |
| `code` | `string` | Code. |
| `message` | `string` | Message. |
| `field` | `string or null` | Field. |
| `remaining` | `integer` | Remaining. Minimum: 0. |
| `headers` | `map<string, string>` | Headers keyed by identifier or resource name. |

### TrolleyCredential

| Parameter | Type | Description |
| - | - | - |
| `access_key` | `string` | **Required.** Access key. |
| `secret_key` | `string` | **Required.** Secret key. |
| `environment` | `"sandbox" / "live"` | Environment. |
| `enabled` | `boolean` | Enable or set enabled behavior. |
| `label` | `string` | Label. |

See [Scenario seeding](https://docs.argalabs.com/twins/seeding.md) for saving, provisioning, and resetting fixtures.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.