> ## Documentation Index > Fetch the complete documentation index at: https://docs.subtotal.com/llms.txt > Use this file to discover all available pages before exploring further. # Simulate Connection > Create an active simulated test connection, as the dashboard's event simulator does, to test your webhook or integration. Emits `connection.activated` to your webhooks, marked `is_simulated`; starter purchases are backdated history and emit nothing (simulate a purchase to send `purchase.created`). Simulated connections never collect real purchases. [Subtotal Connector tool: simulate\_connection](/docs/connector/tools.md#simulate_connection) Creates an active simulated connection to a retailer, as the dashboard's [Event Simulator](/docs/event-simulator.md) does, and sends `connection.activated` to webhook destinations that [accept simulated events](/docs/event-simulator.md#configure-simulated-events-for-your-webhook-destination). The connection is marked `is_simulated: true` and never collects real purchases. Every call creates a new connection. By default it also gets 1 to 4 simulated purchases, dated in the last 60 days as history. They don't send `purchase.created`. Set `include_purchases` to `false` to skip them, and use [Simulate a purchase](/docs/api-reference/simulated-connections/simulate-purchase.md) to send that event. Simulated connections appear in [List connections](/docs/api-reference/connections/get-connections.md) and [Get a connection](/docs/api-reference/connections/get-connection.md), marked `is_simulated`. An unknown `retailer_id` returns `422`. Call it with your API key, or with a [Subtotal Connector](/docs/connector/introduction.md) OAuth token that includes `simulator:write`. A token without it receives `403 insufficient_scope`. [Partner app](/docs/partner-apps/introduction.md#fixed-permissions) tokens don't include it. ## OpenAPI ````yaml post /simulated-connections openapi: 3.1.0 info: title: FastAPI version: 0.1.0 servers: [] security: [] paths: /simulated-connections: post: tags: - simulator summary: Simulate Connection description: >- Create an active simulated test connection, as the dashboard's event simulator does, to test your webhook or integration. Emits `connection.activated` to your webhooks, marked `is_simulated`; starter purchases are backdated history and emit nothing (simulate a purchase to send `purchase.created`). Simulated connections never collect real purchases. operationId: simulate_connection_simulated_connections_post parameters: - name: authorization in: header required: false schema: anyOf: - type: string - type: 'null' title: Authorization - name: x-api-key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SimulateConnectionRequest' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ConnectionResponse' '422': description: Unknown retailer_id components: schemas: SimulateConnectionRequest: properties: retailer_id: type: string minLength: 1 title: Retailer Id description: The retailer to simulate a link to examples: - walmart customer_id: anyOf: - type: string maxLength: 64 - type: 'null' title: Customer Id description: Your identifier for the test customer; generated when omitted examples: - test-customer-1 email: anyOf: - type: string maxLength: 254 - type: 'null' title: Email description: The test customer's email examples: - test@example.com mobile: anyOf: - type: string maxLength: 16 - type: 'null' title: Mobile description: The test customer's mobile examples: - '+15555550100' include_purchases: type: boolean title: Include Purchases description: >- Also create 1–4 simulated purchases of random retailer products, dated in the last 60 days as history; they emit no events default: true type: object required: - retailer_id title: SimulateConnectionRequest description: The public `POST /simulated-connections` body. ConnectionResponse: properties: connection_id: type: string title: Connection Id description: A unique identifier for the connection examples: - 01J51S0JYV6N7K1030CV1ZKSCA customer_id: type: string title: Customer Id description: >- A unique identifier used to map connections to customer records in external systems. examples: - 8a46e581-48ba-498a-9ad0-2ee72582e1af retailer_id: type: string title: Retailer Id description: The unique identifier for the retailer in the connection examples: - 01J7SC0NN73R6F5VVSP3ZKPDA3 status: $ref: '#/components/schemas/ConnectionStatusResponse' description: The status of the connection examples: - active email: anyOf: - type: string - type: 'null' title: Email description: The customer's email address examples: - alice@example.com mobile: anyOf: - type: string - type: 'null' title: Mobile description: The customer's mobile phone number examples: - '+1234567890' creation_date: type: string format: date-time title: Creation Date description: When the connection was created examples: - '2024-08-13T17:27:57.913Z' tags: additionalProperties: type: string type: object title: Tags description: >- Client-defined attribution tags recorded when the connection is created, for grouping connection metrics — e.g. {"campaign": "summer_sweeps", "program": "loyalty"}. Names and values are opaque to Subtotal and are never interpreted. At most 10 tags; names up to 64 characters, values up to 256. Intended for campaign and source metadata — do not put consumer PII in tags. examples: - campaign: summer_sweeps is_simulated: type: boolean title: Is Simulated description: >- True for a test connection made with the event simulator. Its events are marked is_simulated too, and it never collects real purchases. default: false examples: - false type: object required: - connection_id - customer_id - retailer_id - status - email - mobile - creation_date title: ConnectionResponse ConnectionStatusResponse: type: string enum: - active - initialized - unauthenticated - disconnected title: ConnectionStatusResponse description: >- Connection status enum for API responses (excludes revoked status). NOTE: This should mirror the ConnectionStatus enum the database, excluding internal statuses like (REVOKED) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.