# Authentication
Source: https://docs.tolt.com/authentication

How to authenticate with the Tolt API

The Tolt API uses Bearer authentication. For all API requests, you need to include your API key in the `Authorization` header using the Bearer scheme.

```bash theme={"system"}
'Authorization': 'Bearer <API_KEY>'
```

## API Keys

API keys can be found and created in the [Settings -> Integrations](https://app.tolt.io/settings?tab=integrations) tab of your Tolt dashboard.

### Example Request

```bash theme={"system"}
curl -X GET 'https://api.tolt.com/v1/links' \
-H 'Authorization: Bearer tlt_live_3eYx5GATWpBpW1bJXw4ZD9'
```

### Security

* Keep your API keys secure and never share them publicly
* API keys carry many privileges, so be sure to keep them secure
* Do not commit API keys to your source code
* Do not share API keys in client-side code
* Rotate your API keys periodically

### Permissions

Each API key has full access to all API endpoints. We recommend creating separate API keys for different applications or services to make it easier to manage and rotate keys when needed.


# Create Click
Source: https://docs.tolt.com/clicks/create

POST https://api.tolt.com/v1/clicks
This endpoint creates a click. You can create a click either by providing partner and link IDs or by using a tracking parameter and value.

## Base URL `https://api.tolt.com`

<br />

### Body Parameters

You can create a click using one of these two methods:

#### Method 1: Using Partner and Link IDs

<ParamField type="string">
  The ID of the partner who generated the click
</ParamField>

<ParamField type="string - optional">
  The ID of the link that was clicked
</ParamField>

#### Method 2: Using Tracking Parameter

<ParamField type="string">
  The tracking parameter name (e.g., 'ref', 'via')
</ParamField>

<ParamField type="string">
  The value of the tracking parameter
</ParamField>

#### Common Optional Parameters

<ParamField type="string - optional">
  Two-letter ISO country code where the click originated
</ParamField>

<ParamField type="string - optional">
  Device type that generated the click (e.g., 'desktop', 'mobile', 'tablet')
</ParamField>

<ParamField type="string - optional">
  URL of the page where the click occurred
</ParamField>

<ParamField type="string - optional">
  URL of the referring page
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the click, `uuid` or prefixed with `clk_`
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the partner who generated the click
    </ResponseField>

    <ResponseField name="link_id" type="string">
      ID of the link that was clicked
    </ResponseField>

    <ResponseField name="country" type="string">
      Two-letter ISO country code
    </ResponseField>

    <ResponseField name="state" type="string | null">
      State
    </ResponseField>

    <ResponseField name="device" type="string">
      Device type
    </ResponseField>

    <ResponseField name="page" type="string">
      Page URL
    </ResponseField>

    <ResponseField name="browser" type="string | null">
      Browser name
    </ResponseField>

    <ResponseField name="referrer" type="string">
      Referrer URL
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the click belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Method 1: Partner ID theme={"system"}
  curl -X POST 'https://api.tolt.com/v1/clicks' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
      "link_id": "lnk_dK9bzRGn46BhVgNFHD6fDgXW",
      "country": "US",
      "device": "desktop",
      "page": "https://example.com/product",
      "referrer": "https://google.com"
  }'
  ```

  ```bash Method 2: Tracking Parameter theme={"system"}
  curl -X POST 'https://api.tolt.com/v1/clicks' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "param": "ref",
      "value": "michael_scott",
      "country": "US",
      "device": "mobile",
      "page": "https://example.com/product",
      "referrer": "https://twitter.com"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response - Method 1 theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "clk_dK9bzRGn46BhVgNFHD6fDgXW",
        "page": "https://example.com/product",
        "referrer": "https://google.com",
        "device": "desktop",
        "browser": null,
        "country": "US",
        "state": null,
        "link_id": "lnk_dK9bzRGn46BhVgNFHD6fDgXW",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2"
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "created_at": "2025-04-25T11:22:35.546Z",
        "updated_at": "2025-04-25T11:22:35.546Z"
      }
    ]
  }
  ```

  ```json Response - Method 2 theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "clk_dK9bzRGn46BhVgNFHD6fDgXW",
        "page": "https://example.com/product",
        "referrer": "https://google.com",
        "device": "desktop",
        "browser": null,
        "country": "US",
        "state": null,
        "link_id": "lnk_dK9bzRGn46BhVgNFHD6fDgXW",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "created_at": "2025-04-25T11:22:35.546Z",
        "updated_at": "2025-04-25T11:22:35.546Z"
      }
    ]
  }
  ```
</ResponseExample>


# Create Commission
Source: https://docs.tolt.com/commissions/create

POST https://api.tolt.com/v1/commissions
This endpoint creates a commission.

## Base URL `https://api.tolt.com`

<br />

### Body Parameters

<ParamField type="number">
  The commission amount in cents
</ParamField>

<ParamField type="string | null - optional">
  The ID of the customer associated with this commission. Omit this field or set it to `null` to create a commission without a customer.
</ParamField>

<ParamField type="string - optional">
  Program ID for the commission. Required when `customer_id` is omitted or `null`.
</ParamField>

<ParamField type="string - optional">
  Partner ID for the commission. Required when `customer_id` is omitted or `null`.
</ParamField>

<ParamField type="string - optional">
  Associated transaction identifier
</ParamField>

<ParamField type="string - optional">
  Associated charge identifier
</ParamField>

<ParamField type="string - optional">
  Source of the commission
</ParamField>

<ParamField type="string - optional">
  Commission status. Valid values are: 'pending', 'approved', 'paid',
  'rejected', 'refunded'
</ParamField>

<ParamField type="number - optional">
  The revenue amount in cents
</ParamField>

<ParamField type="string - optional">
  ISO 8601 timestamp of when the commission was created
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array[object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the commission
    </ResponseField>

    <ResponseField name="amount" type="number">
      Commission amount in cents
    </ResponseField>

    <ResponseField name="customer_id" type="string | null">
      ID of the associated customer, or null for customerless commissions
    </ResponseField>

    <ResponseField name="transaction_id" type="string">
      Associated transaction identifier
    </ResponseField>

    <ResponseField name="charge_id" type="string | null">
      Associated charge identifier
    </ResponseField>

    <ResponseField name="charge_status" type="string | null">
      Status of the related charge (e.g. "paid", "failed")
    </ResponseField>

    <ResponseField name="source" type="string | null">
      Source of the commission
    </ResponseField>

    <ResponseField name="status" type="string | null">
      Commission status
    </ResponseField>

    <ResponseField name="type" type="string | null">
      Type of commission (e.g. "reward", "referral")
    </ResponseField>

    <ResponseField name="currency" type="string | null">
      Currency of the commission (ISO currency code) or null if not set
    </ResponseField>

    <ResponseField name="revenue" type="number | null">
      Revenue amount in cents
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of update
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the partner who earned the commission
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the commission belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>

    <ResponseField name="payout_id" type="string | null">
      ID of the payout if the commission has been paid, otherwise null
    </ResponseField>

    <ResponseField name="scheduled_approval_date" type="string | null">
      Scheduled approval date if applicable, otherwise null
    </ResponseField>

    <ResponseField name="approval_type" type="string | null">
      Approval type for the commission (e.g. "immediate", "manual")
    </ResponseField>

    <ResponseField name="flow_id" type="string | null">
      ID of the flow that generated the commission
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST 'https://api.tolt.com/v1/commissions' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "amount": 1999,
      "customer_id": null,
      "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
      "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
      "transaction_id": "txn_7mbzRGn46BhVgNFHD6fDgXW",
      "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
      "source": "stripe",
      "status": "pending",
      "revenue": 9999,
      "created_at": "2025-01-15T14:30:00.000Z"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "comm_eK9bzRGn46BhVgNFHD6fDgXW",
        "revenue": null,
        "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
        "charge_status": null,
        "source": "stripe",
        "status": "pending",
        "type": null,
        "currency": null,
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
        "transaction_id": "txn_7mbzRGn46BhVgNFHD6fDgXW",
        "customer_id": null,
        "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "payout_id": null,
        "created_at": "2025-01-15T14:30:00.000Z",
        "updated_at": "2025-01-15T14:30:00.000Z",
        "amount": "1999",
        "scheduled_approval_date": null,
        "approval_type": "manual",
        "flow_id": null
      }
    ]
  }
  ```
</ResponseExample>


# Delete Commission
Source: https://docs.tolt.com/commissions/delete

DELETE https://api.tolt.com/v1/commissions/:id
This endpoint deletes a commission.

## Base URL `https://api.tolt.com`

<br />

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the deleted commission
    </ResponseField>

    <ResponseField name="deleted" type="boolean">
      Indicates that the commission was deleted
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X DELETE 'https://api.tolt.com/v1/commissions/comm_eK9bzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": {
      "id": "comm_eK9bzRGn46BhVgNFHD6fDgXW",
      "deleted": true
    }
  }
  ```
</ResponseExample>


# List Commissions
Source: https://docs.tolt.com/commissions/list

GET https://api.tolt.com/v1/commissions
This endpoint lists all commissions.

## Base URL `https://api.tolt.com`

<br />

### Query Parameters

<ParamField type="string">
  The program ID from where you want to list the commissions
</ParamField>

<ParamField type="string - optional">
  Only return commissions from this partner
</ParamField>

<ParamField type="string - optional">
  Only return commissions for this customer
</ParamField>

<ParamField type="string - optional">
  Only return commissions for this transaction
</ParamField>

<ParamField type="asc | desc - optional">
  The order of the commissions to return by created\_at. Default is desc
</ParamField>

<ParamField type="array - optional">
  Specify which related objects to include in the response. Valid values are
  **'partner'**, **'program'**, **'customer'**, and **'transaction'**. Use
  **expand\[]=partner**, **expand\[]=program**, **expand\[]=customer**, or
  **expand\[]=transaction** to include the related objects.
</ParamField>

<ParamField type="string - optional">
  Only return commissions created after this date
</ParamField>

<ParamField type="string - optional">
  Only return commissions created before this date
</ParamField>

<ParamField type="string - optional">
  A limit on the number of commissions to return. Default is 10, max is 100
</ParamField>

<ParamField type="string - optional">
  A cursor for use in pagination. starting\_after is an object ID that defines
  your place in the list
</ParamField>

<ParamField type="string - optional">
  A cursor for use in pagination. ending\_before is an object ID that defines
  your place in the list
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether there are more pages of results available
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of commissions matching the query
</ResponseField>

<ResponseField name="data" type="array[Object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the commission
    </ResponseField>

    <ResponseField name="amount" type="number">
      Commission amount in cents
    </ResponseField>

    <ResponseField name="customer_id" type="string">
      ID of the associated customer
    </ResponseField>

    <ResponseField name="transaction_id" type="string">
      Associated transaction identifier
    </ResponseField>

    <ResponseField name="charge_id" type="string">
      Associated charge identifier
    </ResponseField>

    <ResponseField name="source" type="string">
      Source of the commission
    </ResponseField>

    <ResponseField name="status" type="string">
      Commission status
    </ResponseField>

    <ResponseField name="revenue" type="number">
      Revenue amount in cents
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of update
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the commission belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/commissions?program_id=prg_YRsbPDAKhWfdqJbFACheh' \
  -H 'Authorization: Bearer <API_KEY>'
  ```

  ```bash With Expand theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/commissions?program_id=prg_YRsbPDAKhWfdqJbFACheh&expand[]=partner&expand[]=program&expand[]=customer&expand[]=transaction' \
  -H 'Authorization: Bearer <API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "has_more": true,
    "total_count": 45,
    "data": [
      {
        "id": "comm_eK9bzRGn46BhVgNFHD6fDgXW",
        "amount": 1999,
        "customer_id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
        "transaction_id": "txn_7mbzRGn46BhVgNFHD6fDgXW",
        "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
        "source": "stripe",
        "status": "pending",
        "revenue": 9999,
        "created_at": "2025-01-15T14:30:00.000Z",
        "updated_at": "2025-01-15T14:30:00.000Z",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2"
      }
    ]
  }
  ```

  ```json Expand Response theme={"system"}
  {
    "success": true,
    "has_more": true,
    "total_count": 45,
    "data": [
      {
        "id": "comm_eK9bzRGn46BhVgNFHD6fDgXW",
        "amount": 1999,
        "customer_id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
        "transaction_id": "txn_7mbzRGn46BhVgNFHD6fDgXW",
        "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
        "source": "stripe",
        "status": "pending",
        "revenue": 9999,
        "created_at": "2025-01-15T14:30:00.000Z",
        "updated_at": "2025-01-15T14:30:00.000Z",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
        "partner": {
          "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
          "first_name": "Michael",
          "last_name": "Scott",
          "email": "michael.scott@dundermifflin.com",
          "company_name": "Dunder Mifflin",
          "status": "active",
          "created_at": "2025-01-13T10:06:11.251Z"
        },
        "program": {
          "id": "prg_YRsbPDAKhWfdqJbFACheh",
          "status": "active",
          "name": "Tolt's Partnership Program",
          "product_name": "Tolt",
          "subdomain": "affiliates",
          "type": "public",
          "currency_code": "USD",
          "created_at": "2024-03-05T10:28:08.984+00:00"
        },
        "customer": {
          "id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
          "email": "cust_123",
          "name": "Jim Halpert",
          "status": "active",
          "created_at": "2025-01-15T14:30:00.000Z"
        },
        "transaction": {
          "id": "txn_7mbzRGn46BhVgNFHD6fDgXW",
          "amount": 9999,
          "status": "completed",
          "created_at": "2025-01-15T14:30:00.000Z"
        }
      }
    ]
  }
  ```
</ResponseExample>


# Retrieve Commission
Source: https://docs.tolt.com/commissions/retrieve

GET https://api.tolt.com/v1/commissions/:id
This endpoint retrieves a commission.

## Base URL `https://api.tolt.com`

<br />

### Query Parameters

<ParamField type="array - optional">
  Specify which related objects to include in the response. Valid values are
  **'partner'**, **'program'**, and **'customer'**. Use **expand\[]=partner**,
  **expand\[]=program**, or **expand\[]=customer** to include the related objects.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the commission
    </ResponseField>

    <ResponseField name="amount" type="number">
      Commission amount in cents
    </ResponseField>

    <ResponseField name="customer_id" type="string">
      ID of the associated customer
    </ResponseField>

    <ResponseField name="transaction_id" type="string">
      Associated transaction identifier
    </ResponseField>

    <ResponseField name="charge_id" type="string">
      Associated charge identifier
    </ResponseField>

    <ResponseField name="source" type="string">
      Source of the commission
    </ResponseField>

    <ResponseField name="status" type="string">
      Commission status
    </ResponseField>

    <ResponseField name="revenue" type="number">
      Revenue amount in cents
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of update
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the commission belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/commissions/comm_eK9bzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>'
  ```

  ```bash With Expand theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/commissions/comm_eK9bzRGn46BhVgNFHD6fDgXW?expand[]=partner&expand[]=program&expand[]=customer' \
  -H 'Authorization: Bearer <API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": {
      "id": "comm_eK9bzRGn46BhVgNFHD6fDgXW",
      "amount": 1999,
      "customer_id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
      "transaction_id": "txn_7mbzRGn46BhVgNFHD6fDgXW",
      "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
      "source": "stripe",
      "status": "pending",
      "revenue": 9999,
      "created_at": "2025-01-15T14:30:00.000Z",
      "updated_at": "2025-01-15T14:30:00.000Z",
      "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
      "organization_id": "org_JE3mfYNL9ci7sFaJazAv2"
    }
  }
  ```

  ```json Expand Response theme={"system"}
  {
    "success": true,
    "data": {
      "id": "comm_eK9bzRGn46BhVgNFHD6fDgXW",
      "amount": 1999,
      "customer_id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
      "transaction_id": "txn_7mbzRGn46BhVgNFHD6fDgXW",
      "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
      "source": "stripe",
      "status": "pending",
      "revenue": 9999,
      "created_at": "2025-01-15T14:30:00.000Z",
      "updated_at": "2025-01-15T14:30:00.000Z",
      "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
      "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
      "partner": {
        "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "first_name": "Michael",
        "last_name": "Scott",
        "email": "michael.scott@dundermifflin.com",
        "company_name": "Dunder Mifflin",
        "status": "active",
        "created_at": "2025-01-13T10:06:11.251Z"
      },
      "program": {
        "id": "prg_YRsbPDAKhWfdqJbFACheh",
        "status": "active",
        "name": "Tolt's Partnership Program",
        "product_name": "Tolt",
        "subdomain": "affiliates",
        "type": "public",
        "currency_code": "USD",
        "created_at": "2024-03-05T10:28:08.984+00:00"
      },
      "customer": {
        "id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
        "email": "cust_123",
        "name": "Jim Halpert",
        "status": "active",
        "created_at": "2025-01-15T14:30:00.000Z"
      }
    }
  }
  ```
</ResponseExample>


# Update Commission
Source: https://docs.tolt.com/commissions/update

PUT https://api.tolt.com/v1/commissions/:id
This endpoint updates a commission.

## Base URL `https://api.tolt.com`

<br />

### Body Parameters

<ParamField type="number - optional">
  The commission amount in cents
</ParamField>

<ParamField type="string - optional">
  Associated transaction identifier
</ParamField>

<ParamField type="string - optional">
  Associated charge identifier
</ParamField>

<ParamField type="string - optional">
  Source of the commission
</ParamField>

<ParamField type="string - optional">
  Commission status. Valid values are: 'pending', 'approved', 'paid',
  'rejected', 'refunded'
</ParamField>

<ParamField type="number - optional">
  The revenue amount in cents
</ParamField>

<ParamField type="string - optional">
  ISO 8601 timestamp of when the commission was created
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array[object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the commission
    </ResponseField>

    <ResponseField name="amount" type="number">
      Commission amount in cents
    </ResponseField>

    <ResponseField name="customer_id" type="string">
      ID of the associated customer
    </ResponseField>

    <ResponseField name="transaction_id" type="string">
      Associated transaction identifier
    </ResponseField>

    <ResponseField name="charge_id" type="string">
      Associated charge identifier
    </ResponseField>

    <ResponseField name="charge_status" type="string">
      Status of the related charge (e.g. "paid", "failed")
    </ResponseField>

    <ResponseField name="source" type="string">
      Source of the commission
    </ResponseField>

    <ResponseField name="status" type="string">
      Commission status
    </ResponseField>

    <ResponseField name="type" type="string">
      Type of commission (e.g. "reward", "referral")
    </ResponseField>

    <ResponseField name="currency" type="string | null">
      Currency of the commission (ISO currency code) or null if not set
    </ResponseField>

    <ResponseField name="revenue" type="number">
      Revenue amount in cents
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of update
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the partner who earned the commission
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the commission belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>

    <ResponseField name="payout_id" type="string | null">
      ID of the payout if the commission has been paid, otherwise null
    </ResponseField>

    <ResponseField name="scheduled_approval_date" type="string | null">
      Scheduled approval date if applicable, otherwise null
    </ResponseField>

    <ResponseField name="approval_type" type="string">
      Approval type for the commission (e.g. "immediate", "manual")
    </ResponseField>

    <ResponseField name="flow_id" type="string">
      ID of the flow that generated the commission
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X PUT 'https://api.tolt.com/v1/commissions/comm_eK9bzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "amount": 2999,
      "status": "approved",
      "revenue": 14999
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "comm_eK9bzRGn46BhVgNFHD6fDgXW",
        "revenue": "14999",
        "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
        "charge_status": "paid",
        "source": "manual",
        "status": "approved",
        "type": "reward",
        "currency": null,
        "partner_id": "part_JE3mfL9dfdffci7sFaJazAv2",
        "organization_id": "org_JEsdfL9dfci7sFaJazAv2",
        "program_id": "prg_YRdddbPDAKhWfdqhJbeh",
        "transaction_id": "txn_7m46BhVkjkgNFHD6fDgXW",
        "customer_id": "cust_d6BhVgNFHD6fDgkjkjXW",
        "payout_id": null,
        "created_at": "2025-04-25T09:36:10.858Z",
        "updated_at": "2025-04-25T09:36:10.858Z",
        "amount": "2999",
        "scheduled_approval_date": null,
        "approval_type": "immediate",
        "flow_id": "flw_FX567GZjkn7RtaKbEuFatWw"
      }
    ]
  }
  ```
</ResponseExample>


# Create Customer
Source: https://docs.tolt.com/customers/create

POST https://api.tolt.com/v1/customers
This endpoint creates a customer.

## Base URL `https://api.tolt.com`

<br />

### Body Parameters

<ParamField type="string">
  Customer's email address
</ParamField>

<ParamField type="string">
  The partner ID who referred this customer
</ParamField>

<ParamField type="string - optional">
  Customer's name
</ParamField>

<ParamField type="string - optional">
  Associated subscription identifier
</ParamField>

<ParamField type="string - optional">
  Your internal customer identifier
</ParamField>

<ParamField type="string - optional">
  Tracking click identifier
</ParamField>

<ParamField type="string - optional">
  Promotion code used to attribute this customer. The code must belong to the
  referring partner, their group, or their program. If it does not match, the
  customer is still created using click or API attribution, and the response
  includes a `warnings` array with a `promotion_code_not_applied` entry.
</ParamField>

<ParamField type="string - optional">
  ISO 8601 timestamp of when the customer was created
</ParamField>

<ParamField type="string - optional">
  ISO 8601 timestamp of when the customer became a lead
</ParamField>

<ParamField type="string - optional">
  ISO 8601 timestamp of when the customer became active
</ParamField>

<ParamField type="string - optional">
  Customer's status. Valid values are: 'lead', 'trialing', 'active', 'canceled'
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array[object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the customer, `uuid` or prefixed with `cust_`
    </ResponseField>

    <ResponseField name="email" type="string">
      Your unique identifier for the customer
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the referring partner
    </ResponseField>

    <ResponseField name="name" type="string">
      Customer's name
    </ResponseField>

    <ResponseField name="subscription_id" type="string">
      Associated subscription identifier
    </ResponseField>

    <ResponseField name="identifier" type="string">
      Customer identifier
    </ResponseField>

    <ResponseField name="customer_id" type="string">
      Your internal customer identifier
    </ResponseField>

    <ResponseField name="click_id" type="string">
      Tracking click identifier
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="lead_at" type="string">
      ISO 8601 timestamp of lead conversion
    </ResponseField>

    <ResponseField name="active_at" type="string">
      ISO 8601 timestamp of activation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of updated customer
    </ResponseField>

    <ResponseField name="status" type="string">
      Customer's current status
    </ResponseField>

    <ResponseField name="plan" type="string | null">
      Plan the customer subscribed to
    </ResponseField>

    <ResponseField name="promotion_code_id" type="string | null">
      Identifier for a promotoinal code used by the customer
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the customer belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST 'https://api.tolt.com/v1/customers' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "email": "cust_123",
      "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
      "name": "Jim Halpert",
      "subscription_id": "sub_456",
      "customer_id": "jim_halpert_789",
      "click_id": "click_abc",
      "promotion_code": "PARTNER20",
      "status": "active",
      "active_at": "2025-01-15T14:30:00.000Z"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
        "customer_id": "jim_halpert_789",
        "identifier": "james@tolt.com",
        "email": "james@tolt.com",
        "name": "Jim Halpert",
        "status": "active",
        "plan": null,
        "subscription_id": "sub_456",
        "lead_at": "2025-04-25T11:00:00.797Z",
        "active_at": "2025-01-15T14:30:00.000Z",
        "click_id": "click_abc",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
        "created_at": "2025-04-25T11:00:00.800Z",
        "updated_at": "2025-04-25T11:00:00.800Z",
        "promotion_code_id": "promo_abc"
      }
    ]
  }
  ```
</ResponseExample>


# Delete Customer
Source: https://docs.tolt.com/customers/delete

DELETE https://api.tolt.com/v1/customers/:id
This endpoint deletes a customer.

## Base URL `https://api.tolt.com`

<br />

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the deleted customer, `uuid` or prefixed with
      `cust_`
    </ResponseField>

    <ResponseField name="deleted" type="boolean">
      Indicates that the customer was deleted
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X DELETE 'https://api.tolt.com/v1/customers/cust_dK9bzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": {
      "id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
      "deleted": true
    }
  }
  ```
</ResponseExample>


# List Customers
Source: https://docs.tolt.com/customers/list

GET https://api.tolt.com/v1/customers
This endpoint lists all customers.

## Base URL `https://api.tolt.com`

<br />

### Query Parameters

<ParamField type="string">
  The program ID from where you want to list the customers.
</ParamField>

<ParamField type="string - optional">
  Only return customers referred by this partner.
</ParamField>

<ParamField type="string - optional">
  Filter customers by email. Partial matches are supported.
</ParamField>

<ParamField type="asc | desc - optional">
  The order of the customers to return by created\_at. Default is desc.
</ParamField>

<ParamField type="string - optional">
  Filter customers by status. Valid values are: 'lead', 'trialing', 'active',
  'canceled'
</ParamField>

<ParamField type="array - optional">
  Specify which related objects to include in the response. Valid values are
  **'partner'** and **'program'**. Use **expand\[]=partner** or
  **expand\[]=program** to include the related objects.
</ParamField>

<ParamField type="string - optional">
  Only return customers created after this date.
</ParamField>

<ParamField type="string - optional">
  Only return customers created before this date.
</ParamField>

<ParamField type="string - optional">
  A limit on the number of customers to return. Default is 10, max is 100.
</ParamField>

<ParamField type="string - optional">
  A cursor for use in pagination. starting\_after is an object ID that defines
  your place in the list. The value of the starting\_after parameter is the
  customer ID. To receive the next page use the last customer ID from the
  previous page.
</ParamField>

<ParamField type="string - optional">
  A cursor for use in pagination. ending\_before is an object ID that defines
  your place in the list. The value of the ending\_before parameter is the
  customer ID. To receive the previous page use the first customer ID from the
  previous page.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether there are more pages of results available
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of customers matching the query
</ResponseField>

<ResponseField name="data" type="object{object}">
  <Expandable title="properties">
    <ResponseField name="data" type="array[object]">
      <Expandable title="properties">
        <ResponseField name="id" type="string">
          Unique identifier for the customer, `uuid` or prefixed with `cust_`
        </ResponseField>

        <ResponseField name="email" type="string">
          Your unique identifier for the customer
        </ResponseField>

        <ResponseField name="partner_id" type="string">
          ID of the referring partner
        </ResponseField>

        <ResponseField name="name" type="string">
          Customer's name
        </ResponseField>

        <ResponseField name="customer_id" type="string">
          Your internal customer identifier
        </ResponseField>

        <ResponseField name="created_at" type="string">
          ISO 8601 timestamp of when the customer was created
        </ResponseField>

        <ResponseField name="updated_at" type="string">
          ISO 8601 timestamp of when the customer became active
        </ResponseField>

        <ResponseField name="status" type="string">
          Current status of the customer. Valid values are: 'lead', 'trialing', 'active',
          'canceled'
        </ResponseField>

        <ResponseField name="program_id" type="string">
          Program ID the customer belongs to
        </ResponseField>

        <ResponseField name="organization_id" type="string">
          Organization ID
        </ResponseField>

        <ResponseField name="partner" type="object">
          <Expandable title="partner">
            Partner details when expanded:

            <ResponseField name="id" type="string">
              Unique identifier for the partner
            </ResponseField>

            <ResponseField name="first_name" type="string">
              Partner's first name
            </ResponseField>

            <ResponseField name="last_name" type="string">
              Partner's last name
            </ResponseField>

            <ResponseField name="email" type="string">
              Partner's email address
            </ResponseField>

            <ResponseField name="company_name" type="string">
              Partner's company name
            </ResponseField>

            <ResponseField name="status" type="string">
              Partner's status. Valid values are: 'active', 'pending', 'suspended', 'rejected'.
            </ResponseField>

            <ResponseField name="created_at" type="string">
              ISO 8601 timestamp of when the partner was created
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="program" type="object">
          <Expandable title="program">
            Program details when expanded:

            <ResponseField name="id" type="string">
              Unique identifier for the program
            </ResponseField>

            <ResponseField name="status" type="string">
              Program status
            </ResponseField>

            <ResponseField name="name" type="string">
              Program name
            </ResponseField>

            <ResponseField name="product_name" type="string">
              Name of the product
            </ResponseField>

            <ResponseField name="subdomain" type="string">
              Program's subdomain
            </ResponseField>

            <ResponseField name="type" type="string">
              Program type
            </ResponseField>

            <ResponseField name="currency_code" type="string">
              Three-letter ISO currency code
            </ResponseField>

            <ResponseField name="created_at" type="string">
              ISO 8601 timestamp of when the program was created
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/customers?program_id=prg_YRsbPDAKhWfdqJbFACheh' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```

  ```bash cURL - Expand theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/customers?program_id=prg_YRsbPDAKhWfdqJbFACheh&expand[]=partner&expand[]=program' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "has_more": true,
    "total_count": 85,
    "data": {
      "data": [
        {
          "id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
          "email": "customer@example.com",
          "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
          "name": "Jim Halpert",
          "customer_id": "jim_halpert_789",
          "created_at": "2025-01-15T14:30:00.000Z",
          "updated_at": "2025-01-15T14:30:00.000Z",
          "status": "active",
          "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
          "organization_id": "org_JE3mfYNL9ci7sFaJazAv2"
        }
      ]
    }
  }
  ```

  ```json Expand Response theme={"system"}
  {
    "success": true,
    "has_more": true,
    "total_count": 85,
    "data": {
      "data": [
        {
          "id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
          "email": "customer@example.com",
          "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
          "name": "Jim Halpert",
          "customer_id": "jim_halpert_789",
          "created_at": "2025-01-15T14:30:00.000Z",
          "updated_at": "2025-01-15T15:00:00.000Z",
          "status": "active",
          "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
          "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
          "partner": {
            "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
            "first_name": "Michael",
            "last_name": "Scott",
            "email": "michael.scott@dundermifflin.com",
            "company_name": "Dunder Mifflin",
            "status": "active",
            "created_at": "2025-01-13T10:06:11.251Z"
          },
          "program": {
            "id": "prg_YRsbPDAKhWfdqJbFACheh",
            "status": "active",
            "name": "Tolt's Partnership Program",
            "product_name": "Tolt",
            "subdomain": "affiliates",
            "type": "public",
            "currency_code": "USD",
            "created_at": "2024-03-05T10:28:08.984+00:00"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Retrieve Customer
Source: https://docs.tolt.com/customers/retrieve

GET https://api.tolt.com/v1/customers/:id
This endpoint retrieves a customer.

## Base URL `https://api.tolt.com`

<br />

### Query Parameters

<ParamField type="array - optional">
  Specify which related objects to include in the response. Valid values are
  **'partner'** and **'program'**. Use **expand\[]=partner** or
  **expand\[]=program** to include the related objects.
</ParamField>

<ParamField type="array - optional">
  Specify which related objects to include in the response. Valid values are
  **'stats'**. Use **include\[]=stats** to include the related objects.
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique identifier for the customer, `uuid` or prefixed with `cust_`
</ResponseField>

<ResponseField name="email" type="string">
  Your unique identifier for the customer
</ResponseField>

<ResponseField name="partner_id" type="string">
  ID of the referring partner
</ResponseField>

<ResponseField name="name" type="string">
  Customer's name
</ResponseField>

<ResponseField name="customer_id" type="string">
  Your internal customer identifier
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the customer was created
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of when the customer became active
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the customer (e.g., 'lead', 'trialing', 'active',
  'canceled')
</ResponseField>

<ResponseField name="program_id" type="string">
  Program ID the customer belongs to
</ResponseField>

<ResponseField name="organization_id" type="string">
  Organization ID
</ResponseField>

<ResponseField name="partner" type="object">
  <Expandable title="partner">
    Partner details when expanded:

    <ResponseField name="id" type="string">
      Unique identifier for the partner
    </ResponseField>

    <ResponseField name="first_name" type="string">
      Partner's first name
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Partner's last name
    </ResponseField>

    <ResponseField name="email" type="string">
      Partner's email address
    </ResponseField>

    <ResponseField name="company_name" type="string">
      Partner's company name
    </ResponseField>

    <ResponseField name="status" type="string">
      Partner's status. Valid values are: 'active', 'pending', 'suspended',
      'rejected'.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the partner was created
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="program" type="object">
  <Expandable title="program">
    Program details when expanded:

    <ResponseField name="id" type="string">
      Unique identifier for the program
    </ResponseField>

    <ResponseField name="status" type="string">
      Program status
    </ResponseField>

    <ResponseField name="name" type="string">
      Program name
    </ResponseField>

    <ResponseField name="product_name" type="string">
      Name of the product
    </ResponseField>

    <ResponseField name="subdomain" type="string">
      Program's subdomain
    </ResponseField>

    <ResponseField name="type" type="string">
      Program type (e.g., 'public')
    </ResponseField>

    <ResponseField name="currency_code" type="string">
      Three-letter ISO currency code
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the program was created
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="stats" type="object">
  <Expandable title="stats">
    An object containing the customer's statistics:

    <ResponseField name="total_revenue" type="integer">
      Total revenue generated in cents
    </ResponseField>

    <ResponseField name="total_commission" type="integer">
      Total commission generated in cents
    </ResponseField>

    <ResponseField name="total_orders" type="integer">
      Total number of orders
    </ResponseField>

    <ResponseField name="last_order_at" type="string">
      ISO 8601 timestamp of the last order
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/customers/cust_dK9bzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```

  ```bash cURL - Expand & Include theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/customers/cust_dK9bzRGn46BhVgNFHD6fDgXW?expand[]=partner&expand[]=program&include[]=stats' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": {
      "id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
      "email": "customer@email.com",
      "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
      "name": "Jim Halpert",
      "customer_id": "jim_halpert_789",
      "created_at": "2025-01-15T14:30:00.000Z",
      "updated_at": "2025-01-15T15:00:00.000Z",
      "status": "active",
      "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
      "organization_id": "org_JE3mfYNL9ci7sFaJazAv2"
    }
  }
  ```

  ```json Expand & Include Response theme={"system"}
  {
    "success": true,
    "data": {
      "id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
      "email": "customer@email.com",
      "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
      "name": "Jim Halpert",
      "customer_id": "jim_halpert_789",
      "created_at": "2025-01-15T14:30:00.000Z",
      "updated_at": "2025-01-15T15:00:00.000Z",
      "status": "active",
      "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
      "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
      "partner": {
        "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "first_name": "Michael",
        "last_name": "Scott",
        "email": "michael.scott@dundermifflin.com",
        "company_name": "Dunder Mifflin",
        "status": "active",
        "created_at": "2025-01-13T10:06:11.251Z"
      },
      "program": {
        "id": "prg_YRsbPDAKhWfdqJbFACheh",
        "status": "active",
        "name": "Tolt's Partnership Program",
        "product_name": "Tolt",
        "subdomain": "affiliates",
        "type": "public",
        "currency_code": "USD",
        "created_at": "2024-03-05T10:28:08.984+00:00"
      },
      "stats": {
        "total_revenue": 99900,
        "total_commission": 19980,
        "total_orders": 3,
        "last_order_at": "2025-01-20T09:15:32.000Z"
      }
    }
  }
  ```
</ResponseExample>


# Update Customer
Source: https://docs.tolt.com/customers/update

PUT https://api.tolt.com/v1/customers/:id
This endpoint updates a customer.

## Base URL `https://api.tolt.com`

<br />

### Body Parameters

<ParamField type="string - optional">
  Customer's email address
</ParamField>

<ParamField type="string - optional">
  Customer's name
</ParamField>

<ParamField type="string - optional">
  Associated subscription identifier
</ParamField>

<ParamField type="string - optional">
  Your internal customer identifier
</ParamField>

<ParamField type="string - optional">
  Tracking click identifier
</ParamField>

<ParamField type="string - optional">
  Promotion code used to attribute this customer. The code must belong to the
  customer's partner, their group, or their program. If it does not match, the
  customer's existing attribution is left unchanged, and the response includes a
  `warnings` array with a `promotion_code_not_applied` entry.
</ParamField>

<ParamField type="string - optional">
  ISO 8601 timestamp of when the customer was created
</ParamField>

<ParamField type="string - optional">
  ISO 8601 timestamp of when the customer became a lead
</ParamField>

<ParamField type="string - optional">
  ISO 8601 timestamp of when the customer became active
</ParamField>

<ParamField type="string - optional">
  Customer's status. Valid values are: 'lead', 'trialing', 'active', 'canceled'
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array[Object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the customer, `uuid` or prefixed with `cust_`
    </ResponseField>

    <ResponseField name="email" type="string">
      Your unique identifier for the customer
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the referring partner
    </ResponseField>

    <ResponseField name="name" type="string">
      Customer's name
    </ResponseField>

    <ResponseField name="subscription_id" type="string">
      Associated subscription identifier
    </ResponseField>

    <ResponseField name="identifier" type="string">
      Customer identifier
    </ResponseField>

    <ResponseField name="customer_id" type="string">
      Your internal customer identifier
    </ResponseField>

    <ResponseField name="click_id" type="string">
      Tracking click identifier
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="lead_at" type="string">
      ISO 8601 timestamp of lead conversion
    </ResponseField>

    <ResponseField name="active_at" type="string">
      ISO 8601 timestamp of activation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of updated customer
    </ResponseField>

    <ResponseField name="status" type="string">
      Customer's current status
    </ResponseField>

    <ResponseField name="plan" type="string | null">
      Plan the customer subscribed to
    </ResponseField>

    <ResponseField name="promotion_code_id" type="string | null">
      Identifier for a promotoinal code used by the customer
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the customer belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X PUT 'https://api.tolt.com/v1/customers/cust_dK9bzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "James Halpert",
      "status": "active",
      "subscription_id": "sub_789",
      "promotion_code": "PARTNER20",
      "active_at": "2025-01-15T15:00:00.000Z"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
        "customer_id": "jim_halpert_789",
        "identifier": "james@tolt.com",
        "email": "james@tolt.com",
        "name": "Jim Halpert",
        "status": "active",
        "plan": null,
        "subscription_id": "sub_456",
        "lead_at": "2025-04-25T11:00:00.797Z",
        "active_at": "2025-01-15T14:30:00.000Z",
        "click_id": "click_abc",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
        "created_at": "2025-04-25T11:00:00.800Z",
        "updated_at": "2025-04-25T11:00:00.800Z",
        "promotion_code_id": "promo_abc"
      }
    ]
  }
  ```
</ResponseExample>


# Track with tolt.js
Source: https://docs.tolt.com/guides/with-toltjs

Track partner clicks, leads, and payments using the tolt.js script

## Installation

First, add the tolt.js script to the head of your website/app:

<Tabs>
  <Tab title="Default">
    ```html theme={"system"}
    <script
      src="https://cdn.tolt.io/tolt.js"
      data-tolt="YOUR_PUBLIC_ORG_KEY"
    ></script>
    ```
  </Tab>

  <Tab title="Alternative">
    ```javascript theme={"system"}
    <script>
      var toltScript = document.createElement('script'); 
      toltScript.src = 'https://cdn.tolt.io/tolt.js'; 
      toltScript.setAttribute('data-tolt', 'YOUR_PUBLIC_ORG_KEY'); 
      document.head.appendChild(toltScript);
    </script>
    ```
  </Tab>
</Tabs>

## Tracking Flow

### 1. Click Tracking

The tolt.js script automatically tracks visitors that come through partner links:

* When a visitor arrives through a partner link, tolt.js creates a click
* The click data is accessible through `window.tolt_data`:

```javascript theme={"system"}
{
  click_id: "30aa8b8d-b846-4827-bd6f-6beb16466841",
  cookie_duration: 30,
  partner_id: "f468da94-f786-485c-9314-3008ce472188",
  program_id: "prg_YRsbPDAKhWAdqJbFACheh",
  customer_id: null  // Will be set after signup
}
```

### 2. Lead Tracking

When a visitor signs up, convert them to a lead using the signup function:

```javascript theme={"system"}
const result = await window.tolt.signup("user@example.com");
// Returns signup data including customer_id
```

After signup, store the `customer_id` and `partner_id` from `window.tolt_data` in your database. You'll need these to track future payments for this customer.

### 3. Payment Tracking

When the customer makes a payment, call the [create a transaction](/transactions/create) API:

```bash theme={"system"}
curl -X POST 'https://api.tolt.com/v1/transactions' \
-H 'Authorization: Bearer <API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "amount": 9999,
    "customer_id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
    "billing_type": "subscription",
    "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
    "product_name": "Premium Plan",
    "source": "stripe",
    "interval": "month"
}'
```

When a transaction is created, Tolt automatically:

1. Identifies the associated partner through the customer\_id
2. Triggers the programs commission flows
3. The flows will create a commission record for the partner if the conditions are met

This completes the tracking cycle from initial click through to paid commission.


# Track without tolt.js
Source: https://docs.tolt.com/guides/without-toltjs

Track affiliate clicks, leads, and payments using direct API calls

## Tracking Flow

### 1. Click Tracking

When a visitor arrives through a partner link (e.g., `yourdomain.com?ref=partner123`), call the [create a click](/clicks/create) API:

```bash theme={"system"}
curl -X POST 'https://api.tolt.com/v1/clicks' \
-H 'Authorization: Bearer <API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "param": "ref",
    "value": "partner123",
    "page": "https://yourdomain.com/product",
    "device": "desktop"
}'
```

If the param & value combination doesn't exist in your program, the API will return an error:

```json theme={"system"}
{
  "success": false,
  "error": "Link not found"
}
```

On success, store the returned `partner_id` - you'll need it to create the customer later.

### 2. Lead Tracking

When the visitor signs up, [create a customer](/customers/create) using the stored `partner_id`:

```bash theme={"system"}
curl -X POST 'https://api.tolt.com/v1/customers' \
-H 'Authorization: Bearer <API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "email": "user@example.com",
    "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
    "customer_id": "your_internal_user_id"
}'
```

Store the returned `customer_id` alongside your user data - you'll need it for tracking payments.

### 3. Payment Tracking

When the customer makes a payment, [create a transaction](/transactions/create) using the stored `customer_id`:

```bash theme={"system"}
curl -X POST 'https://api.tolt.com/v1/transactions' \
-H 'Authorization: Bearer <API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "amount": 9999,
    "customer_id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
    "billing_type": "subscription",
    "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
    "product_name": "Premium Plan",
    "source": "stripe",
    "interval": "month"
}'
```

When a transaction is created, Tolt automatically:

1. Identifies the associated partner through the customer\_id
2. Triggers the programs commission flows
3. The flows will create a commission record for the partner if the conditions are met

This completes the tracking cycle from initial click through to paid commission.


# Introduction
Source: https://docs.tolt.com/introduction

Welcome to the Tolt API documentation

<Note>
  We are actively working on improving our APIs and adding new endpoints and
  options. Please reach out to us if you have any feedback or suggestions via
  live chat in the bottom right corner of the page or via email at
  [support@tolt.io](mailto:support@tolt.io).
</Note>

## Overview

Welcome to Tolt's API documentation. Our API enables you to programmatically manage your partnership program, including partners, commissions, transactions, and more. The API follows RESTful principles and uses standard HTTP methods.

## Base URL

All API requests should be made to:

```bash theme={"system"}
https://api.tolt.com
```

## Authentication

All API endpoints require authentication using Bearer token authentication. Include your API key in the Authorization header:

```bash theme={"system"}
Authorization: Bearer <API_KEY>
```

You can find your API key in the [Settings -> Integrations](https://app.tolt.io/settings?tab=integrations) tab.

## Response Format

All responses are returned in JSON format and include a `success` boolean indicating if the request was successful.

### Successful Response Example

```json theme={"system"}
{
  "success": true,
  "data": {
    "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
    "first_name": "Michael",
    "last_name": "Scott"
    // ... other fields
  }
}
```

### Error Response Example

```json theme={"system"}
{
  "success": false,
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error"
  }
}
```

## Common Parameters

Many endpoints support these common query parameters:

* `limit`: Number of records to return (default: 10, max: 100)
* `starting_after`: Cursor for pagination (forward)
* `ending_before`: Cursor for pagination (backward)
* `expand`: Include related objects in the response

## Available Resources

The Tolt API provides access to the following resources:

* **Partners**: Manage your partners and their information
* **Links**: Create and manage tracking links
* **Commissions**: Track and manage commission payouts
* **Transactions**: View and manage transactions
* **Promotion Codes**: Create and manage promotional codes

## API Versioning

The current version is `v1`. We maintain backwards compatibility within a version and will notify you of any upcoming changes.

## Need Help?

If you need assistance:

* Email us at [support@tolt.io](mailto:support@tolt.io)
* Check our [API Status Page](https://status.tolt.io)

## Next Steps

* [Authentication Guide](/api-reference/authentication)
* [Rate Limits](/api-reference/rate-limits)
* [Partners API Reference](/api-reference/partners/create)


# Overview
Source: https://docs.tolt.com/javascript/overview

The tolt.js script is a JavaScript library that automatically tracks partner clicks and can convert them into leads on your website/app

## Installation

Add the tolt.js script to the head of your website/app:

<Tabs>
  <Tab title="Default">
    ```html theme={"system"}
    <script
      src="https://cdn.tolt.io/tolt.js"
      data-tolt="YOUR_PUBLIC_ORG_KEY"
    ></script>
    ```
  </Tab>

  <Tab title="Alternative">
    ```javascript theme={"system"}
    <script>
      var toltScript = document.createElement('script'); 
      toltScript.src = 'https://cdn.tolt.io/tolt.js'; 
      toltScript.setAttribute('data-tolt', 'YOUR_PUBLIC_ORG_KEY'); 
      document.head.appendChild(toltScript);
    </script>
    ```
  </Tab>
</Tabs>

## Tracking Data

When a visitor arrives through a partner link, `window.tolt_data` contains:

```javascript theme={"system"}
{
  click_id: "30aa8b8d-b846-4827-bd6f-6beb16466841",
  cookie_duration: 30,
  partner_id: "f468da94-f786-485c-9314-3008ce472188",
  program_id: "prg_YRsbPDAKhWAdqJbFACheh",
  customer_id: null  // Only present after signup
}
```

If no affiliate link was used, `window.tolt_data` will be `null`.

### Lead Tracking

The script provides a signup function to convert clicks into leads:

```javascript theme={"system"}
const result = await window.tolt.signup("unique_identifier");
// unique_identifier can be an email or unique ID

// Returns:
{
  click_id: "30aa8b8d-b846-4827-bd6f-6beb16466841",
  customer_id: "cus_aE1xbsSk3HuZk58B2usFXNSv",
  customer_identifier: "unique_identifier",
  partner_id: "f468da94-f786-485c-9314-3008ce472188",
  program_id: "prg_YRsbPDAKhWAdqJbFACheh",
  message: "Success"
}
```

After a successful signup, `window.tolt_data` will be updated to include the `customer_id`.


# Lead Tracking
Source: https://docs.tolt.com/javascript/sign-up

Convert clicks into leads by signing up visitors with a unique identifier

## Overview

When a visitor comes through an affiliate link, you can convert their click into a lead by calling the signup function. Before signing up, you should check if:

1. The visitor came through an affiliate link (`window.tolt_data` exists)
2. The visitor hasn't already been signed up (`customer_id` is null)

### Example Implementation

```javascript theme={"system"}
async function signUpVisitor(identifier) {
  // Check if visitor came through affiliate link
  if (!window.tolt_data) {
    console.log("Not an affiliate click");
    return;
  }

  // Check if visitor is already signed up
  if (window.tolt_data.customer_id) {
    console.log("Visitor already signed up");
    return;
  }

  try {
    const result = await window.tolt.signup(identifier);
    console.log("Signup successful:", result);
    return result;
  } catch (error) {
    console.error("Signup failed:", error);
  }
}
```

The `identifier` parameter should be unique to each customer (like an email or user ID).

On success, the function returns:

```javascript theme={"system"}
{
  click_id: "30aa8b8d-b846-4827-bd6f-6beb16466841",
  customer_id: "cus_aE1xbsSk3HuZk58B2usFXNSv",
  customer_identifier: "unique_identifier",
  partner_id: "f468da94-f786-485c-9314-3008ce472188",
  program_id: "prg_YRsbPDAKhWAdqJbFACheh",
  message: "Success"
}
```

If the identifier already exists in the system, the function will throw a 409 error:

```javascript theme={"system"}
{
  message: "Customer already exists";
}
```

After a successful signup, `window.tolt_data` will be automatically updated with the new `customer_id`.


# Create Link
Source: https://docs.tolt.com/links/create

POST https://api.tolt.com/v1/links
This endpoint creates a tracking link.

## Base URL `https://api.tolt.com`

<br />

### Body Parameters

<ParamField type="string">
  The tracking parameter name (e.g., 'ref', 'via')
</ParamField>

<ParamField type="string">
  The value of the tracking parameter
</ParamField>

<ParamField type="string">
  The ID of the partner who owns this link
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array[Object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the link, prefixed with `lnk_`
    </ResponseField>

    <ResponseField name="param" type="string">
      Tracking parameter name
    </ResponseField>

    <ResponseField name="value" type="string">
      Tracking parameter value
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the partner who owns the link
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of update
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the link belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST 'https://api.tolt.com/v1/links' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "param": "ref",
      "value": "michael_scott",
      "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "lnk_dK9bzRGn46BhVgNFHD6fDgXW",
        "param": "ref",
        "value": "michael_scott",
        "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "created_at": "2025-01-15T14:30:00.000Z",
        "updated_at": "2025-01-15T14:30:00.000Z",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2"
      }
    ]
  }
  ```
</ResponseExample>


# Delete Link
Source: https://docs.tolt.com/links/delete

DELETE https://api.tolt.com/v1/links/:id
This endpoint deletes a tracking link.

## Base URL `https://api.tolt.com`

<br />

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the deleted link
    </ResponseField>

    <ResponseField name="deleted" type="boolean">
      Indicates that the link was deleted
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X DELETE 'https://api.tolt.com/v1/links/lnk_dK9bzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": {
      "id": "lnk_dK9bzRGn46BhVgNFHD6fDgXW",
      "deleted": true
    }
  }
  ```
</ResponseExample>


# List Links
Source: https://docs.tolt.com/links/list

GET https://api.tolt.com/v1/links
This endpoint lists all tracking links.

## Base URL `https://api.tolt.com`

<br />

### Query Parameters

<ParamField type="string">
  The program ID from where you want to list the links
</ParamField>

<ParamField type="string - optional">
  Only return links from this partner
</ParamField>

<ParamField type="string - optional">
  Filter links by tracking parameter name
</ParamField>

<ParamField type="string - optional">
  Filter links by tracking parameter value
</ParamField>

<ParamField type="asc | desc - optional">
  The order of the links to return by created\_at. Default is desc
</ParamField>

<ParamField type="array - optional">
  Specify which related objects to include in the response. Valid values are
  **'partner'** and **'program'**. Use **expand\[]=partner** or
  **expand\[]=program** to include the related objects.
</ParamField>

<ParamField type="string - optional">
  Only return links created after this date
</ParamField>

<ParamField type="string - optional">
  Only return links created before this date
</ParamField>

<ParamField type="string - optional">
  A limit on the number of links to return. Default is 10, max is 100
</ParamField>

<ParamField type="string - optional">
  A cursor for use in pagination. starting\_after is an object ID that defines
  your place in the list
</ParamField>

<ParamField type="string - optional">
  A cursor for use in pagination. ending\_before is an object ID that defines
  your place in the list
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether there are more pages of results available
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of links matching the query
</ResponseField>

<ResponseField name="data" type="array[Object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the link
    </ResponseField>

    <ResponseField name="param" type="string">
      Tracking parameter name
    </ResponseField>

    <ResponseField name="value" type="string">
      Tracking parameter value
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the partner who owns the link
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of update
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the link belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/links?program_id=prg_YRsbPDAKhWfdqJbFACheh' \
  -H 'Authorization: Bearer <API_KEY>'
  ```

  ```bash With Expand theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/links?program_id=prg_YRsbPDAKhWfdqJbFACheh&expand[]=partner&expand[]=program' \
  -H 'Authorization: Bearer <API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "has_more": true,
    "total_count": 45,
    "data": [
      {
        "id": "lnk_dK9bzRGn46BhVgNFHD6fDgXW",
        "param": "ref",
        "value": "michael_scott",
        "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "created_at": "2025-01-15T14:30:00.000Z",
        "updated_at": "2025-01-15T14:30:00.000Z",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2"
      }
    ]
  }
  ```

  ```json Expand Response theme={"system"}
  {
    "success": true,
    "has_more": true,
    "total_count": 45,
    "data": [
      {
        "id": "lnk_dK9bzRGn46BhVgNFHD6fDgXW",
        "param": "ref",
        "value": "michael_scott",
        "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "created_at": "2025-01-15T14:30:00.000Z",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
        "partner": {
          "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
          "first_name": "Michael",
          "last_name": "Scott",
          "email": "michael.scott@dundermifflin.com",
          "company_name": "Dunder Mifflin",
          "status": "active",
          "created_at": "2025-01-13T10:06:11.251Z"
        },
        "program": {
          "id": "prg_YRsbPDAKhWfdqJbFACheh",
          "status": "active",
          "name": "Tolt's Partnership Program",
          "product_name": "Tolt",
          "subdomain": "affiliates",
          "type": "public",
          "currency_code": "USD",
          "created_at": "2024-03-05T10:28:08.984+00:00"
        }
      }
    ]
  }
  ```
</ResponseExample>


# Retrieve Link
Source: https://docs.tolt.com/links/retrieve

GET https://api.tolt.com/v1/links/:id
This endpoint retrieves a tracking link by its ID.

## Base URL `https://api.tolt.com`

<br />

### Query Parameters

<ParamField type="array - optional">
  Specify which related objects to include in the response. Valid values are
  **'partner'** and **'program'**. Use **expand\[]=partner** or
  **expand\[]=program** to include the related objects.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array[Object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the link
    </ResponseField>

    <ResponseField name="param" type="string">
      Tracking parameter name
    </ResponseField>

    <ResponseField name="value" type="string">
      Tracking parameter value
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the partner who owns the link
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of update
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the link belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  //97b4e078-c614-483c-859b-9e447873a024

  ```bash cURL theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/links/lnk_dK9bzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>'
  ```

  ```bash With Expand theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/links/lnk_dK9bzRGn46BhVgNFHD6fDgXW?expand[]=partner&expand[]=program' \
  -H 'Authorization: Bearer <API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "lnk_dK9bzRGn46BhVgNFHD6fDgXW",
        "param": "ref",
        "value": "michael_scott",
        "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "created_at": "2025-01-15T14:30:00.000Z",
        "updated_at": "2025-01-15T14:30:00.000Z",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2"
      }
    ]
  }
  ```

  ```json Expand Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "lnk_dK9bzRGn46BhVgNFHD6fDgXW",
        "param": "ref",
        "value": "michael_scott",
        "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "created_at": "2025-01-15T14:30:00.000Z",
        "updated_at": "2025-01-15T14:30:00.000Z",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
        "partner": {
          "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
          "first_name": "Michael",
          "last_name": "Scott",
          "email": "michael.scott@dundermifflin.com",
          "company_name": "Dunder Mifflin",
          "status": "active",
          "created_at": "2025-01-13T10:06:11.251Z"
        },
        "program": {
          "id": "prg_YRsbPDAKhWfdqJbFACheh",
          "status": "active",
          "name": "Tolt's Partnership Program",
          "product_name": "Tolt",
          "subdomain": "affiliates",
          "type": "public",
          "currency_code": "USD",
          "created_at": "2024-03-05T10:28:08.984+00:00"
        }
      }
    ]
  }
  ```
</ResponseExample>


# Update Link
Source: https://docs.tolt.com/links/update

PUT https://api.tolt.com/v1/links/:id
This endpoint updates a tracking link.

## Base URL `https://api.tolt.com`

<br />

### Body Parameters

<ParamField type="string - optional">
  The tracking parameter name (e.g., 'ref', 'via')
</ParamField>

<ParamField type="string - optional">
  The value of the tracking parameter
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array[Object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the link
    </ResponseField>

    <ResponseField name="param" type="string">
      Updated tracking parameter name
    </ResponseField>

    <ResponseField name="value" type="string">
      Updated tracking parameter value
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the partner who owns the link
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the link belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X PUT 'https://api.tolt.com/v1/links/lnk_dK9bzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "param": "via",
      "value": "michael_scott_new"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "lnk_dK9bzRGn46BhVgNFHD6fDgXW",
        "param": "via",
        "value": "michael_scott_new",
        "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "created_at": "2025-01-15T14:30:00.000Z",
        "updated_at": "2025-01-15T14:30:00.000Z",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2"
      }
    ]
  }
  ```
</ResponseExample>


# Create Partner
Source: https://docs.tolt.com/partners/create

POST https://api.tolt.com/v1/partners
This endpoint creates a partner.

## Base URL `https://api.tolt.com`

<br />

### Body Parameters

<ParamField type="string">
  Partner's first name
</ParamField>

<ParamField type="string">
  Partner's last name
</ParamField>

<ParamField type="string">
  Partner's email address
</ParamField>

<ParamField type="string">
  The program ID that the partner will belong to
</ParamField>

<ParamField type="string - optional">
  The group ID to assign the partner to
</ParamField>

<ParamField type="string - optional">
  Partner's company name
</ParamField>

<ParamField type="string - optional">
  Two-letter ISO country code of the partner
</ParamField>

<ParamField type="string - optional">
  Partner's payout method. Valid values are: 'paypal', 'crypto', 'wise',
  'bank\_transfer', 'wire', 'none'
</ParamField>

<ParamField type="object - optional">
  Details specific to the selected payout method (e.g., PayPal email, bank
  details)
</ParamField>

<ParamField type="boolean - optional">
  When true, sends a welcome email to the partner after their account is
  created.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the partner, `uuid` or prefixed with `part_`
    </ResponseField>

    <ResponseField name="first_name" type="string">
      Partner's first name
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Partner's last name
    </ResponseField>

    <ResponseField name="email" type="string">
      Partner's email address
    </ResponseField>

    <ResponseField name="company_name" type="string">
      Partner's company name
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the partner belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>

    <ResponseField name="group_id" type="string">
      Group ID the partner belongs to
    </ResponseField>

    <ResponseField name="payout_method" type="string">
      Partner's payout method
    </ResponseField>

    <ResponseField name="payout_details" type="object">
      Payout method specific details
    </ResponseField>

    <ResponseField name="country_code" type="string">
      Two-letter ISO country code
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>

    <ResponseField name="completed_onboarding" type="boolean">
      The partner has completed onboarding.
    </ResponseField>

    <ResponseField name="rejection_note" type="string | null">
      A note why a partner was rejected.
    </ResponseField>

    <ResponseField name="internal_note" type="string | null">
      A note related to the partner.
    </ResponseField>

    <ResponseField name="suspension_reason" type="string | null">
      Reason for partner suspension if applicable.
    </ResponseField>

    <ResponseField name="first_customer_email_active" type="boolean">
      Whether first customer email notifications are active for this partner.
    </ResponseField>

    <ResponseField name="new_customer_email_active" type="boolean">
      Whether new customer email notifications are active for this partner.
    </ResponseField>

    <ResponseField name="payout_paid_email_active" type="boolean">
      Whether payout paid email notifications are active for this partner.
    </ResponseField>
  </Expandable>
</ResponseField>

### Errors

<ResponseField name="409 Conflict" type="object">
  Returned when a partner with the same email already exists in the program. The
  response includes the existing partner under `data`, so you can connect it to
  your system without a separate lookup.

  <Expandable title="properties">
    <ResponseField name="success" type="boolean">
      Always `false` for errors.
    </ResponseField>

    <ResponseField name="error" type="string">
      `"Partner with this email already exists."`
    </ResponseField>

    <ResponseField name="data" type="object">
      The existing partner (same shape as a retrieved partner), including its `id`.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST 'https://api.tolt.com/v1/partners' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "first_name": "Michael",
      "last_name": "Scott",
      "email": "michael.scott@dundermifflin.com",
      "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
      "company_name": "Dunder Mifflin",
      "country_code": "US",
      "payout_method": "paypal",
      "payout_details": {
          "email": "michael.paypal@dundermifflin.com"
      }
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "part_yP2D2oFyPsFUfkwzXCzRn3U2",
        "status": "active",
        "first_name": "TEST create",
        "last_name": "test",
        "company_name": null,
        "email": "aaaa@gmail.com",
        "program_id": "prg_ztTmEaAJRtfPVKM9nHhZwhjH",
        "organization_id": "org_qeHXERFhTv5DzxpvxtA5BWL5",
        "group_id": "grp_gMHPxVAQJghkdXSNXyQk6xfB",
        "created_at": "2025-08-06T13:46:07.328Z",
        "updated_at": "2025-08-06T13:46:07.328Z",
        "payout_method": "none",
        "payout_details": {},
        "country_code": null,
        "completed_onboarding": true,
        "rejection_note": null,
        "internal_note": null,
        "suspension_reason": null,
        "first_customer_email_active": true,
        "new_customer_email_active": true,
        "payout_paid_email_active": true
      }
    ]
  }
  ```

  ```json 409 Already exists theme={"system"}
  {
    "success": false,
    "error": "Partner with this email already exists.",
    "data": {
      "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
      "first_name": "Michael",
      "last_name": "Scott",
      "email": "michael.scott@dundermifflin.com",
      "company_name": "Dunder Mifflin",
      "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
      "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
      "group_id": "grp_Zc2uw9zm1eyBiD3MHcjV3RDn",
      "payout_method": "paypal",
      "payout_details": {
        "email": "michael.paypal@dundermifflin.com"
      },
      "country_code": "US",
      "status": "active",
      "created_at": "2025-01-13T10:06:11.251Z",
      "updated_at": "2025-01-13T10:06:11.251Z"
    }
  }
  ```
</ResponseExample>


# Delete Partner
Source: https://docs.tolt.com/partners/delete

DELETE https://api.tolt.com/v1/partners/:id
This endpoint deletes a partner.

## Base URL `https://api.tolt.com`

<br />

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the deleted partner, `uuid` or prefixed with `part_`
    </ResponseField>

    <ResponseField name="deleted" type="boolean">
      Indicates that the partner was deleted
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X DELETE 'https://api.tolt.com/v1/partners/part_s7mbzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": {
      "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
      "deleted": true
    }
  }
  ```
</ResponseExample>


# List Partners
Source: https://docs.tolt.com/partners/list

GET https://api.tolt.com/v1/partners
This endpoint lists all partners.

## Base URL `https://api.tolt.com`

<br />

### Query Parameters

<ParamField type="string">
  The program ID from where you want to list the partners.
</ParamField>

<ParamField type="string - optional">
  Only return partners from this group.
</ParamField>

<ParamField type="string - optional">
  Return the partner with this exact email address (case-insensitive) within the
  program. Useful for checking whether a partner already exists before creating
  one. Unlike the default listing, an `email` lookup also returns partners who
  have not yet finished onboarding.
</ParamField>

<ParamField type="asc | desc - optional">
  The order of the partners to return by created\_at. Default is desc.
</ParamField>

<ParamField type="array - optional">
  Specify which related objects to include in the response. Valid values are
  **'group'** and **'program'**. Use **expand\[]=group** or **expand\[]=program**
  to include the related objects.
</ParamField>

<ParamField type="array - optional">
  Specify additional related data to include in the response. Valid value is
  **'stats'**. Use **include\[]=stats**.
</ParamField>

<ParamField type="string - optional">
  Only return partners created after this date.
</ParamField>

<ParamField type="string - optional">
  Only return partners created before this date.
</ParamField>

<ParamField type="string - optional">
  A limit on the number of partners to return. Default is 10, max is 100.
</ParamField>

<ParamField type="string - optional">
  A cursor for use in pagination. starting\_after is an object ID that defines
  your place in the list. The value of the starting\_after parameter is the
  partner ID. To receive the next page use the last partner ID from the previous
  page.
</ParamField>

<ParamField type="string - optional">
  A cursor for use in pagination. ending\_before is an object ID that defines
  your place in the list. The value of the ending\_before parameter is the
  partner ID. To receive the previous page use the first partner ID from the
  previous page.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether there are more pages of results available
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of partners matching the query
</ResponseField>

<ResponseField name="data" type="array[Object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the partner, `uuid` or prefixed with `part_`.
    </ResponseField>

    <ResponseField name="first_name" type="string">
      Partner's first name
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Partner's last name
    </ResponseField>

    <ResponseField name="email" type="string">
      Partner's email address
    </ResponseField>

    <ResponseField name="company_name" type="string">
      Partner's company name
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Unique identifier for the program the partner belongs to, `uuid` or prefixed
      with `prg_`.
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Unique identifier for the organization, `uuid` or prefixed with `org_`.
    </ResponseField>

    <ResponseField name="group_id" type="string">
      Unique identifier for the partner's group, `uuid` or prefixed with `grp_`.
    </ResponseField>

    <ResponseField name="payout_method" type="string">
      Partner's selected payout method (e.g., 'paypal', 'crypto', 'wise', 'bank\_transfer', 'wire', 'none')
    </ResponseField>

    <ResponseField name="payout_details" type="object">
      Details specific to the selected payout method (e.g., PayPal email, bank details)
    </ResponseField>

    <ResponseField name="country_code" type="string">
      Two-letter ISO country code of the partner
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the partner was created
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the partner (e.g., 'active', 'pending', 'suspended', 'rejected')
    </ResponseField>

    <ResponseField name="custom_fields" type="array">
      Custom-field answers submitted by the partner. Returns an empty array when
      the partner has no custom-field answers.

      <Expandable title="custom field properties">
        <ResponseField name="answer_id" type="string">
          Unique identifier for the custom-field answer.
        </ResponseField>

        <ResponseField name="answer" type="string">
          The answer submitted by the partner.
        </ResponseField>

        <ResponseField name="question_id" type="string">
          Unique identifier for the custom-field question.
        </ResponseField>

        <ResponseField name="question" type="string | null">
          The custom-field question shown to the partner. Returns `null` when the
          question was created without text.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="rejected_at" type="string | null">
      ISO 8601 timestamp recorded when the partner was rejected, or `null` when
      the partner is not rejected.
    </ResponseField>

    <ResponseField name="group" type="object">
      <Expandable title="group">
        Group details when expanded:

        <ResponseField name="id" type="string">
          Unique identifier for the group
        </ResponseField>

        <ResponseField name="name" type="string">
          Name of the group
        </ResponseField>

        <ResponseField name="description" type="string">
          Description of the group
        </ResponseField>

        <ResponseField name="created_at" type="string">
          ISO 8601 timestamp of when the group was created
        </ResponseField>

        <ResponseField name="public_key" type="string">
          Public identifier for the group
        </ResponseField>

        <ResponseField name="default" type="boolean">
          Whether this is the default group
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="program" type="object">
      <Expandable title="program">
        Program details when expanded:

        <ResponseField name="id" type="string">
          Unique identifier for the program
        </ResponseField>

        <ResponseField name="status" type="string">
          Program status
        </ResponseField>

        <ResponseField name="name" type="string">
          Program name
        </ResponseField>

        <ResponseField name="product_name" type="string">
          Name of the product
        </ResponseField>

        <ResponseField name="subdomain" type="string">
          Program's subdomain
        </ResponseField>

        <ResponseField name="type" type="string">
          Program type (e.g., 'public')
        </ResponseField>

        <ResponseField name="currency_code" type="string">
          Three-letter ISO currency code
        </ResponseField>

        <ResponseField name="cookie_duration" type="integer">
          Duration of tracking cookies in days
        </ResponseField>

        <ResponseField name="payout_methods" type="array">
          Available payout methods
        </ResponseField>

        <ResponseField name="payout_term" type="string">
          Payment terms in days
        </ResponseField>

        <ResponseField name="url_params" type="array">
          Supported URL parameters for tracking
        </ResponseField>

        <ResponseField name="created_at" type="string">
          ISO 8601 timestamp of when the program was created
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="stats" type="object">
      <Expandable title="stats">
        Stats details when included:

        <ResponseField name="total_clicks" type="integer">
          Total tracked clicks for this partner.
        </ResponseField>

        <ResponseField name="total_customers" type="integer">
          Total non-lead customers attributed to this partner.
        </ResponseField>

        <ResponseField name="total_revenue" type="integer">
          Total non-refunded transaction revenue for this partner (in cents).
        </ResponseField>

        <ResponseField name="total_commission" type="integer">
          Total commission amount for this partner (in cents).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/partners?program_id=prg_YRsbPDAKhWfdqJbFACheh' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```

  ```bash cURL - Find by email theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/partners?program_id=prg_YRsbPDAKhWfdqJbFACheh&email=michael.scott@dundermifflin.com' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```

  ```bash cURL - Expand theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/partners?program_id=prg_YRsbPDAKhWfdqJbFACheh&expand[]=group&expand[]=program' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```

  ```bash cURL - Include Stats theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/partners?program_id=prg_YRsbPDAKhWfdqJbFACheh&expand[]=group&expand[]=program&include[]=stats' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```
</RequestExample>

<ResponseExample>
  ```bash Response theme={"system"}
  {
      "success": true,
      "has_more": true,
      "total_count": 160,
      "data": [
          {
              "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
              "first_name": "Michael",
              "last_name": "Scott",
              "email": "michael.scott@dundermifflin.com",
              "company_name": "Dunder Mifflin",
              "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
              "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
              "group_id": "grp_Zc2uw9zm1eyBiD3MHcjV3RDn",
              "payout_method": "paypal",
              "payout_details": {
                  "email": "michael.paypal@dundermifflin.com",
              },
              "country_code": "US",
              "created_at": "2025-01-13T10:06:11.251Z",
              "custom_fields": [
                  {
                      "answer_id": "ans_2cuw9zm1eyBiD3MHcjV3RDn",
                      "answer": "SaaS founders",
                      "question_id": "que_6uw9zm1eyBiD3MHcjV3RDn",
                      "question": "Who is your audience?"
                  }
              ]
              "status": "active",
              "rejected_at": null
          }
      ]
  }
  ```

  ```bash Expand + Include Stats Response theme={"system"}
  {
      "success": true,
      "has_more": true,
      "total_count": 160,
      "data": [
          {
              "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
              "first_name": "Michael",
              "last_name": "Scott",
              "email": "michael.scott@dundermifflin.com",
              "company_name": "Dunder Mifflin",
              "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
              "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
              "group_id": "grp_Zc2uw9zm1eyBiD3MHcjV3RDn",
              "payout_method": "paypal",
              "payout_details": {
                  "email": "michael.paypal@dundermifflin.com",
              },
              "country_code": "US",
              "created_at": "2025-01-13T10:06:11.251Z",
              "group": {
                  "id": "grp_Zc2uw9zm1eyBiD3MHcjV3RDn",
                  "name": "Dunder Mifflin Group",
                  "description": "Dunder Mifflin Group 20% off",
                  "created_at": "2024-11-25T15:24:26.846428+00:00",
                  "public_key": "dunder-mifflin-group",
                  "default": true
              },
              "program": {
                  "id": "prg_YRsbPDAKhWfdqJbFACheh",
                  "status": "active",
                  "name": "Tolt's Partnership Program",
                  "product_name": "Tolt",
                  "subdomain": "affiliates",
                  "type": "public",
                  "currency_code": "USD",
                  "cookie_duration": 30,
                  "payout_methods": [
                      "none",
                      "crypto",
                      "wise",
                      "bank_transfer",
                      "wire",
                      "paypal"
                  ],
                  "payout_term": "15",
                  "url_params": [
                      "aff",
                      "via"
                  ],
                  "created_at": "2024-03-05T10:28:08.984+00:00"
              },
              "stats": {
                  "total_clicks": 1024,
                  "total_customers": 112,
                  "total_revenue": 145000,
                  "total_commission": 22000
              }
          }
      ]
  }
  ```
</ResponseExample>


# Retrieve Partner
Source: https://docs.tolt.com/partners/retrieve

GET https://api.tolt.com/v1/partners/:id
This endpoint retrieves a partner.

## Base URL `https://api.tolt.com`

<br />

### Query Parameters

<ParamField type="array - optional">
  Specify which related objects to include in the response. Valid values are
  **'group'** and **'program'**. Use **expand\[]=group** or **expand\[]=program**
  to include the related objects.
</ParamField>

<ParamField type="array - optional">
  Specify which related objects to include in the response. Valid values are
  **'stats'**. Use **include\[]=stats** to include the related objects.
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique identifier for the partner, `uuid` or prefixed with `part_`.
</ResponseField>

<ResponseField name="first_name" type="string">
  Partner's first name
</ResponseField>

<ResponseField name="last_name" type="string">
  Partner's last name
</ResponseField>

<ResponseField name="email" type="string">
  Partner's email address
</ResponseField>

<ResponseField name="company_name" type="string">
  Partner's company name
</ResponseField>

<ResponseField name="program_id" type="string">
  Unique identifier for the program the partner belongs to, `uuid` or prefixed
  with `prg_`.
</ResponseField>

<ResponseField name="organization_id" type="string">
  Unique identifier for the organization, `uuid` or prefixed with `org_`.
</ResponseField>

<ResponseField name="group_id" type="string">
  Unique identifier for the partner's group, `uuid` or prefixed with `grp_`.
</ResponseField>

<ResponseField name="payout_method" type="string">
  Partner's selected payout method (e.g., 'paypal', 'crypto', 'wise',
  'bank\_transfer', 'wire', 'none')
</ResponseField>

<ResponseField name="payout_details" type="object">
  Details specific to the selected payout method (e.g., PayPal email, bank
  details)
</ResponseField>

<ResponseField name="country_code" type="string">
  Two-letter ISO country code of the partner
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the partner was created
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the partner (e.g., 'active', 'pending', 'suspended',
  'rejected')
</ResponseField>

<ResponseField name="rejected_at" type="string | null">
  ISO 8601 timestamp recorded when the partner was rejected, or `null` when the
  partner is not rejected.
</ResponseField>

<ResponseField name="custom_fields" type="array">
  Answers submitted by the partner during sign-up.
</ResponseField>

<ResponseField name="group" type="object">
  <Expandable title="group">
    Group details when expanded:

    <ResponseField name="id" type="string">
      Unique identifier for the group
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the group
    </ResponseField>

    <ResponseField name="description" type="string">
      Description of the group
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the group was created
    </ResponseField>

    <ResponseField name="public_key" type="string">
      Public identifier for the group
    </ResponseField>

    <ResponseField name="default" type="boolean">
      Whether this is the default group
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="program" type="object">
  <Expandable title="program">
    Program details when expanded:

    <ResponseField name="id" type="string">
      Unique identifier for the program
    </ResponseField>

    <ResponseField name="status" type="string">
      Program status
    </ResponseField>

    <ResponseField name="name" type="string">
      Program name
    </ResponseField>

    <ResponseField name="product_name" type="string">
      Name of the product
    </ResponseField>

    <ResponseField name="subdomain" type="string">
      Program's subdomain
    </ResponseField>

    <ResponseField name="type" type="string">
      Program type (e.g., 'public')
    </ResponseField>

    <ResponseField name="currency_code" type="string">
      Three-letter ISO currency code
    </ResponseField>

    <ResponseField name="cookie_duration" type="integer">
      Duration of tracking cookies in days
    </ResponseField>

    <ResponseField name="payout_methods" type="array">
      Available payout methods
    </ResponseField>

    <ResponseField name="payout_term" type="string">
      Payment terms in days
    </ResponseField>

    <ResponseField name="url_params" type="array">
      Supported URL parameters for tracking
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the program was created
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="stats" type="object">
  <Expandable title="stats">
    An object containing the partner's performance statistics. All monetary
    values are in cents (or lowest denomination of the currency).

    <ResponseField name="total_clicks" type="integer">
      Total number of clicks on partner's referral links
    </ResponseField>

    <ResponseField name="total_customers" type="integer">
      Total number of customers referred
    </ResponseField>

    <ResponseField name="total_revenue" type="integer">
      Total revenue generated in cents
    </ResponseField>

    <ResponseField name="total_commission" type="integer">
      Total commission earned in cents
    </ResponseField>

    <ResponseField name="total_leads" type="integer">
      Total number of leads generated
    </ResponseField>

    <ResponseField name="total_trial_customers" type="integer">
      Total number of trial customers
    </ResponseField>

    <ResponseField name="total_paid_customers" type="integer">
      Total number of paid customers
    </ResponseField>

    <ResponseField name="total_canceled_customers" type="integer">
      Total number of customers who canceled
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/partners/part_s7mbzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```

  ```bash cURL - Expand & Include theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/partners/part_s7mbzRGn46BhVgNFHD6fDgXW&expand[]=group&expand[]=program&include[]=stats' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d ''
  ```
</RequestExample>

<ResponseExample>
  ```bash Response theme={"system"}
  {
      "success": true,
      "data": {
          "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
          "first_name": "Michael",
          "last_name": "Scott",
          "email": "michael.scott@dundermifflin.com",
          "company_name": "Dunder Mifflin",
          "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
          "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
          "group_id": "grp_Zc2uw9zm1eyBiD3MHcjV3RDn",
          "payout_method": "paypal",
          "payout_details": {
              "email": "michael.paypal@dundermifflin.com",
          },
          "country_code": "US",
          "created_at": "2025-01-13T10:06:11.251Z",
          "status": "active",
          "rejected_at": null,
          "custom_fields": []
      }
  }
  ```

  ```bash Expand & Include Response theme={"system"}
  {
      "success": true,
      "data": {
          "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
          "first_name": "Michael",
          "last_name": "Scott",
          "email": "michael.scott@dundermifflin.com",
          "company_name": "Dunder Mifflin",
          "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
          "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
          "group_id": "grp_Zc2uw9zm1eyBiD3MHcjV3RDn",
          "payout_method": "paypal",
          "payout_details": {
              "email": "michael.paypal@dundermifflin.com",
          },
          "country_code": "US",
          "created_at": "2025-01-13T10:06:11.251Z",
          "group": {
              "id": "grp_Zc2uw9zm1eyBiD3MHcjV3RDn",
              "name": "Dunder Mifflin Group",
              "description": "Dunder Mifflin Group 20% off",
              "created_at": "2024-11-25T15:24:26.846428+00:00",
              "public_key": "dunder-mifflin-group",
              "default": true
          },
          "program": {
              "id": "prg_YRsbPDAKhWfdqJbFACheh",
              "status": "active",
              "name": "Tolt's Partnership Program",
              "product_name": "Tolt",
              "subdomain": "affiliates",
              "type": "public",
              "currency_code": "USD",
              "cookie_duration": 30,
              "payout_methods": [
                  "none",
                  "crypto",
                  "wise",
                  "bank_transfer",
                  "wire",
                  "paypal"
              ],
              "payout_term": "15",
              "url_params": [
                  "aff",
                  "via"
              ],
              "created_at": "2024-03-05T10:28:08.984+00:00"
          },
          "stats": {
              "total_clicks": 40,
              "total_customers": 41,
              "total_revenue": 522226,
              "total_commission": 1741877,
              "total_leads": 11,
              "total_trial_customers": 0,
              "total_paid_customers": 23,
              "total_canceled_customers": 6
          }
      }
  }
  ```
</ResponseExample>


# Update Partner
Source: https://docs.tolt.com/partners/update

PUT https://api.tolt.com/v1/partners/:id
This endpoint updates a partner.

## Base URL `https://api.tolt.com`

<br />

### Body Parameters

<ParamField type="string - optional">
  Partner's first name
</ParamField>

<ParamField type="string - optional">
  Partner's last name
</ParamField>

<ParamField type="string - optional">
  Partner's email address
</ParamField>

<ParamField type="string - optional">
  The group ID to assign the partner to
</ParamField>

<ParamField type="string - optional">
  Partner's company name
</ParamField>

<ParamField type="string - optional">
  Two-letter ISO country code of the partner
</ParamField>

<ParamField type="string - optional">
  Partner's payout method. Valid values are: 'paypal', 'crypto', 'wise',
  'bank\_transfer', 'wire', 'none'
</ParamField>

<ParamField type="object - optional">
  Details specific to the selected payout method (e.g., PayPal email, bank
  details)
</ParamField>

<ParamField type="string - optional">
  Partner's status. Valid values are: 'active', 'suspended', 'rejected'. Setting
  the status to `rejected` records `rejected_at`; changing it to another status
  clears `rejected_at`.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the partner, `uuid` or prefixed with `part_`
    </ResponseField>

    <ResponseField name="first_name" type="string">
      Partner's first name
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Partner's last name
    </ResponseField>

    <ResponseField name="email" type="string">
      Partner's email address
    </ResponseField>

    <ResponseField name="company_name" type="string">
      Partner's company name
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the partner belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>

    <ResponseField name="group_id" type="string">
      Group ID the partner belongs to
    </ResponseField>

    <ResponseField name="payout_method" type="string">
      Partner's payout method
    </ResponseField>

    <ResponseField name="payout_details" type="object">
      Payout method specific details
    </ResponseField>

    <ResponseField name="country_code" type="string">
      Two-letter ISO country code
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="status" type="string">
      Partner's status. Valid values are: 'active', 'pending', 'suspended',
      'rejected'.
    </ResponseField>

    <ResponseField name="completed_onboarding" type="boolean">
      The partner has completed onboarding.
    </ResponseField>

    <ResponseField name="rejection_note" type="string | null">
      A note why a partner was rejected.
    </ResponseField>

    <ResponseField name="rejected_at" type="string | null">
      ISO 8601 timestamp recorded when the partner was rejected, or `null` when
      the partner is not rejected.
    </ResponseField>

    <ResponseField name="internal_note" type="string | null">
      A note related to the partner.
    </ResponseField>

    <ResponseField name="suspension_reason" type="string | null">
      Reason for partner suspension if applicable.
    </ResponseField>

    <ResponseField name="first_customer_email_active" type="boolean">
      Whether first customer email notifications are active for this partner.
    </ResponseField>

    <ResponseField name="new_customer_email_active" type="boolean">
      Whether new customer email notifications are active for this partner.
    </ResponseField>

    <ResponseField name="payout_paid_email_active" type="boolean">
      Whether payout paid email notifications are active for this partner.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X PUT 'https://api.tolt.com/v1/partners/part_s7mbzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "company_name": "Dunder Mifflin Paper Company",
      "payout_method": "wise",
      "payout_details": {
          "email": "michael.wise@dundermifflin.com"
      }
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": {
      "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
      "first_name": "Michael",
      "last_name": "Scott",
      "email": "michael.scott@dundermifflin.com",
      "company_name": "Dunder Mifflin Paper Company",
      "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
      "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
      "group_id": "grp_Zc2uw9zm1eyBiD3MHcjV3RDn",
      "payout_method": "wise",
      "payout_details": {
        "email": "michael.wise@dundermifflin.com"
      },
      "country_code": "US",
      "created_at": "2025-01-13T10:06:11.251Z",
      "status": "active",
      "completed_onboarding": true,
      "rejection_note": null,
      "rejected_at": null,
      "internal_note": null,
      "suspension_reason": null,
      "first_customer_email_active": true,
      "new_customer_email_active": true,
      "payout_paid_email_active": true
    }
  }
  ```
</ResponseExample>


# List Programs
Source: https://docs.tolt.com/programs/list

GET https://api.tolt.com/v1/programs
This endpoint lists all programs available in your organization.

## Base URL `https://api.tolt.com`

<br />

### Query Parameters

This endpoint does not accept query parameters.

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful.
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether there are more pages of results available.
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of programs.
</ResponseField>

<ResponseField name="data" type="array[Object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the program, `uuid` or prefixed with `prg_`.
    </ResponseField>

    <ResponseField name="name" type="string">
      Program name.
    </ResponseField>

    <ResponseField name="status" type="string">
      Program status (for example, `active` or `inactive`).
    </ResponseField>

    <ResponseField name="currency_code" type="string">
      Three-letter ISO currency code used by the program.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the program was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/programs' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json'
  ```
</RequestExample>

<ResponseExample>
  ```bash Response theme={"system"}
  {
    "success": true,
    "has_more": false,
    "total_count": 2,
    "data": [
      {
        "id": "prg_YRsbPDAKhWfdqJbFACheh",
        "name": "Main Program",
        "status": "active",
        "currency_code": "USD",
        "created_at": "2025-01-13T10:06:11.251Z"
      },
      {
        "id": "prg_ztTmEaAJRtfPVKM9nHhZwhjH",
        "name": "EU Program",
        "status": "active",
        "currency_code": "EUR",
        "created_at": "2025-02-02T09:00:00.000Z"
      }
    ]
  }
  ```
</ResponseExample>


# Create Promotion Code
Source: https://docs.tolt.com/promotion-codes/create

POST https://api.tolt.com/v1/promotion-codes
This endpoint creates a promotion code.

## Base URL `https://api.tolt.com`

<br />

### Body Parameters

<ParamField type="string">
  The promotion code value (e.g., 'SUMMER2024')
</ParamField>

<ParamField type="string">
  The type of discount. Valid values are: **'fixed'** or **'percentage'**
</ParamField>

<ParamField type="number">
  The discount value. For fixed type, amount in cents. For percentage type,
  value between 0 and 100
</ParamField>

<ParamField type="string">
  The ID of the partner who owns this promotion code
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array[object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the promotion code, prefixed with `prc_`
    </ResponseField>

    <ResponseField name="code" type="string">
      The promotion code value
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of discount
    </ResponseField>

    <ResponseField name="entity_type" type="string | null">
      Entity type of the code
    </ResponseField>

    <ResponseField name="value" type="number">
      The discount value
    </ResponseField>

    <ResponseField name="active" type="boolean">
      If the code is active
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the partner who owns the code
    </ResponseField>

    <ResponseField name="group_id" type="string | null">
      ID of the group
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the promotion code belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST 'https://api.tolt.com/v1/promotion-codes' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "code": "SUMMER2024",
      "type": "percentage",
      "value": 20,
      "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "prc_dK9bzRGn46BhVgNFHD6fDgXW",
        "active": true,
        "entity_type": null,
        "code": "SUMMER2024",
        "value": 20,
        "type": "percentage",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "group_id": null,
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
        "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "created_at": "2025-01-15T14:30:00.000Z",
        "updated_at": "2025-01-15T14:30:00.000Z"
      }
    ]
  }
  ```
</ResponseExample>


# Delete Promotion Code
Source: https://docs.tolt.com/promotion-codes/delete

DELETE https://api.tolt.com/v1/promotion-codes/:id
This endpoint deletes a promotion code.

## Base URL `https://api.tolt.com`

<br />

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the deleted promotion code
    </ResponseField>

    <ResponseField name="deleted" type="boolean">
      Indicates that the promotion code was deleted
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X DELETE 'https://api.tolt.com/v1/promotion-codes/prc_dK9bzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": {
      "id": "prc_dK9bzRGn46BhVgNFHD6fDgXW",
      "deleted": true
    }
  }
  ```
</ResponseExample>


# List Promotion Codes
Source: https://docs.tolt.com/promotion-codes/list

GET https://api.tolt.com/v1/promotion-codes
This endpoint lists all promotion codes.

## Base URL `https://api.tolt.com`

<br />

### Query Parameters

<ParamField type="string">
  The program ID from where you want to list the partners.
</ParamField>

<ParamField type="string - optional">
  Only return promotion codes from this partner
</ParamField>

<ParamField type="string - optional">
  Search promotion codes by code value.
</ParamField>

<ParamField type="asc | desc - optional">
  The order of the promotion codes to return by created\_at. Default is desc
</ParamField>

<ParamField type="array - optional">
  Specify which related objects to include in the response. Valid values are
  **'partner'** and **'program'**. Use **expand\[]=partner** or
  **expand\[]=program** to include the related objects.
</ParamField>

<ParamField type="string - optional">
  Only return promotion codes created after this date
</ParamField>

<ParamField type="string - optional">
  Only return promotion codes created before this date
</ParamField>

<ParamField type="string - optional">
  A limit on the number of promotion codes to return. Default is 10, max is 100
</ParamField>

<ParamField type="string - optional">
  A cursor for use in pagination. starting\_after is an object ID that defines
  your place in the list
</ParamField>

<ParamField type="string - optional">
  A cursor for use in pagination. ending\_before is an object ID that defines
  your place in the list
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether there are more pages of results available
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of promotion codes matching the query
</ResponseField>

<ResponseField name="data" type="array[Object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the promotion code
    </ResponseField>

    <ResponseField name="code" type="string">
      The promotion code value
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of discount
    </ResponseField>

    <ResponseField name="value" type="number">
      The discount value
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the partner who owns the code
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the promotion code belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/promotion-codes' \
  -H 'Authorization: Bearer <API_KEY>'
  ```

  ```bash With Expand theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/promotion-codes?expand[]=partner&expand[]=program' \
  -H 'Authorization: Bearer <API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "has_more": true,
    "total_count": 45,
    "data": [
      {
        "id": "prc_dK9bzRGn46BhVgNFHD6fDgXW",
        "code": "SUMMER2024",
        "type": "percentage",
        "value": 20,
        "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "created_at": "2025-01-15T14:30:00.000Z",
        "updated_at": "2025-01-15T14:30:00.000Z",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2"
      }
    ]
  }
  ```

  ```json Expand Response theme={"system"}
  {
    "success": true,
    "has_more": true,
    "total_count": 45,
    "data": [
      {
        "id": "prc_dK9bzRGn46BhVgNFHD6fDgXW",
        "code": "SUMMER2024",
        "type": "percentage",
        "value": 20,
        "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "created_at": "2025-01-15T14:30:00.000Z",
        "updated_at": "2025-01-15T14:30:00.000Z",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
        "partner": {
          "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
          "first_name": "Michael",
          "last_name": "Scott",
          "email": "michael.scott@dundermifflin.com",
          "company_name": "Dunder Mifflin",
          "status": "active",
          "created_at": "2025-01-13T10:06:11.251Z"
        },
        "program": {
          "id": "prg_YRsbPDAKhWfdqJbFACheh",
          "status": "active",
          "name": "Tolt's Partnership Program",
          "product_name": "Tolt",
          "subdomain": "affiliates",
          "type": "public",
          "currency_code": "USD",
          "created_at": "2024-03-05T10:28:08.984+00:00"
        }
      }
    ]
  }
  ```
</ResponseExample>


# Retrieve Promotion Code
Source: https://docs.tolt.com/promotion-codes/retrieve

GET https://api.tolt.com/v1/promotion-codes/:id
This endpoint retrieves a promotion code.

## Base URL `https://api.tolt.com`

<br />

### Query Parameters

<ParamField type="array - optional">
  Specify which related objects to include in the response. Valid values are
  **'partner'** and **'program'**. Use **expand\[]=partner** or
  **expand\[]=program** to include the related objects.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the promotion code
    </ResponseField>

    <ResponseField name="code" type="string">
      The promotion code value
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of discount
    </ResponseField>

    <ResponseField name="value" type="number">
      The discount value
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the partner who owns the code
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the promotion code belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/promotion-codes/prc_dK9bzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>'
  ```

  ```bash With Expand theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/promotion-codes/prc_dK9bzRGn46BhVgNFHD6fDgXW?expand[]=partner&expand[]=program' \
  -H 'Authorization: Bearer <API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": {
      "id": "prc_dK9bzRGn46BhVgNFHD6fDgXW",
      "code": "SUMMER2024",
      "type": "percentage",
      "value": 20,
      "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
      "created_at": "2025-01-15T14:30:00.000Z",
      "updated_at": "2025-01-15T14:30:00.000Z",
      "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
      "organization_id": "org_JE3mfYNL9ci7sFaJazAv2"
    }
  }
  ```

  ```json Expand Response theme={"system"}
  {
    "success": true,
    "data": {
      "id": "prc_dK9bzRGn46BhVgNFHD6fDgXW",
      "code": "SUMMER2024",
      "type": "percentage",
      "value": 20,
      "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
      "created_at": "2025-01-15T14:30:00.000Z",
      "updated_at": "2025-01-15T14:30:00.000Z",
      "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
      "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
      "partner": {
        "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "first_name": "Michael",
        "last_name": "Scott",
        "email": "michael.scott@dundermifflin.com",
        "company_name": "Dunder Mifflin",
        "status": "active",
        "created_at": "2025-01-13T10:06:11.251Z"
      },
      "program": {
        "id": "prg_YRsbPDAKhWfdqJbFACheh",
        "status": "active",
        "name": "Tolt's Partnership Program",
        "product_name": "Tolt",
        "subdomain": "affiliates",
        "type": "public",
        "currency_code": "USD",
        "created_at": "2024-03-05T10:28:08.984+00:00"
      }
    }
  }
  ```
</ResponseExample>


# Update Promotion Code
Source: https://docs.tolt.com/promotion-codes/update

PUT https://api.tolt.com/v1/promotion-codes/:id
This endpoint updates a promotion code.

## Base URL `https://api.tolt.com`

<br />

### Body Parameters

<ParamField type="string - optional">
  The type of discount. Valid values are: **'fixed'** or **'percentage'**
</ParamField>

<ParamField type="number - optional">
  The discount value. For fixed type, amount in cents. For percentage type,
  value between 0 and 100
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array[object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the promotion code, prefixed with `prc_`
    </ResponseField>

    <ResponseField name="code" type="string">
      The promotion code value
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of discount
    </ResponseField>

    <ResponseField name="entity_type" type="string | null">
      Entity type of the code
    </ResponseField>

    <ResponseField name="value" type="number">
      The discount value
    </ResponseField>

    <ResponseField name="active" type="boolean">
      If the code is active
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the partner who owns the code
    </ResponseField>

    <ResponseField name="group_id" type="string | null">
      ID of the group
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the promotion code belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X PUT 'https://api.tolt.com/v1/promotion-codes/prc_dK9bzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "type": "fixed",
      "value": 2500
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "prc_dK9bzRGn4BhVgNFHD6fDgXW",
        "active": true,
        "entity_type": null,
        "code": "SUMMER2024",
        "value": 20,
        "type": "percentage",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "group_id": null,
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
        "partner_id": "part_s7mbzRjGn46BhVgNFHD6fDgXW",
        "created_at": "2025-01-15T14:30:00.000Z",
        "updated_at": "2025-01-15T14:30:00.000Z"
      }
    ]
  }
  ```
</ResponseExample>


# Rate Limits
Source: https://docs.tolt.com/rate-limit

Understanding Tolt API rate limits

## Overview

The Tolt API implements rate limiting to ensure stability and fair usage across all users. Rate limits are applied on a per-API key basis.

## Current Limits

<Card title="Rate Limits">
  **25 requests per second**
</Card>

## Rate Limit Response

When you exceed the rate limit, the API will return a `429 Too Many Requests` response with the following JSON body:

```json theme={"system"}
{
  "success": false,
  "error": {
    "message": "Too many requests. Please try again.",
    "type": "rate_limit_error"
  }
}
```

## Best Practices

To work effectively within these limits:

1. **Implement Retries**

   * Use exponential backoff when you receive a 429 response
   * Wait for the duration specified in the error message before retrying

2. **Monitor Usage**

   * Track the rate limit headers in your responses
   * Set up alerts when you're approaching limits
   * Consider implementing your own request throttling

3. **Optimize Requests**
   * Batch operations when possible
   * Cache responses when appropriate
   * Use webhook notifications instead of polling

## Need Higher Limits?

If you require higher rate limits for your use case, please contact our support team at [support@tolt.io](mailto:support@tolt.io).


# Create Transaction
Source: https://docs.tolt.com/transactions/create

POST https://api.tolt.com/v1/transactions
This endpoint creates a transaction.

## Base URL `https://api.tolt.com`

<br />

### Body Parameters

<ParamField type="number">
  The transaction amount in cents
</ParamField>

<ParamField type="string">
  The ID of the customer associated with this transaction
</ParamField>

<ParamField type="string - optional">
  The billing type. Valid values are: **'one\_time'** or **'subscription'**
</ParamField>

<ParamField type="string - optional">
  Associated charge identifier
</ParamField>

<ParamField type="string - optional">
  Associated click identifier
</ParamField>

<ParamField type="string - optional">
  ISO 8601 timestamp of when the transaction was created
</ParamField>

<ParamField type="string - optional">
  The ID of the product associated with this transaction
</ParamField>

<ParamField type="string - optional">
  The name of the product associated with this transaction
</ParamField>

<ParamField type="string - optional">
  Source of the transaction
</ParamField>

<ParamField type="string - optional">
  For subscription billing type. Valid values are: **'month'** or **'year'**
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array[object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the transaction
    </ResponseField>

    <ResponseField name="amount" type="number">
      Transaction amount in cents
    </ResponseField>

    <ResponseField name="customer_id" type="string">
      ID of the associated customer
    </ResponseField>

    <ResponseField name="billing_type" type="string">
      The billing type
    </ResponseField>

    <ResponseField name="amount_excluding_tax" type="number | null">
      Transaction amount excluding tax in cents
    </ResponseField>

    <ResponseField name="amount_including_tax" type="number | null">
      Transaction amount including tax in cents
    </ResponseField>

    <ResponseField name="tax" type="number | null">
      Tax amount in cents
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code for the transaction amount
    </ResponseField>

    <ResponseField name="payment_currency" type="string">
      Currency used for the payment
    </ResponseField>

    <ResponseField name="payment_amount" type="number | null">
      Payment amount in cents
    </ResponseField>

    <ResponseField name="payment_amount_excluding_tax" type="number | null">
      Payment amount excluding tax in cents
    </ResponseField>

    <ResponseField name="payment_amount_including_tax" type="number | null">
      Payment amount including tax in cents
    </ResponseField>

    <ResponseField name="payment_tax" type="number | null">
      Payment tax amount in cents
    </ResponseField>

    <ResponseField name="charge_id" type="string">
      Associated charge identifier
    </ResponseField>

    <ResponseField name="click_id" type="string">
      Associated click identifier
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="source" type="string">
      Source of the transaction
    </ResponseField>

    <ResponseField name="status" type="string">
      Status of the transaction
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Optional metadata
    </ResponseField>

    <ResponseField name="interval" type="string">
      Subscription interval
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>

    <ResponseField name="product_ids" type="array[string]">
      List of product identifiers associated with the transaction
    </ResponseField>

    <ResponseField name="product_names" type="array[string] | null">
      List of product names associated with the transaction
    </ResponseField>

    <ResponseField name="conversion_rate" type="number | null">
      Conversion rate if currency conversion is involved
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the partner associated with the transaction
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the transaction belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST 'https://api.tolt.com/v1/transactions' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "amount": 9999,
      "customer_id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
      "billing_type": "subscription",
      "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
      "click_id": "clk_7mbzRGn46BhVgNFHD6fDgXW",
      "product_id": "prod_123",
      "product_name": "Premium Plan",
      "source": "stripe",
      "interval": "month",
      "created_at": "2025-01-15T14:30:00.000Z"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "txn_eK9bzRGn46BhVgNFHD6fDgXW",
        "status": "paid",
        "amount": 14999,
        "amount_excluding_tax": null,
        "tax": null,
        "currency": "USD",
        "payment_currency": "USD",
        "payment_amount": null,
        "payment_amount_excluding_tax": null,
        "payment_tax": null,
        "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
        "metadata": null,
        "source": "stripe",
        "partner_id": "d30a0807-a0f0-44fc-a38e-2c3a1f640f07",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "click_id": "clk_7mbzRGn46BhVgNFHD6fDgXW",
        "customer_id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
        "created_at": "2025-04-25T09:35:53.025Z",
        "updated_at": "2025-04-25T09:36:10.740Z",
        "amount_including_tax": null,
        "payment_amount_including_tax": null,
        "product_ids": [],
        "interval": "year",
        "billing_type": "subscription",
        "product_names": [],
        "conversion_rate": null
      }
    ]
  }
  ```
</ResponseExample>


# Delete Transaction
Source: https://docs.tolt.com/transactions/delete

DELETE https://api.tolt.com/v1/transactions/:id
This endpoint deletes a transaction.

## Base URL `https://api.tolt.com`

<br />

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the deleted transaction
    </ResponseField>

    <ResponseField name="deleted" type="boolean">
      Indicates that the transaction was deleted
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X DELETE 'https://api.tolt.com/v1/transactions/txn_eK9bzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": {
      "id": "txn_eK9bzRGn46BhVgNFHD6fDgXW",
      "deleted": true
    }
  }
  ```
</ResponseExample>


# List Transactions
Source: https://docs.tolt.com/transactions/list

GET https://api.tolt.com/v1/transactions
This endpoint lists all transactions.

## Base URL `https://api.tolt.com`

<br />

### Query Parameters

<ParamField type="string">
  The program ID from where you want to list the transactions
</ParamField>

<ParamField type="string - optional">
  Only return transactions from this partner
</ParamField>

<ParamField type="string - optional">
  Only return transactions for this customer
</ParamField>

<ParamField type="asc | desc - optional">
  The order of the transactions to return by created\_at. Default is desc
</ParamField>

<ParamField type="array - optional">
  Specify which related objects to include in the response. Valid values are
  **'customer'**, **'program'**, and **'partner'**. Use **expand\[]=customer**,
  **expand\[]=program**, or **expand\[]=partner** to include the related objects.
</ParamField>

<ParamField type="string - optional">
  Only return transactions created after this date
</ParamField>

<ParamField type="string - optional">
  Only return transactions created before this date
</ParamField>

<ParamField type="string - optional">
  A limit on the number of transactions to return. Default is 10, max is 100
</ParamField>

<ParamField type="string - optional">
  A cursor for use in pagination. starting\_after is an object ID that defines
  your place in the list
</ParamField>

<ParamField type="string - optional">
  A cursor for use in pagination. ending\_before is an object ID that defines
  your place in the list
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether there are more pages of results available
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of transactions matching the query
</ResponseField>

<ResponseField name="data" type="array[Object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the transaction
    </ResponseField>

    <ResponseField name="amount" type="number">
      Transaction amount in cents
    </ResponseField>

    <ResponseField name="customer_id" type="string">
      ID of the associated customer
    </ResponseField>

    <ResponseField name="billing_type" type="string | null">
      The billing type
    </ResponseField>

    <ResponseField name="charge_id" type="string">
      Associated charge identifier
    </ResponseField>

    <ResponseField name="click_id" type="string">
      Associated click identifier
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of update
    </ResponseField>

    <ResponseField name="source" type="string">
      Source of the transaction
    </ResponseField>

    <ResponseField name="interval" type="string">
      Subscription interval
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the transaction belongs to
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the referring partner
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/transactions?program_id=prg_YRsbPDAKhWfdqJbFACheh' \
  -H 'Authorization: Bearer <API_KEY>'
  ```

  ```bash With Expand theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/transactions?program_id=prg_YRsbPDAKhWfdqJbFACheh&expand[]=customer&expand[]=program&expand[]=partner' \
  -H 'Authorization: Bearer <API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "has_more": true,
    "total_count": 45,
    "data": [
      {
        "id": "txn_eK9bzRGn46BhVgNFHD6fDgXW",
        "amount": 9999,
        "customer_id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
        "billing_type": "subscription",
        "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
        "click_id": "clk_7mbzRGn46BhVgNFHD6fDgXW",
        "product_id": "prod_123",
        "product_name": "Premium Plan",
        "source": "stripe",
        "interval": "month",
        "created_at": "2025-01-15T14:30:00.000Z",
        "updated_at": "2025-01-15T14:30:00.000Z",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "partner_id": "part_JE3jbmkL9ci7sFaJazAv2"
      }
    ]
  }
  ```

  ```json Expand Response theme={"system"}
  {
    "success": true,
    "has_more": true,
    "total_count": 45,
    "data": [
      {
        "id": "txn_eK9bzRGn46BhVgNFHD6fDgXW",
        "amount": 9999,
        "customer_id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
        "billing_type": "subscription",
        "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
        "click_id": "clk_7mbzRGn46BhVgNFHD6fDgXW",
        "source": "stripe",
        "interval": "month",
        "created_at": "2025-01-15T14:30:00.000Z",
        "updated_at": "2025-01-15T14:30:00.000Z",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "partner_id": "part_JE3jbmkL9ci7sFaJazAv2",
        "customer": {
          "id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
          "email": "cust_123",
          "name": "Jim Halpert",
          "status": "active",
          "created_at": "2025-01-15T14:30:00.000Z"
        },
        "program": {
          "id": "prg_YRsbPDAKhWfdqJbFACheh",
          "status": "active",
          "name": "Tolt's Partnership Program",
          "product_name": "Tolt",
          "subdomain": "affiliates",
          "type": "public",
          "currency_code": "USD",
          "created_at": "2024-03-05T10:28:08.984+00:00"
        },
        "partner": {
          "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
          "first_name": "Michael",
          "last_name": "Scott",
          "email": "michael.scott@dundermifflin.com",
          "company_name": "Dunder Mifflin",
          "status": "active",
          "created_at": "2025-01-13T10:06:11.251Z"
        }
      }
    ]
  }
  ```
</ResponseExample>


# Refund Transaction
Source: https://docs.tolt.com/transactions/refund

PUT https://api.tolt.com/v1/transactions/:id/refund
This endpoint refunds a transaction.

## Base URL `https://api.tolt.com`

<br />

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array[object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the transaction
    </ResponseField>

    <ResponseField name="amount" type="number">
      Transaction amount in cents
    </ResponseField>

    <ResponseField name="customer_id" type="string">
      ID of the associated customer
    </ResponseField>

    <ResponseField name="billing_type" type="string">
      The billing type
    </ResponseField>

    <ResponseField name="amount_excluding_tax" type="number | null">
      Transaction amount excluding tax in cents
    </ResponseField>

    <ResponseField name="amount_including_tax" type="number | null">
      Transaction amount including tax in cents
    </ResponseField>

    <ResponseField name="tax" type="number | null">
      Tax amount in cents
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code for the transaction amount
    </ResponseField>

    <ResponseField name="payment_currency" type="string">
      Currency used for the payment
    </ResponseField>

    <ResponseField name="payment_amount" type="number | null">
      Payment amount in cents
    </ResponseField>

    <ResponseField name="payment_amount_excluding_tax" type="number | null">
      Payment amount excluding tax in cents
    </ResponseField>

    <ResponseField name="payment_amount_including_tax" type="number | null">
      Payment amount including tax in cents
    </ResponseField>

    <ResponseField name="payment_tax" type="number | null">
      Payment tax amount in cents
    </ResponseField>

    <ResponseField name="charge_id" type="string">
      Associated charge identifier
    </ResponseField>

    <ResponseField name="click_id" type="string">
      Associated click identifier
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="source" type="string">
      Source of the transaction
    </ResponseField>

    <ResponseField name="status" type="string">
      Status of the transaction
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Optional metadata
    </ResponseField>

    <ResponseField name="interval" type="string">
      Subscription interval
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>

    <ResponseField name="product_ids" type="array[string]">
      List of product identifiers associated with the transaction
    </ResponseField>

    <ResponseField name="product_names" type="array[string] | null">
      List of product names associated with the transaction
    </ResponseField>

    <ResponseField name="conversion_rate" type="number | null">
      Conversion rate if currency conversion is involved
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the partner associated with the transaction
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the transaction belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X PUT 'https://api.tolt.com/v1/transactions/txn_eK9bzRGn46BhVgNFHD6fDgXW/refund' \
  -H 'Authorization: Bearer <API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "txn_eK9bzRGn46BhVgNFHD6fDgXW",
        "status": "refunded",
        "amount": 14999,
        "amount_excluding_tax": null,
        "tax": null,
        "currency": "USD",
        "payment_currency": "USD",
        "payment_amount": null,
        "payment_amount_excluding_tax": null,
        "payment_tax": null,
        "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
        "metadata": null,
        "source": "stripe",
        "partner_id": "d30a0807-a0f0-44fc-a38e-2c3a1f640f07",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "click_id": "clk_7mbzRGn46BhVgNFHD6fDgXW",
        "customer_id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
        "created_at": "2025-04-25T09:35:53.025Z",
        "updated_at": "2025-04-25T09:36:10.740Z",
        "amount_including_tax": null,
        "payment_amount_including_tax": null,
        "product_ids": [],
        "interval": "year",
        "billing_type": "subscription",
        "product_names": [],
        "conversion_rate": null
      }
    ]
  }
  ```
</ResponseExample>


# Retrieve Transaction
Source: https://docs.tolt.com/transactions/retrieve

GET https://api.tolt.com/v1/transactions/:id
This endpoint retrieves a transaction.

## Base URL `https://api.tolt.com`

<br />

### Query Parameters

<ParamField type="array - optional">
  Specify which related objects to include in the response. Valid values are
  **'customer'**, **'program'**, and **'partner'**. Use **expand\[]=customer**,
  **expand\[]=program**, or **expand\[]=partner** to include the related objects.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the transaction
    </ResponseField>

    <ResponseField name="amount" type="number">
      Transaction amount in cents
    </ResponseField>

    <ResponseField name="customer_id" type="string">
      ID of the associated customer
    </ResponseField>

    <ResponseField name="billing_type" type="string">
      The billing type
    </ResponseField>

    <ResponseField name="charge_id" type="string">
      Associated charge identifier
    </ResponseField>

    <ResponseField name="click_id" type="string">
      Associated click identifier
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="source" type="string">
      Source of the transaction
    </ResponseField>

    <ResponseField name="interval" type="string">
      Subscription interval
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the transaction belongs to
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      Unique identifier for the partner
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/transactions/txn_eK9bzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>'
  ```

  ```bash With Expand theme={"system"}
  curl -X GET 'https://api.tolt.com/v1/transactions/txn_eK9bzRGn46BhVgNFHD6fDgXW?expand[]=customer&expand[]=program&expand[]=partner' \
  -H 'Authorization: Bearer <API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": {
      "id": "txn_eK9bzRGn46BhVgNFHD6fDgXW",
      "amount": 9999,
      "customer_id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
      "billing_type": "subscription",
      "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
      "click_id": "clk_7mbzRGn46BhVgNFHD6fDgXW",
      "source": "stripe",
      "interval": "month",
      "created_at": "2025-01-15T14:30:00.000Z",
      "updated_at": "2025-01-15T14:30:00.000Z",
      "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
      "partner_id": "part_ER3mfYNL9ci7sFaJazAv2"
    }
  }
  ```

  ```json Expand Response theme={"system"}
  {
    "success": true,
    "data": {
      "id": "txn_eK9bzRGn46BhVgNFHD6fDgXW",
      "amount": 9999,
      "customer_id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
      "billing_type": "subscription",
      "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
      "click_id": "clk_7mbzRGn46BhVgNFHD6fDgXW",
      "product_id": "prod_123",
      "product_name": "Premium Plan",
      "source": "stripe",
      "interval": "month",
      "created_at": "2025-01-15T14:30:00.000Z",
      "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
      "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
      "customer": {
        "id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
        "email": "cust_123",
        "name": "Jim Halpert",
        "status": "active",
        "created_at": "2025-01-15T14:30:00.000Z"
      },
      "program": {
        "id": "prg_YRsbPDAKhWfdqJbFACheh",
        "status": "active",
        "name": "Tolt's Partnership Program",
        "product_name": "Tolt",
        "subdomain": "affiliates",
        "type": "public",
        "currency_code": "USD",
        "created_at": "2024-03-05T10:28:08.984+00:00"
      },
      "partner": {
        "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "first_name": "Michael",
        "last_name": "Scott",
        "email": "michael.scott@dundermifflin.com",
        "company_name": "Dunder Mifflin",
        "status": "active",
        "created_at": "2025-01-13T10:06:11.251Z"
      }
    }
  }
  ```
</ResponseExample>


# Update Transaction
Source: https://docs.tolt.com/transactions/update

PUT https://api.tolt.com/v1/transactions/:id
This endpoint updates a transaction.

## Base URL `https://api.tolt.com`

<br />

### Body Parameters

<ParamField type="number - optional">
  The transaction amount in cents
</ParamField>

<ParamField type="string - optional">
  The billing type. Valid values are: **'one\_time'** or **'subscription'**
</ParamField>

<ParamField type="string - optional">
  Associated charge identifier
</ParamField>

<ParamField type="string - optional">
  Associated click identifier
</ParamField>

<ParamField type="string - optional">
  ISO 8601 timestamp of when the transaction was created
</ParamField>

<ParamField type="string - optional">
  The ID of the product associated with this transaction
</ParamField>

<ParamField type="string - optional">
  The name of the product associated with this transaction
</ParamField>

<ParamField type="string - optional">
  Source of the transaction
</ParamField>

<ParamField type="string - optional">
  For subscription billing type. Valid values are: **'month'** or **'year'**
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array[object]">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the transaction
    </ResponseField>

    <ResponseField name="amount" type="number">
      Transaction amount in cents
    </ResponseField>

    <ResponseField name="customer_id" type="string">
      ID of the associated customer
    </ResponseField>

    <ResponseField name="billing_type" type="string">
      The billing type
    </ResponseField>

    <ResponseField name="amount_excluding_tax" type="number | null">
      Transaction amount excluding tax in cents
    </ResponseField>

    <ResponseField name="amount_including_tax" type="number | null">
      Transaction amount including tax in cents
    </ResponseField>

    <ResponseField name="tax" type="number | null">
      Tax amount in cents
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code for the transaction amount
    </ResponseField>

    <ResponseField name="payment_currency" type="string">
      Currency used for the payment
    </ResponseField>

    <ResponseField name="payment_amount" type="number | null">
      Payment amount in cents
    </ResponseField>

    <ResponseField name="payment_amount_excluding_tax" type="number | null">
      Payment amount excluding tax in cents
    </ResponseField>

    <ResponseField name="payment_amount_including_tax" type="number | null">
      Payment amount including tax in cents
    </ResponseField>

    <ResponseField name="payment_tax" type="number | null">
      Payment tax amount in cents
    </ResponseField>

    <ResponseField name="charge_id" type="string">
      Associated charge identifier
    </ResponseField>

    <ResponseField name="click_id" type="string">
      Associated click identifier
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="source" type="string">
      Source of the transaction
    </ResponseField>

    <ResponseField name="status" type="string">
      Status of the transaction
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Optional metadata
    </ResponseField>

    <ResponseField name="interval" type="string">
      Subscription interval
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>

    <ResponseField name="product_ids" type="array[string]">
      List of product identifiers associated with the transaction
    </ResponseField>

    <ResponseField name="product_names" type="array[string] | null">
      List of product names associated with the transaction
    </ResponseField>

    <ResponseField name="conversion_rate" type="number | null">
      Conversion rate if currency conversion is involved
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the partner associated with the transaction
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the transaction belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X PUT 'https://api.tolt.com/v1/transactions/txn_eK9bzRGn46BhVgNFHD6fDgXW' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "amount": 14999,
      "billing_type": "subscription",
      "product_name": "Premium Plan Plus",
      "interval": "year"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "txn_eK9bzRGn46BhVgNFHD6fDgXW",
        "status": "paid",
        "amount": 14999,
        "amount_excluding_tax": null,
        "tax": null,
        "currency": "USD",
        "payment_currency": "USD",
        "payment_amount": null,
        "payment_amount_excluding_tax": null,
        "payment_tax": null,
        "charge_id": "ch_9bzRGn46BhVgNFHD6fDgXW",
        "metadata": null,
        "source": "stripe",
        "partner_id": "d30a0807-a0f0-44fc-a38e-2c3a1f640f07",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "click_id": "clk_7mbzRGn46BhVgNFHD6fDgXW",
        "customer_id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
        "created_at": "2025-04-25T09:35:53.025Z",
        "updated_at": "2025-04-25T09:36:10.740Z",
        "amount_including_tax": null,
        "payment_amount_including_tax": null,
        "product_ids": [],
        "interval": "year",
        "billing_type": "subscription",
        "product_names": [],
        "conversion_rate": null
      }
    ]
  }
  ```
</ResponseExample>