Subtotal

https://www.subtotal.com/docs
Admin
Subtotal is a retail data connectivity platform that enables shoppers to securely share their retail...
Tokens:15,700
Snippets:95
Trust Score:7.7
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install AI Shopping Assistant Dependencies

Source: https://www.subtotal.com/docs/guides/ai-shopping-assistant

Installs the required npm packages for the AI shopping assistant, including the Subtotal AI Toolkit, OpenAI AI SDK, and react-markdown for rendering messages.

```bash
cd ai-shopping-assistant
npm install @subtotal-inc/ai-toolkit @ai-sdk/openai react-markdown
```

--------------------------------

### Dynamic Link URL Example

Source: https://www.subtotal.com/docs/subtotal-link/dynamic-links

This example shows how to construct a Dynamic Link URL by appending a `connection_token` to the base URL. An optional `redirect_url` can be included as a query parameter.

```url
https://link.subtotal.com/{{connection_token}}?redirect_url=https%3A%2F%2Fexample.com%2Fprofile
```

--------------------------------

### Run AI Shopping Assistant Project

Source: https://www.subtotal.com/docs/guides/ai-shopping-assistant

Starts the development server for the AI shopping assistant project, allowing you to test its functionality locally. This command compiles and serves the Next.js application.

```bash
npm run dev
```

--------------------------------

### GET /purchases

Source: https://www.subtotal.com/docs/api-reference/purchases/get-purchases

Fetches a list of purchases from a connected account. Supports pagination and requires an API key for authentication.

```APIDOC
## GET /purchases

### Description
Get a list of purchases from a connected account.

### Method
GET

### Endpoint
/purchases

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of purchases to return. Default is 10, maximum is 50.
- **starting_after** (string) - Optional - The purchase id of the last purchase you processed. The next purchase returned will be the next oldest purchase.

#### Header Parameters
- **x-api-key** (string) - Required - The client's API key secret value

### Request Example
```yaml
GET /purchases?limit=10&starting_after=01J51S0JYV6N7K1030CV1ZJH30
Headers:
  x-api-key: "YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **has_more** (boolean) - Whether there are more purchases available to fetch
- **purchases** (array) - The list of purchases for the connection sorted in descending order by purchase date
  - **purchase_id** (string) - The unique identifier for the purchase
  - **date** (string) - The date and time of the purchase
  - **total** (string) - The total amount of the purchase

#### Response Example
```json
{
  "has_more": true,
  "purchases": [
    {
      "purchase_id": "01J51S0JYV6N7K1030CV1ZKSJH",
      "date": "2024-01-01T00:00:00Z",
      "total": "9.34"
    }
  ]
}
```

#### Error Response (422)
- **detail** (array) - Validation Error details
  - **loc** (array) - Error location
  - **msg** (string) - Error message
  - **type** (string) - Error type

#### Error Response Example
```json
{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "ensure this value is less than or equal to 50",
      "type": "value_error.number.max"
    }
  ]
}
```
```

--------------------------------

### GET /retailers

Source: https://www.subtotal.com/docs/api-reference/retailers/get-retailers

Retrieves a list of configured retailers. You can optionally fetch all retailers, not just those configured for the client. An API key is required for authentication.

```APIDOC
## GET /retailers

### Description
Retrieves a list of configured retailers. You can optionally fetch all retailers, not just those configured for the client. An API key is required for authentication.

### Method
GET

### Endpoint
/retailers

### Parameters
#### Query Parameters
- **all** (boolean) - Optional - Whether to return all retailers, not just the ones configured for the client. Defaults to false.

#### Header Parameters
- **x-api-key** (string) - Required - The client's API key secret value

### Request Example
```json
{
  "query": {
    "all": true
  },
  "headers": {
    "x-api-key": "YOUR_API_KEY"
  }
}
```

### Response
#### Success Response (200)
- **retailers** (array) - An array of retailer objects, each containing `retailer_id`, `name`, and `images`.
  - **retailer_id** (string) - Identifier for the retailer (e.g., "walmart")
  - **name** (string) - Name of the retailer (e.g., "Walmart")
  - **images** (object) - Logos and icons for the retailer.
    - **logo** (object) - Light and dark mode logos.
      - **light** (string) - URL for the light mode logo.
      - **dark** (string) - URL for the dark mode logo.
    - **icon** (object) - Light and dark mode icons.
      - **light** (string) - URL for the light mode icon.
      - **dark** (string) - URL for the dark mode icon.

#### Response Example (200 OK)
```json
{
  "retailers": [
    {
      "retailer_id": "walmart",
      "name": "Walmart",
      "images": {
        "logo": {
          "light": "https://cdn.subtotal.com/subtotal-link/default.svg",
          "dark": "https://cdn.subtotal.com/subtotal-link/default.svg"
        },
        "icon": {
          "light": "https://cdn.subtotal.com/subtotal-link/default.svg",
          "dark": "https://cdn.subtotal.com/subtotal-link/default.svg"
        }
      }
    }
  ]
}
```

#### Error Response (422 Unprocessable Entity)
- **detail** (array) - An array of validation error objects.
  - **loc** (array) - The location of the error in the request (e.g., `["query", "all"]`).
  - **msg** (string) - The error message.
  - **type** (string) - The type of error (e.g., "value_error.number.not_multiple").

#### Response Example (422 Unprocessable Entity)
```json
{
  "detail": [
    {
      "loc": [
        "query",
        "all"
      ],
      "msg": "value is not a valid boolean",
      "type": "type_error.boolean"
    }
  ]
}
```
```

--------------------------------

### Purchase Created Event Payload Example (JSON)

Source: https://www.subtotal.com/docs/webhooks/webhooks

This JSON object represents the payload structure for the purchase.created event. It includes details about the customer's connection and the specific purchase, such as items, prices, and dates. This data is essential for processing and analyzing customer transactions.

```json
{
  "id": "01J51S0JYV6N7K1030CV1ZBDOW",
  "type": "purchase.created",
  "payload": {
    "connection": {
      "connection_id": "01J51S0JYV6N7K1030CV1ZKSCA",
      "customer_id": "01K8HDK6Y9FXM7ES4NJSHZDEKF",
      "retailer_id": "walmart",
      "email": "jessica@acme.com",
      "mobile": "+123456789",
      "status": "active"
    },
    "purchase": {
      "purchase_id": "01J51S0JYV6N7K1030CV1ZKSJH",
      "date": "2025-10-08T14:23:00Z",
      "total": 47.85,
      "subtotal": 43.50,
      "tax": 4.35,
      "items": [
        {
          "item_id": "01JV7ZDWC9GN1VPR41K3BY08X9",
          "price": 5.99,
          "quantity": 2,
          "product": {
            "product_id": "01J51S0JYV6N7K1030CV1ZKSCA", 
            "name": "Sparkling Water 12pk",
            "description": "Sparkling Water 12-Pack - 12 fl oz bottles",
            "upc": "001234567890",
            "brand": "la-croix"
          }
        },
        {
          "item_id": "01K3KS9Q4522E3HG444E4XH1R0",
          "price": 12.99,
          "quantity": 1,
          "product": {
            "product_id": "01J51S0JYV6N7K1030CV1ZKSCA",
            "name": "Trail Mix",
            "description": "Trail Mix Family Size", 
            "upc": "009876543210",
            "brand": "harvest-one"
          }
        },
        {
          "item_id": "01JV7ZDWC9GN1VPR41K3BY08X9",
          "price": 18.53,
          "quantity": 1,
          "product": {
            "product_id": "01J51S0JYV6N7K1030CV1ZKSCA",
            "name": "Face Cream",
            "description": "Moisturizing Face Cream",
            "upc": "011122233344",
            "brand": "glowww"
          }
        }
      ]
    }
  }
}
```

--------------------------------

### GET /connections/{connection_id}

Source: https://www.subtotal.com/docs/api-reference/connections/get-connection

Retrieves a specific connection using its unique identifier and an API key.

```APIDOC
## GET /connections/{connection_id}

### Description
Retrieves a specific connection using its unique identifier and an API key.

### Method
GET

### Endpoint
`/connections/{connection_id}`

### Parameters
#### Path Parameters
- **connection_id** (string) - Required - A unique identifier for the connection

#### Query Parameters
None

#### Header Parameters
- **x-api-key** (string) - Required - The client's API key secret value

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **connection_id** (string) - A unique identifier for the connection
- **customer_id** (string) - A unique identifier used to map connections to customer records in external systems.
- **retailer_id** (string) - The unique identifier for the retailer in the connection
- **status** (ConnectionStatus) - The status of the connection
- **email** (string | null) - The customer's email address
- **mobile** (string | null) - The customer's mobile phone number

#### Response Example
```json
{
  "connection_id": "01J51S0JYV6N7K1030CV1ZKSCA",
  "customer_id": "8a46e581-48ba-498a-9ad0-2ee72582e1af",
  "retailer_id": "01J7SC0NN73R6F5VVSP3ZKPDA3",
  "status": "active",
  "email": "alice@example.com",
  "mobile": "+1234567890"
}
```

#### Error Response (422)
- **detail** (array) - Contains validation error details.

```json
{
  "detail": [
    {
      "loc": ["query", "connection_id"],
      "msg": "Invalid connection ID format",
      "type": "value_error"
    }
  ]
}
```
```

--------------------------------

### GET /purchases/{purchase_id}

Source: https://www.subtotal.com/docs/api-reference/purchases/get-purchase

Retrieves the details of a specific purchase using its unique identifier.

```APIDOC
## GET /purchases/{purchase_id}

### Description
Get details of an individual purchase.

### Method
GET

### Endpoint
/purchases/{purchase_id}

### Parameters
#### Path Parameters
- **purchase_id** (string) - Required - The unique identifier for the purchase

#### Header Parameters
- **x-api-key** (string) - Required - The client's API key secret value

### Request Example
```json
{
  "example": "Not applicable for GET request"
}
```

### Response
#### Success Response (200)
- **purchase_id** (string) - The unique identifier for the purchase
- **date** (string) - The date and time of the purchase
- **total** (string) - The total amount of the purchase
- **tax** (string) - The tax amount of the purchase
- **subtotal** (string) - The subtotal amount of the purchase
- **item_count** (integer) - The number of items in the purchase
- **items** (array) - The list of items in the purchase

#### Response Example
```json
{
  "purchase_id": "01J51S0JYV6N7K1030CV1ZKSCF",
  "date": "2024-01-01T00:00:00Z",
  "total": "9.34",
  "tax": "0.85",
  "subtotal": "8.49",
  "item_count": 1,
  "items": [
    {
      "item_id": "01J51S0JYV6N7K1030CV1ZKSCA",
      "price": "8.49",
      "quantity": 1,
      "product": {
        "product_id": "01J51S0JYV6N7K1030CV1ZKSCA",
        "brand": "diet-coke",
        "description": "Diet Coke - 12pk/12oz cans",
        "name": "Diet Coke 12pk",
        "upc": "049000028911"
      }
    }
  ]
}
```

#### Error Response (422)
- **detail** (array) - Contains details about the validation error.

#### Error Response Example
```json
{
  "detail": [
    {
      "loc": [
        "path",
        "purchase_id"
      ],
      "msg": "value is not a valid uuid",
      "type": "validation_error"
    }
  ]
}
```
```

--------------------------------

### OpenAPI Specification for Get Retailers

Source: https://www.subtotal.com/docs/api-reference/retailers/get-retailers

This OpenAPI 3.1.0 specification defines the `/retailers` GET endpoint. It details request parameters like 'all' (boolean) to fetch all retailers and 'x-api-key' for authentication, along with the structure of the successful JSON response containing retailer information and error response formats.

```yaml
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /retailers:
    get:
      tags:
        - merchant
      summary: Get Retailers
      description: Get configured retailers
      operationId: get_retailers_retailers_get
      parameters:
        - name: all
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              Whether to return all retailers, not just the ones configured for
              the client
            examples:
              - true
              - false
            default: false
            title: All
          description: >-
            Whether to return all retailers, not just the ones configured for
            the client
        - name: x-api-key
          in: header
          required: true
          schema:
            type: string
            description: The client's API key secret value
            title: X-Api-Key
          description: The client's API key secret value
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRetailersResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    GetRetailersResponse:
      properties:
        retailers:
          items:
            $ref: '#/components/schemas/RetailerResponse'
          type: array
          title: Retailers
          default: []
      type: object
      title: GetRetailersResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RetailerResponse:
      properties:
        retailer_id:
          type: string
          title: Retailer Id
          description: Identifier for the retailer
          examples:
            - walmart
        name:
          type: string
          title: Name
          description: Name of the retailer
          examples:
            - Walmart
        images:
          $ref: '#/components/schemas/ImagesResponse'
          description: Logos and icons for the retailer
          examples:
            - icon:
                dark: https://cdn.subtotal.com/subtotal-link/default.svg
                light: https://cdn.subtotal.com/subtotal-link/default.svg
              logo:
                dark: https://cdn.subtotal.com/subtotal-link/default.svg
                light: https://cdn.subtotal.com/subtotal-link/default.svg
      type: object
      required:
        - retailer_id
        - name
        - images
      title: RetailerResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ImagesResponse:
      properties:
        logo:
          $ref: '#/components/schemas/ImageThemes'
        icon:
          $ref: '#/components/schemas/ImageThemes'
      type: object
      required:
        - logo
        - icon
      title: ImagesResponse
    ImageThemes:
      properties:
        light:
          type: string
          title: Light
        dark:
          type: string
          title: Dark
      type: object
      required:
        - light
        - dark
      title: ImageThemes

```

--------------------------------

### Get Purchase Details

Source: https://www.subtotal.com/docs/api-reference/purchases/get-purchase

Retrieves the details of a specific purchase. This endpoint is useful for displaying purchase history or order status.

```APIDOC
## GET /websites/subtotal

### Description
Get details of an individual purchase.

### Method
GET

### Endpoint
/websites/subtotal

### Parameters
#### Path Parameters
- **purchaseId** (string) - Required - The unique identifier of the purchase to retrieve.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **purchaseId** (string) - The unique identifier of the purchase.
- **items** (array) - A list of items included in the purchase.
- **totalAmount** (number) - The total amount of the purchase.
- **purchaseDate** (string) - The date and time the purchase was made.

#### Response Example
{
  "purchaseId": "pur_12345",
  "items": [
    {
      "itemId": "item_abc",
      "name": "Example Product",
      "quantity": 2,
      "price": 19.99
    }
  ],
  "totalAmount": 39.98,
  "purchaseDate": "2023-10-27T10:00:00Z"
}
```

--------------------------------

### Create Button to Launch Subtotal Link View (Swift)

Source: https://www.subtotal.com/docs/guides/ios-subtotal-link

This Swift code creates a SwiftUI View with a button. Tapping the button presents a navigation destination, which will display the Subtotal Link interface within a WebView. This sets up the initial user interaction to start the account linking flow.

```swift
struct ContentView: View {
    @State private var showWebView = false
    
    var body: some View {
        NavigationStack {
            Button("Link your account") {
                showWebView = true
            }
            .navigationDestination(isPresented: $showWebView) {
                SubtotalLinkView()
            }
        }
    }
}
```

--------------------------------

### Configure Environment Variables for API Keys

Source: https://www.subtotal.com/docs/guides/ai-shopping-assistant

Sets up the necessary API keys for Subtotal and OpenAI by creating a `.env.local` file. This file should contain your specific API keys, which are crucial for authentication and accessing services.

```bash
SUBTOTAL_API_KEY=your_subtotal_api_key
OPENAI_API_KEY=your_openai_api_key
```

--------------------------------

### Create Next.js Project with TypeScript and App Router

Source: https://www.subtotal.com/docs/guides/ai-shopping-assistant

Initializes a new Next.js project configured with TypeScript and the App Router, setting the foundation for the AI shopping assistant application.

```bash
npx create-next-app@latest ai-shopping-assistant --typescript --app
```

--------------------------------

### Fetch Navigation and Other Pages

Source: https://www.subtotal.com/docs/api-reference/purchases/get-purchase

Instructions on how to fetch navigation and other page data using the provided URL.

```APIDOC
## Fetch Navigation and Other Pages

### Description
To find navigation and other pages in this documentation, fetch the `llms.txt` file from the specified URL.

### Endpoint
`https://docs.subtotal.com/llms.txt`

### Method
GET
```

--------------------------------

### Subtotal Link URL - With Query Parameters

Source: https://www.subtotal.com/docs/subtotal-link/link-urls

Demonstrates how to construct a Subtotal Link URL with optional query parameters for customer ID and redirect URL.

```APIDOC
## Subtotal Link URL with Query Parameters

### Description
An example of a complete Link URL including the `customer_id` and `redirect_url` query parameters.

### Method
GET

### Endpoint
`https://link.subtotal.com/tWGE4TJM?customer_id=8a46e581-48ba-498a-9ad0-2ee72582e1af&redirect_url=https%3A%2F%2Fexample.com%2Fprofile`

### Query Parameters
#### Query Parameters
- **customer_id** (string) - Optional - `8a46e581-48ba-498a-9ad0-2ee72582e1af`
- **redirect_url** (string) - Optional - `https%3A%2F%2Fexample.com%2Fprofile`
```

--------------------------------

### POST /connections

Source: https://www.subtotal.com/docs/api-reference/connections/create-connection

Create a new connection for a customer with a specific retailer. This endpoint requires an API key for authentication.

```APIDOC
## POST /connections

### Description
Create a new connection for a customer with a specific retailer.

### Method
POST

### Endpoint
/connections

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - The client's API key secret value

#### Request Body
- **customer_id** (string) - Required - A unique identifier used to map connections to customer records in external systems.
- **retailer_id** (string) - Required - The unique identifier for the retailer in the connection.
- **email** (string or null) - Optional - The customer's email address.
- **mobile** (string or null) - Optional - The customer's mobile phone number

### Request Example
```json
{
  "customer_id": "8a46e581-48ba-498a-9ad0-2ee72582e1af",
  "retailer_id": "walmart",
  "email": "alice@example.com",
  "mobile": "+1234567890"
}
```

### Response
#### Success Response (201)
- **connection_id** (string) - A unique identifier for the connection.
- **customer_id** (string) - A unique identifier used to map connections to customer records in external systems.
- **retailer_id** (string) - The unique identifier for the retailer in the connection.
- **status** (ConnectionStatus) - The status of the connection.
- **email** (string or null) - The customer's email address.
- **mobile** (string or null) - The customer's mobile phone number.

#### Response Example
```json
{
  "connection_id": "01J51S0JYV6N7K1030CV1ZKSCA",
  "customer_id": "8a46e581-48ba-498a-9ad0-2ee72582e1af",
  "retailer_id": "01J7SC0NN73R6F5VVSP3ZKPDA3",
  "status": "active",
  "email": "alice@example.com",
  "mobile": "+1234567890"
}
```

#### Error Response (422)
- **detail** (array) - Contains a list of validation errors.

```json
{
  "detail": [
    {
      "loc": ["body", "customer_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```
```

--------------------------------

### Create a Connection

Source: https://www.subtotal.com/docs/subtotal-link/dynamic-links

Creates a new connection between a customer's retail accounts and your system. A connection ID is returned upon successful creation.

```APIDOC
## POST /connection

### Description
Creates a new connection between a customer's retail accounts and your system. A connection ID is returned upon successful creation.

### Method
POST

### Endpoint
/connection

### Parameters
#### Request Body
- **customer_id** (string) - Required - The ID of the customer.
- **email** (string) - Required - The email address of the customer.
- **mobile** (string) - Required - The mobile number of the customer.
- **retailer_id** (string) - Required - The ID of the retailer.

### Request Example
```json
{
   "customer_id": "8a46e581-48ba-498a-9ad0-2ee72582e1af",
   "email": "alice@example.com",
   "mobile": "+123456789",
   "retailer_id": "instacart"
}
```

### Response
#### Success Response (201 Created)
- **connection_id** (string) - The ID of the created connection.
- **customer_id** (string) - The ID of the customer.
- **email** (string) - The email address of the customer.
- **mobile** (string) - The mobile number of the customer.
- **retailer_id** (string) - The ID of the retailer.
- **status** (string) - The status of the connection (e.g., 'initialized').

#### Response Example
```json
{
  "connection_id": "01J51S0JYV6N7K1030CV1ZKSCA",
  "customer_id": "8a46e581-48ba-498a-9ad0-2ee72582e1af",
  "email": "alice@example.com",
  "mobile": "+1234567890",
  "retailer_id": "instacart",
  "status": "initialized"
}
```
```

--------------------------------

### Integrate Subtotal and OpenAI with Next.js API Route

Source: https://www.subtotal.com/docs/guides/ai-shopping-assistant

Sets up an API route in Next.js (`src/app/api/chat/route.ts`) to handle chat requests. It integrates the Subtotal AI Toolkit and OpenAI's GPT-4o model, processing messages and streaming responses using the Vercel AI SDK.

```ts
import {SubtotalAIToolkit, Tools} from '@subtotal-inc/ai-toolkit/ai-sdk';
import {openai} from '@ai-sdk/openai';
import {streamText} from 'ai';

const subtotalAIToolkit = new SubtotalAIToolkit({
  secretKey: process.env.SUBTOTAL_API_KEY!,
  configuration: {
    tools: [
      Tools.createConnection,
      Tools.createMerchantLinkUrl,
      Tools.getPurchases,
      Tools.getPurchaseDetails,
      Tools.getMerchants,
    ]
  },
});

const model = openai('gpt-4o');

const prompt = {
  role: 'system',
  content: 'Greet the user by responding to their message. ' + 
  'Then create a new connection and generate a url for the user to link their Target account.' + 
  'Indicate that user should click the url and link their account to get started. ' + 
  'Wait for a response from the user indicating they have linked their account. '
}

export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: model,
    tools: {...subtotalAIToolkit.getTools()},
    maxSteps: 4,
    messages: [
      prompt,
      ...messages,
    ],
  });

  return result.toDataStreamResponse();
}

```

--------------------------------

### Create Chat Interface with Next.js and AI SDK

Source: https://www.subtotal.com/docs/guides/ai-shopping-assistant

Implements the client-side chat interface for the AI shopping assistant using Next.js and the Vercel AI SDK. It handles message display, user input, and form submission, utilizing react-markdown for rich message rendering.

```tsx
'use client';

import { useChat } from '@ai-sdk/react';
import ReactMarkdown from 'react-markdown';

const Chat = () => {
  const { messages, input, handleInputChange, handleSubmit } = useChat();

  return (
    <div className='flex flex-col w-full h-screen p-8 pt-24 items-center justify-center bg-black'>
      <div className="flex flex-col w-full max-w-[1000px] h-full justify-between items-center space-y-8">
        <ul className='flex flex-col w-full flex-1 overflow-clip p-4 space-y-4'>
          {messages.map(m => (
            <li key={m.id} className='flex flex-col space-y-2 hover:bg-white/5'>
              <span className='text-sm text-white font-semibold'>{m.role === 'user' ? 'You' : 'Shopping Assistant'}</span>
              <span className='text-white/80 text-sm font-light'><ChatMessage message={m.content} /></span>
            </li>
          ))}
        </ul>
          
        <form className='w-full bg-white/5 border border-white/30 rounded-md shadow' onSubmit={handleSubmit}>
          <input
            className="text-white w-full p-4 placeholder:text-white/80 focus:outline-none"
            value={input}
            placeholder={`${messages.length === 0 ? "Say hi to your new shopping assistant..." : "Ask anything..."}`}
            onChange={handleInputChange}
          />
        </form>
      </div>
    </div>
  );
}

export default Chat;

const ChatMessage = ({ message }: { message: string }) => {
  return (
    <ReactMarkdown
      components={{
        a: ({ node, ...props }) => (
          <a {...props} className="text-blue-500 underline" target="_blank" rel="noopener noreferrer">
            {props.children}
          </a>
        ),
      }}
    >
      {message}
    </ReactMarkdown>
  );
};

```

--------------------------------

### Launch Subtotal Link

Source: https://www.subtotal.com/docs/subtotal-link/dynamic-links

Constructs a fully-formed Dynamic Link by appending the connection token to the base Link URL. A redirect URL can optionally be included.

```APIDOC
## Constructing Dynamic Link URL

### Description
Constructs a fully-formed Dynamic Link by appending the connection token to the base Link URL. A redirect URL can optionally be included.

### Method
GET (Constructed URL)

### Endpoint
`https://link.subtotal.com/{{connection_token}}`

### Parameters
#### Query Parameters
- **redirect_url** (string) - Optional - The URL to redirect the customer to after completing the flow.

### Request Example
```
https://link.subtotal.com/{{connection_token}}?redirect_url=https%3A%2F%2Fexample.com%2Fprofile
```
```

--------------------------------

### Event Types and Payload Structures

Source: https://www.subtotal.com/docs/webhooks/webhooks

Details on supported webhook event types and their corresponding payload structures.

```APIDOC
## Event Types

### connection.activated

*Description:* Connections are `activated` when a customer successfully links their account.

*Payload Structure:*

*   **payload.connection.connection_id** (string) - Identifier for the connection.
*   **payload.connection.customer_id** (string) - Identifier for the associated customer.
*   **payload.connection.email** (string) - Email address of the associated customer.
*   **payload.connection.mobile** (string) - Mobile phone number of the associated customer.
*   **payload.connection.status** (string) - Current status of the connection.
*   **payload.connection.retailer_id** (string) - Identifier for the retailer in the connection.

### connection.unauthenticated

*Description:* Connections move from `activated` to `unauthenticated` when a customer needs to re-authenticate their account (e.g., when a customer changes their password with the retailer).

*Payload Structure:*

*   **payload.connection.connection_id** (string) - Identifier for the connection.
*   **payload.connection.customer_id** (string) - Identifier for the associated customer.
*   **payload.connection.email** (string) - Email address of the associated customer.
*   **payload.connection.mobile** (string) - Mobile phone number of the associated customer.
*   **payload.connection.status** (string) - Current status of the connection.
*   **payload.connection.retailer_id** (string) - Identifier for the retailer in the connection.
```

--------------------------------

### API Key Authentication Header

Source: https://www.subtotal.com/docs/api-reference/introduction

This snippet demonstrates how to include the API key in the request headers for authentication. Ensure you replace '{yourkeyvalue}' with your actual API key.

```json
{
  "X-Api-Key": "{yourkeyvalue}"
}
```

--------------------------------

### ItemProduct Schema

Source: https://www.subtotal.com/docs/api-reference/purchases/get-purchase

Defines the structure for product information, including required fields and data types.

```APIDOC
## ItemProduct Schema

### Description
Represents a product with details such as ID, brand, description, name, and UPC.

### Object Structure
- **product_id** (string) - Required - Unique identifier for the product.
- **brand** (string | null) - Optional - The brand of the product. Example: `diet-coke`.
- **description** (string) - Required - The description of the product. Example: `Diet Coke - 12pk/12oz cans`.
- **name** (string) - Required - The name of the product. Example: `Diet Coke 12pk`.
- **upc** (string | null) - Optional - The universal identifier for the product (UPC). Example: `049000028911`. This field is read-only.
```

--------------------------------

### Create Connection Response Body

Source: https://www.subtotal.com/docs/subtotal-link/dynamic-links

This JSON object represents a successful response after creating a new connection. It includes the unique `connection_id` and other details about the initialized connection.

```json
{
  "connection_id": "01J51S0JYV6N7K1030CV1ZKSCA",
  "customer_id": "8a46e581-48ba-498a-9ad0-2ee72582e1af",
  "email": "alice@example.com",
  "mobile": "+1234567890"
  "retailer_id": "instacart",
  "status": "initialized"
}
```

--------------------------------

### Implement WKWebView for Subtotal Link (Swift)

Source: https://www.subtotal.com/docs/guides/ios-subtotal-link

This Swift code defines a `UIViewRepresentable` struct to create and configure a `WKWebView` for displaying Subtotal Link. It sets necessary configurations like `allowsInlineMediaPlayback` and a custom user agent, then loads the provided Subtotal Link URL. This view is responsible for rendering the entire account linking process.

```swift
import SwiftUI
import WebKit

struct SubtotalLinkView: View {
    var body: some View {
        SubtotalWebView()
    }
}

struct SubtotalWebView: UIViewRepresentable {
    func makeUIView(context: Context) -> WKWebView {
        let webConfiguration = WKWebViewConfiguration()
        webConfiguration.allowsInlineMediaPlayback = true
        webConfiguration.applicationNameForUserAgent = "Subtotal Custom WebView User Agent"
        
        let webView = WKWebView(frame: .zero, configuration: webConfiguration)
        
        // Copy and paste a Link URL from the Subtotal Dashboard
        let linkURL = "https://link.subtotal.com/tWGE4TJM"
        if let url = URL(string: linkURL) {
            webView.load(URLRequest(url: url))
        }
        
        return webView
    }
    
    func updateUIView(_ webView: WKWebView, context: Context) {
        // Required by UIViewRepresentable protocol - URL is already loaded in makeUIView
    }
}
```

--------------------------------

### Create Connection Request Body

Source: https://www.subtotal.com/docs/subtotal-link/dynamic-links

This JSON object represents the request body for creating a new connection. It includes customer identifiers and the retailer ID. Ensure all required fields are present before sending the request.

```json
{
   "customer_id": "8a46e581-48ba-498a-9ad0-2ee72582e1af",
   "email": "alice@example.com",
   "mobile": "+123456789"
   "retailer_id": "instacart"
}
```

--------------------------------

### Create Connection Token API Endpoint (OpenAPI)

Source: https://www.subtotal.com/docs/api-reference/connections/create-connection-token

This OpenAPI specification defines the POST /connections/{connection_id}/token endpoint for requesting a new connection token. It requires a connection ID and an x-api-key in the header, and accepts a CreateTokenRequest body containing a scope. Successful responses return a ConnectionTokenResponse with the token, while validation errors return HTTPValidationError.

```yaml
post /connections/{connection_id}/token
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /connections/{connection_id}/token:
    post:
      tags:
        - connection
      summary: Create Connection Token
      description: Request a new connection token
      operationId: create_connection_token_connections__connection_id__token_post
      parameters:
        - name: connection_id
          in: path
          required: true
          schema:
            type: string
            description: A unique identifier for the connection
            title: Connection Id
          description: A unique identifier for the connection
        - name: x-api-key
          in: header
          required: true
          schema:
            type: string
            description: The client's API key secret value
            title: X-Api-Key
          description: The client's API key secret value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTokenRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionTokenResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreateTokenRequest:
      properties:
        scope:
          $ref: '#/components/schemas/TokenScope'
          description: The intended scope of the token to be generated
          examples:
            - link
      type: object
      required:
        - scope
      title: CreateTokenRequest
    ConnectionTokenResponse:
      properties:
        connection_token:
          type: string
          title: Connection Token
          description: The generated connection token
          examples:
            - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
      type: object
      required:
        - connection_token
      title: ConnectionTokenResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TokenScope:
      type: string
      enum:
        - link
        - access
      title: TokenScope
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

```

--------------------------------

### Subtotal Link URL - Overview

Source: https://www.subtotal.com/docs/subtotal-link/link-urls

Subtotal Link provides dedicated URLs for launching a browser-based linking experience, offering flexibility for brands and developers.

```APIDOC
## Subtotal Link URL

### Description
Dedicated URLs for launching Subtotal Link, a browser-based experience for linking customer accounts. Each retailer has a unique Link URL.

### Method
GET

### Endpoint
`https://link.subtotal.com/YOUR_RETAILER_ID`

### Query Parameters
#### Query Parameters
- **customer_id** (string) - Optional - A unique identifier to map connections to customer records across external systems.
- **redirect_url** (string) - Optional - The URL to redirect customers to after successfully linking their account.
```

--------------------------------

### POST /connections/{connection_id}/token

Source: https://www.subtotal.com/docs/api-reference/connections/create-connection-token

Request a new connection token for a specified connection ID.

```APIDOC
## POST /connections/{connection_id}/token

### Description
Request a new connection token.

### Method
POST

### Endpoint
/connections/{connection_id}/token

### Parameters
#### Path Parameters
- **connection_id** (string) - Required - A unique identifier for the connection

#### Header Parameters
- **x-api-key** (string) - Required - The client's API key secret value

#### Request Body
- **scope** (string) - Required - The intended scope of the token to be generated (e.g., "link")

### Request Example
```json
{
  "scope": "link"
}
```

### Response
#### Success Response (201)
- **connection_token** (string) - The generated connection token

#### Response Example
```json
{
  "connection_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

#### Error Response (422)
- **detail** (array) - Validation error details
```

--------------------------------

### HTTPBearer Authentication

Source: https://www.subtotal.com/docs/api-reference/purchases/get-purchase

Describes the HTTP Bearer authentication scheme used for securing API connections.

```APIDOC
## HTTPBearer Authentication

### Description
A connection-specific token with access scope is required for authentication. This is typically provided in the `Authorization` header as a Bearer token.
```

--------------------------------

### Connection Token Authorization Header

Source: https://www.subtotal.com/docs/api-reference/introduction

This snippet shows how to include a connection token in the Authorization header for endpoints requiring specific user permissions. Replace '{connection_token}' with the actual token.

```json
{
  "Authorization": "Bearer: {connection_token}"
}
```

--------------------------------

### Webhooks Signature Verification

Source: https://www.subtotal.com/docs/webhooks/webhooks

Information on how to verify the authenticity of incoming webhook requests using provided headers and a shared secret.

```APIDOC
## Verifying Webhook Signatures

To verify the authenticity of each webhook request, use the following headers and steps:

### Headers

*   **X-Subtotal-Signature** (string): HMAC of the payload using your shared secret.
*   **X-Subtotal-Timestamp** (string): The timestamp of the webhook request.

### Step 1: Prepare the `signed_payload` string

Concatenate the timestamp (as a string), a '.' character, and the request body (as a string).

### Step 2: Compute the `expected_signature`

Compute the `expected_signature` using the HMAC-SHA256 hash function. Use your webhook destination's `signing_secret` as the key and the `signed_payload` string as the message.

*Note: The `signing_secret` is obtained when creating a new webhook destination in the Subtotal Dashboard.*

### Step 3: Compare the signatures

Compare the `expected_signature` to the `X-Subtotal-Signature` header. To prevent replay attacks, compare the received timestamp against the current time and reject requests outside your tolerance window. Use a constant-time string comparison to protect against timing attacks.

### Properties included with every webhook request

*   **type** (string): The webhook event type.
*   **id** (string): Identifier for the webhook.
*   **payload** (string): The payload of the webhook.
```

--------------------------------

### Subtotal API - Authentication

Source: https://www.subtotal.com/docs/api-reference/introduction

All requests to the Subtotal API must include an API key for authentication. This is done by adding the 'X-Api-Key' header to your request.

```APIDOC
## Authentication

All requests must include an API key for authentication.

Include the following header in each request:

```json
{
  "X-Api-Key": "{yourkeyvalue}"
}
```
```

--------------------------------

### Subtotal API - Base URL

Source: https://www.subtotal.com/docs/api-reference/introduction

The base URL for all Subtotal API requests. Endpoints should be appended to this root address to form complete request URLs.

```APIDOC
## Base URL

Append an endpoint to the base URL root address to form a complete request URL.

```
https://api.subtotal.com
```
```
Tokens:
Raw