# Lead Track
Source: https://docs.cutmeshort.com/api-reference/endpoint/Lead

Understand deferred and non-deferred lead tracking with practical payload examples and implementation tips.

## What is a Lead Event?

Lead events help you:

* **Attribute leads** to the correct source and campaign
* **Understand journey quality** across different traffic channels
* **Improve ROI reporting** by linking verified actions to ad spend

Common lead events include:

| Event                | Description                            |
| -------------------- | -------------------------------------- |
| `signup_started`     | User registers for an account          |
| `onboarding_started` | User begins the onboarding flow        |
| `demo_booked`        | User schedules a product demo          |
| `info_requested`     | User submits a contact or inquiry form |

<img alt="Lead event attribution flow" />

## Tracking Modes

There are two supported approaches. Choose based on whether your signup flow includes a verification step.

### Non-Deferred Tracking

Use this when you can **immediately trust** the lead action and no verification is needed.

* Send a **single event** right away
* Include `clickId` and `customerExternalId`
* Attribution is established immediately

### Deferred Tracking

Use this when **verification is required** before finalizing the lead (e.g., email or phone confirmation).

* Send **two events** — one before and one after verification
* Use `mode: "deferred"` on the first event
* Both events are linked via a shared `customerExternalId`

<Tip>
  **When in doubt, use deferred tracking.** It's safer to hold a lead open until verified than to count unconfirmed signups as conversions.
</Tip>

<img alt="Deferred Lead event attribution flow" />

### Event 1 - Before Verification

Send this immediately when the user initiates signup.

<Tip>
  `clickId` is a unique identifier stored in cookies when our script detects `cms_rf` in the URL. See [article](/api-reference/endpoint/field) to know more.
</Tip>

**Required fields:**

* `clickId` — establishes attribution
* `mode: "deferred"` — marks this lead as pending
* `customerExternalId` — stable unique ID for the user

**Optional but recommended:**

* `customerName`, `customerEmail`, `customerAvatar` — enriches analytics

### Event 2 - After Verification

Send this once the user completes the verification step.

**Required fields:**

* `customerExternalId` — must match Event 1 exactly
* `eventName` — describes the verification action (e.g. `email_verified`)

<Warning>
  **Do not include `clickId` in Event 2.** Sending it again will cause duplicate attribution errors. The second event only links back to the first via `customerExternalId`.
</Warning>

## Payloads

### Non-Deferred Lead

A single event when no verification step is required.

```json theme={null}
{
  "clickId": "id_123",
  "eventName": "signup_started",
  "customerExternalId": "user_42",
  "timestamp": "2024-01-15T10:30:00Z",
  "customerName": "John Doe",
  "customerEmail": "john@example.com"
}
```

### Deferred Lead — Event 1 (Before Verification)

Initiates deferred lead tracking. Attribution is locked to the `clickId` here.

```json theme={null}
{
  "clickId": "id_123",
  "mode": "deferred",
  "eventName": "signup_started",
  "customerExternalId": "user_42",
  "timestamp": "2024-01-15T10:30:00Z",
  "customerName": "John Doe",
  "customerEmail": "john@example.com"
}
```

<Tip>
  Add user details (`customerName`, `customerEmail`) in this first event. They will be attached to the lead even before verification completes.
</Tip>

### Deferred Lead Event 2 (After Verification)

Confirms the lead. Must use the same `customerExternalId` as Event 1.

```json theme={null}
{
  "eventName": "email_verified",
  "customerExternalId": "user_42"
}
```

<Warning>
  The `customerExternalId` in Event 2 **must exactly match** the value sent in Event 1. Any mismatch will break the attribution chain and result in an unlinked lead.
</Warning>

## Fields

| Field                | Required           | Notes                                                          |
| -------------------- | ------------------ | -------------------------------------------------------------- |
| `clickId`            | Yes (Event 1 only) | Establishes attribution. Never re-send in follow-up events.    |
| `customerExternalId` | Yes (all events)   | Must be stable and consistent across the full user journey.    |
| `eventName`          | Yes (all events)   | Use descriptive names like `signup_started`, `email_verified`. |
| `mode`               | Deferred only      | Set to `"deferred"` on the first event of a deferred flow.     |
| `timestamp`          | Recommended        | ISO 8601 format. Improves sequencing and debugging.            |
| `customerName`       | Optional           | Enriches lead data in your analytics dashboard.                |
| `customerEmail`      | Optional           | Enriches lead data in your analytics dashboard.                |


# Sale Track
Source: https://docs.cutmeshort.com/api-reference/endpoint/Sale

Understand sale attribution with practical payload examples and implementation.

## What is a Sale Event?

Sale events help you:

* **Attribute revenue** to the correct source and campaign
* **Measure conversion quality** across traffic channels
* **Connect lead-to-sale journeys** so you can see which leads actually became customers

<img alt="Sale event attribution flow" />

***

Common sale events include:

| Event                  | Description                         |
| ---------------------- | ----------------------------------- |
| `checkout_completed`   | User finishes a successful purchase |
| `subscription_created` | Paid plan starts after checkout     |
| `payment_captured`     | Payment is confirmed on the server  |
| `order_paid`           | Order moves from pending to paid    |

## Tracking Flow

Sale tracking is usually a single revenue event that you send once the payment is confirmed.

* Send the event **after the purchase is successful**
* Include the same stable identifiers used in your lead flow
* Pass revenue fields like `amount`, `currency`, and an invoice identifier

<img alt="Sale event attribution flow" />

<Tip>
  **clickId** is optional for sale tracking
</Tip>

### What to send

**Required fields:**

* `customerExternalId` — stable identifier for the customer
* `amount` — revenue value for the sale
* `invoiceId` — helps deduplicate retries and repeated submissions

**Strongly recommended:**

* `event` — should describe the purchase action, such as `sale`
* `currency` — currency code such as `USD` or `EUR`
* `timestamp` — improves sequencing and debugging

**Optional but useful:**

* `email`, `name`, `clickId` — enriches identity matching

## How Sale Attribution Works

Sale attribution works by matching the purchase event back to the original traffic source.

1. A user clicks a tracked link and receives a `clickId`.
2. The user later becomes a lead or customer using the same stable identifier.
3. When the payment succeeds, you send the sale event with the same `customerExternalId` and the original `clickId`.
4. The platform ties the revenue to the source that initiated the journey.

<Warning>
  **Do not generate a new customer identifier at sale time.** If the sale event uses a different `customerExternalId`, the attribution chain can break and revenue may not connect to the original lead.
</Warning>

## Payload

A single revenue event after payment is confirmed.

```json theme={null}
{
  "event": "sale",
  "timestamp": "2026-04-10T12:45:10.000Z",
  "customerExternalId": "user_123",
  "email": "alex@example.com",
  "name": "Alex Johnson",
  "currency": "USD",
  "amount": 199.0,
  "invoiceId": "inv_987"
}
```

<Tip>
  **All revenue is normalized to USD.**

  * If `currency` is not provided, the system assumes the `amount` is in USD.
  * If `currency` is provided (e.g., `INR`, `CNY`, `EUR`), the amount is automatically converted to USD before storage and reporting.
  * Currency conversions are performed using the **current day’s exchange rate**.
</Tip>

## Fields

| Field                | Required    | Notes                                                 |
| -------------------- | ----------- | ----------------------------------------------------- |
| `event`              | Yes         | Use a purchase-oriented name such as `sale`.          |
| `customerExternalId` | Yes         | Stable customer identifier used across lead and sale. |
| `amount`             | Yes         | Revenue amount for the sale.                          |
| `currency`           | Yes         | ISO currency code such as `USD`, `EUR`, or `INR`.     |
| `invoiceId`          | Recommended | Helps prevent duplicate revenue records.              |
| `timestamp`          | Recommended | ISO 8601 format is preferred.                         |
| `clickId`            | Optional    | Useful for enriching data.                            |
| `email`              | Optional    | Useful for identity matching and reporting.           |
| `name`               | Optional    | Useful for enriching customer data.                   |


# First-Click vs Last-Click
Source: https://docs.cutmeshort.com/api-reference/endpoint/clickattribution

Understand how cms_rf cookie attribution works, the difference between first-click and last-click models, and which one is right for your tracking strategy.

## What is Attribution?

When a user visits your site, they rarely come from a single source. They might discover your product through a Google Ad, leave, come back from an email campaign, and finally convert through a direct visit. **Attribution** is how you decide which of those touchpoints gets the credit for the conversion.

The CMS script’s `cms_rf` parameter-based cookie system is a lightweight, first-party implementation of this concept no third-party dependencies, no cross-domain complexity, just clean URL-parameter tracking stored directly in the browser.

<Note>
  The CMS script uses <strong>last-click attribution</strong> by default.
</Note>

## How the `cms_rf` Cookie System Works

On page load, the CMS script checks the URL for the `cms_rf` parameter. If present, it runs attribution logic that either sets the cookie for the first time or updates an existing value.

<Steps>
  <Step title="User arrives on site">
    The user clicks a link with `?cms_rf=google_cpc` appended to the URL (e.g., from a paid ad, email, or affiliate link).
  </Step>

  <Step title="Script detects cms_rf">
    The CMS script reads the `cms_rf` value from url on page load.
  </Step>

  <Step title="Cookie logic runs">
    Based on the attribution model, the script either **sets** the cookie (if not set) or **overwrites** it (if already set).
  </Step>

  <Step title="Cookie is sent with conversion">
    When the user completes a conversion event, the `cms_rf` cookie value is read and passed along to your analytics or CRM system.
  </Step>
</Steps>

<Note>
  The `cms_rf` cookie is a **first-party cookie**, which means it lives in the user's browser under your own domain. This makes it more reliable than third-party tracking pixels in an era of increasing browser privacy restrictions (Safari ITP, Firefox ETP, etc.).
</Note>

## First-Click Attribution

In **first-click**, the first touchpoint that introduced the user is retained. Once the `cms_rf` cookie is set, it is **not overwritten** even if the user returns later with a different `cms_rf` value.

### Example scenario

| Visit | URL Parameter             | Cookie Value (First-Click) |
| ----- | ------------------------- | -------------------------- |
| 1st   | `cms_rf=google_cpc`       | `google_cpc` ✅ Set         |
| 2nd   | `cms_rf=email_newsletter` | `google_cpc` 🔒 Locked     |
| 3rd   | `cms_rf=referral_partner` | `google_cpc` 🔒 Locked     |

<Tip>
  First-click is most useful when the initial discovery channel is the signal you want to report on (often longer consideration cycles like SaaS, B2B, or high-ticket products).
</Tip>

### When to use First-Click

* You want to understand what **drives awareness** and top-of-funnel traffic.
* You want credit to remain with the first recorded source across return visits.
* Your customer journey typically spans multiple sessions before conversion.

## Last-Click Attribution

In **last-click**, the most recent touchpoint is retained. Every time a user arrives with a new `cms_rf` value, the cookie is overwritten. So the stored value reflects the last channel seen before converting.

### Example scenario

| Visit | URL Parameter             | Cookie Value (Last-Click)     |
| ----- | ------------------------- | ----------------------------- |
| 1st   | `cms_rf=google_cpc`       | `google_cpc` ✅ Set            |
| 2nd   | `cms_rf=email_newsletter` | `email_newsletter` 🔄 Updated |
| 3rd   | `cms_rf=referral_partner` | `referral_partner` 🔄 Updated |

<Tip>
  Last-click is most useful when the final converting touchpoint is the signal you want to report on (often performance and conversion-focused workflows).
</Tip>

### When to use Last-Click

* You want to know what **closes deals** and drives final conversions.
* You want the attribution value to reflect the most recent recorded source before conversion.
* Your customer journey is short and straightforward.

## Which Model is Better?

There’s no universally “better” model. Each answers a different question.

<Tabs>
  <Tab title="First-Click">
    * Your primary marketing goal is **brand discovery and awareness**
    * You run significant spend on top-of-funnel channels (paid search, content, social) and need to justify ROI
    * Your conversion cycle is **30+ days**
    * You're trying to understand what channel to invest in to grow your audience
  </Tab>

  <Tab title="Last-Click">
    * Your primary goal is **conversion optimization**
    * You run retargeting, promotional email, or affiliate campaigns that directly push users to convert
    * Your conversion cycle is **long**
    * You're a performance marketer who needs to optimize channel spend by conversion volume
  </Tab>
</Tabs>

## Summary

| Type                       | First-Click           | Last-Click           |
| -------------------------- | --------------------- | -------------------- |
| **Cookie set**             | Once only             | Every new `cms_rf`   |
| **Cookie overwritten**     | Never                 | Always               |
| **Credits**                | Original source       | Most recent source   |
| **Best signal**            | Awareness & discovery | Conversion & closing |
| **Cookie expiry strategy** | Longer (60–90 days)   | Longer (60–90 days)  |
| **Complexity**             | Low                   | Low                  |

Both models are simple, privacy-friendly, and effective when used for the right purpose. The most important thing is to **choose deliberately** based on your analytics goals and document which model is active so your team interprets the data correctly.


# Create Domain
Source: https://docs.cutmeshort.com/api-reference/endpoint/createCustomDomain

post /customDomain
Connect a new domain for the authenticated workspace.



# Create Link
Source: https://docs.cutmeshort.com/api-reference/endpoint/createLink

post /link
Create a new link for the authenticated workspace.



# Create Tag
Source: https://docs.cutmeshort.com/api-reference/endpoint/createTag

post /tag
Create a new tag for the authenticated workspace.



# Delete Custom domain
Source: https://docs.cutmeshort.com/api-reference/endpoint/deleteCustomDomain

patch /customDomain
Update settings or delete a domain for the authenticated workspace.



# Delete Link
Source: https://docs.cutmeshort.com/api-reference/endpoint/deleteLink

patch /link
Update tags or delete a link for the authenticated workspace.



# Field Reference
Source: https://docs.cutmeshort.com/api-reference/endpoint/field

Complete reference for attribution, conversion, and user detail fields used in lead and sale tracking.

## Attribution Fields

These fields form the backbone of click-to-conversion tracking. They tell CutMeShort *where* a conversion came from and *who* made it.

### `clickId`

<Warning>
  Never generate your own `clickId`. Always reuse the value created by the tracking script.
</Warning>

The click-level attribution identifier — the unique fingerprint of the original tracked click.

| Property    | Detail                                                                         |
| ----------- | ------------------------------------------------------------------------------ |
| **Source**  | CutMeShort captures it when the script detects `cms_rf` in the URL             |
| **Storage** | Persisted in cookies by the tracking script for later reuse                    |
| **Usage**   | Pass in lead and sale events to link conversions back to the originating click |

### `customerExternalId`

<Warning>
  Do not create a new value at sale time or in follow-up lead events. Use the same identifier across all events for the same customer.
</Warning>

Your stable customer identifier — the consistent key that connects a customer's journey end-to-end.

| Property    | Detail                                                         |
| ----------- | -------------------------------------------------------------- |
| **Source**  | Your application, auth system, CRM, or backend user record     |
| **Usage**   | Keep it unchanged across lead and sale events                  |
| **Purpose** | Allows CutMeShort to stitch the full customer journey together |

### `eventName`

A human-readable label describing the lead milestone being recorded.

| Property     | Detail                                                                  |
| ------------ | ----------------------------------------------------------------------- |
| **Examples** | `signup_started`, `email_verified`, `purchase_completed`                |
| **Source**   | Your product logic or event naming convention                           |
| **Usage**    | Send a meaningful name that describes exactly what lead action occurred |

### `mode`

> **Deferred lead flows only.** Only use this on the initial event of a deferred tracking sequence.

A flag that controls how lead attribution is recorded when you need to defer tracking.

| Property        | Detail                                                               |
| --------------- | -------------------------------------------------------------------- |
| **Valid value** | `"deferred"`                                                         |
| **Source**      | Set by your app when you intentionally want deferred tracking        |
| **Usage**       | Set to `"deferred"` for the first event in a deferred lead flow only |

## Conversion Fields

These fields carry the financial and transactional data for a sale event.

### `amount`

The monetary value associated with the sale.

| Property   | Detail                                                                    |
| ---------- | ------------------------------------------------------------------------- |
| **Source** | Your payment provider, checkout session, order record, or billing backend |
| **Usage**  | Send the final sale amount for the conversion being attributed            |

<Warning>
  Make sure the value matches the currency you send alongside it.
</Warning>

### `currency`

The ISO 4217 currency code for the sale amount.

| Property   | Detail                                       |
| ---------- | -------------------------------------------- |
| **Format** | 3-letter ISO code — e.g. `USD`, `EUR`, `INR` |
| **Source** | Your billing or checkout system              |
| **Usage**  | Always pair with the `amount` field          |

<Warning>
  Keep the code consistent with the actual transaction currency to ensure accurate revenue reporting.
</Warning>

### `invoiceId`

The unique transaction or order reference for a sale.

| Property      | Detail                                                               |
| ------------- | -------------------------------------------------------------------- |
| **Source**    | Your payment processor, order table, or billing system               |
| **Usage**     | Use to deduplicate repeated submissions and reconcile revenue events |
| **Stability** | Must remain the same for the same transaction                        |

## User Detail Fields

These fields are **optional enrichment data**. They don't drive attribution, but they make lead and sale records significantly more useful in analytics and reporting.

### `customerName`

The customer's full display name.

| Property   | Detail                                                    |
| ---------- | --------------------------------------------------------- |
| **Source** | Signup form, profile record, CRM, or auth provider        |
| **Usage**  | Send when you have a reliable, user-facing name available |

### `customerEmail`

The email address associated with the lead or customer.

| Property   | Detail                                                                    |
| ---------- | ------------------------------------------------------------------------- |
| **Source** | Signup form, login flow, or profile record                                |
| **Usage**  | Include when available to improve identity matching and reporting quality |

## Quick Reference

| Field                | Type     | Required    | Used In          |
| -------------------- | -------- | ----------- | ---------------- |
| `clickId`            | `string` | Recommended | Leads, Sales     |
| `customerExternalId` | `string` | Recommended | Leads, Sales     |
| `eventName`          | `string` | Required    | Leads, Sales     |
| `mode`               | `string` | Conditional | Leads (deferred) |
| `amount`             | `number` | Required    | Sales            |
| `currency`           | `string` | Required    | Sales            |
| `invoiceId`          | `string` | Recommended | Sales            |
| `customerName`       | `string` | Optional    | Leads, Sales     |
| `customerEmail`      | `string` | Optional    | Leads, Sales     |

## Related Docs

* [Lead Track](/api-reference/endpoint/Lead)
* [Sale Track](/api-reference/endpoint/Sale)


# Retrieve a list of domains
Source: https://docs.cutmeshort.com/api-reference/endpoint/getCustomDomains

get /customDomain
Returns all domains in a workspace with filter support and pagination



# Retrieve link analytics
Source: https://docs.cutmeshort.com/api-reference/endpoint/getLinkDetails

get /link/{linkId}/{workspaceId}
Get analytics for a link



# Retrieve a list of links
Source: https://docs.cutmeshort.com/api-reference/endpoint/getLinks

get /link
Returns all links in a workspace with filter support and pagination



# Retrieve a list of tags
Source: https://docs.cutmeshort.com/api-reference/endpoint/getTags

get /tag
Returns all tags in a workspace



# Update Domain settings
Source: https://docs.cutmeshort.com/api-reference/endpoint/updateCustomDomain

patch /customDomain
Update settings or delete a domain for the authenticated workspace.



# Update Link tags
Source: https://docs.cutmeshort.com/api-reference/endpoint/updateLink

patch /link
Update tags or delete a link for the authenticated workspace.



# Getting Started
Source: https://docs.cutmeshort.com/api-reference/introduction

Understanding the basics of CutMe Short's API.

<Note>
  Please note that CutMe Short's API is currently in beta. We welcome any
  questions or feedback you may have. Feel free to reach out to us at
  [support@cutmeshort.com](mailto:support@cutmeshort.com?subject=CutMeShort%20API%20Feedback).
</Note>

## Base URL

The CutMe Short API is built on REST principles and is served over HTTPS.

The Base URL for all API endpoints is:

```bash Terminal theme={null}
https://api.cme.sh
```

## Authentication

To access CutMe Short's API, you need to authenticate using a Bearer token. Include the token in the Authorization header of your API requests like this:

```bash Terminal theme={null}
Authorization: Bearer <Your-Token>
```

You can generate a new token/API key under your [Account Settings](https://app.cutmeshort.com).

<Frame>
  <img alt="Hero Light" />
</Frame>

## Workspace ID

CutMe Short's API is organized around workspaces. To access a workspace's resources, include the workspaceId parameter in your API requests either in the query param or request body:

```bash Terminal theme={null}
https://api.cme.sh/links?workspaceId=<Your-Workspace-ID>
```

You can get your workspace ID under your Settings.

<Frame>
  <img alt="Hero Light" />
</Frame>

## Response Codes

The API returns standard HTTP response codes to indicate the success or failure of an API request. Here are a few examples:

| Code  | Description                                                                                    |
| ----- | ---------------------------------------------------------------------------------------------- |
| `200` | The request was successful.                                                                    |
| `400` | The request was invalid or cannot be served.                                                   |
| `401` | The request requires user authentication.                                                      |
| `403` | The server understood the request, but refuses to authorize it.                                |
| `404` | The requested resource could not be found.                                                     |
| `429` | Too many requests.                                                                             |
| `500` | The server encountered an unexpected condition which prevented it from fulfilling the request. |

## Rate limits

CutMe Short's API enforces a rate limit of **60 requests per minute** per user.

This limitation is in place to promote fair usage and prevent any single user from disproportionately impacting the performance and availability of the API for others.

If you exceed the rate limit, you will receive a 429 Too Many Requests response code. This indicates that your request cannot be processed at the moment due to exceeding the allowed number of requests within the specified timeframe.

## Important Notes

<Info>
  CutMe Short's API is currently in public beta and may be subject to changes.
  However, we are committed to minimizing any breaking changes to the API as
  much as possible. Your feedback is valuable to us as we continue to improve
  our services. Feel free to reach out to us with any questions or concerns.
</Info>


# Advance Analytics
Source: https://docs.cutmeshort.com/features/AdvanceAnalytics

Gain insights and AI-driven recommendations to optimize your digital strategies with CutMeShort

<img />

The Advanced Analytics & AI Recommendations feature within CutMe Short provides users with comprehensive insights into their shortened links, coupled with AI-driven recommendations to optimize their digital strategies. This page serves as a centralized hub for users to access detailed link analytics, including click data, device information, demographic insights, and personalized recommendations tailored to enhance engagement and performance.

## Link Details

The Link Details section offers users a concise overview of their created links, including the short URL, destination URL, and other pertinent information. To enhance user experience, we aim to optimize the presentation of these details by utilizing appealing color schemes and intuitive placements.

<img />

## Link Analytics

The Link Analytics section provides users with interactive selectors to refine their analytics data based on parameters such as date range, geographic location (Country, State, City), and device type. With date range selectors, users can seamlessly navigate through their analytics data with ease.

Within this section, users are presented with scorecard details highlighting key performance metrics, such as total clicks, unique clicks, click-through rate (CTR), and engagement rate, empowering users to gauge the effectiveness of their link campaigns at a glance.

<img />

## Device Information

The Device Information section offers insights into user engagement across different devices and platforms. Users can visualize data related to link opens from various devices, including desktops, mobile devices, and tablets, enabling them to tailor their content to specific device preferences of their audience.

<img />

## Demographic Information

The Demographic Information section provides users with valuable insights into the geographic distribution of their audience. By showcasing data related to link opens from different locations worldwide, users can better understand the demographics of their audience and adjust their targeting strategies accordingly.

<img />

## Click Information

The Click Information section offers detailed insights into user behavior, including click counts and clicks opened at different hours of the day across the world. This data enables users to identify peak engagement times and optimize their content distribution schedules for maximum impact.

<img />

## AI Recommendations

Users can explore AI-driven recommendations based on specific criteria, such as Educational Frontiers, Diverse Growth Districts, and Emerging Development Corridors. By selecting a category from the dropdown menu, users can view a pie chart showcasing click counts for each category, providing valuable insights into audience interests.

Additionally, users can visualize recommendation cities through a tree graph, highlighting top cities with populations aligned with the selected category. For example, selecting "Educational Frontiers" will display cities where users with educational interests are concentrated, enabling users to tailor their content to resonate with these audiences effectively.

<img />

<img />

<img />

<img />

This documentation provides a comprehensive guide to leveraging Advanced Analytics & AI Recommendations with CutMeShort, empowering users to optimize their digital strategies and enhance engagement with their audience.

<Tip>
  Visit [CutMe Short](https://cutmeshort.com) and
  [Signup](https://cutmeshort.com) for free! For any queries drop us an email at
  [support@cutmeshort.com](mailto:support@cutmeshort.com).
</Tip>


# Custom Domain
Source: https://docs.cutmeshort.com/features/CustomDomain

Learn how to add a custom domain to your CutMeShort workspace

<img />

CutMeShort introduces the Custom Domain feature, allowing users to utilize their own branded domain for shortening URLs instead of relying on the default CutMeShort domain. This feature enhances brand consistency and recognition by enabling users to maintain their brand identity throughout their URL shortening process.

## Overview

CutMeShort allows users to add custom domains for shortening URLs. This guide provides step-by-step instructions on how to add and configure a custom domain in your CutMeShort workspace.

### Prerequisites

Before you begin, make sure you have:

* A CutMeShort account. If you don't have one, you can [sign up for free](https://www.app.cutmeshort.com).
* Access to your domain registrar account (e.g., GoDaddy, Namecheap, HostGator) where you can configure DNS settings.

## Step 1: Add a Custom Domain

1. [Log in](https://www.app.cutmeshort.com) to your CutMeShort account.
2. Navigate to the [Domains](https://www.app.cutmeshort.com/custom-domains) section in the dashboard.
3. Click on the "Connect new domain" button.

## Step 2: Configure Domain and Subdomain

In the CutMe Short app, follow these steps to configure your custom domain and subdomain:

1. **Is your domain a spare domain?**

   * If your domain is not currently in use, select "Yes, this domain is currently not in use."
   * If your domain is already in use for your website, blog, or other purposes, select "No."

2. **Choose a name for your subdomain:**
   * Enter the desired subdomain name for your custom URL. For example, "go" for "go.example.com".

## Step 3: Immediate Action Required

<img />

After configuring your custom domain and subdomain, it's important to take immediate action to activate your domain. Follow these steps:

### Mandatory Action

Apply the following DNS settings to your domain registrar's DNS management panel to activate your custom domain:

```
RECORD TYPE       HOST NAME            POINTS TO ADDRESS
A                 @ (or leave empty)   157.230.194.205
```

### Optional Action

If you want to enable the "www" subdomain, apply the following optional DNS settings:

```
RECORD TYPE       HOST NAME            POINTS TO ADDRESS
A                 www (or *)           157.230.194.205
```

<Note>
  **Note:** Ensure that any existing A or AAAA records for your domain are
  removed before applying these settings.
</Note>

### DNS Propagation

Your domain activation may take up to 24-48 hours due to DNS propagation. We'll notify you once the setup is complete.

<Tip>
  Visit [CutMe Short](https://cutmeshort.com) and
  [Signup](https://cutmeshort.com) for free! For any queries drop us an email at
  [support@cutmeshort.com](mailto:support@cutmeshort.com).
</Tip>


# Custom QR codes
Source: https://docs.cutmeshort.com/features/CustomQR

Generate personalized QR codes for your shortened URLs with CutMeShort

<img />

CutMe Short offers users the convenience of Custom QRs, allowing them to generate personalized QR codes for their shortened URLs. This feature is seamlessly integrated into two key areas of the platform: the link creation process and the links listing page. Users can not only view and edit QR codes for their shortened URLs but also customize them with high-quality options such as logo insertion, foreground and background color adjustments, and downloadable formats in PNG and JPEG.

## Link Creation Process

Upon successful creation of a short URL, users are presented with the option to view and edit the associated QR code. This streamlined process enables users to quickly generate QR codes for their links without any additional steps.

Users have the flexibility to customize their QR codes by adding or removing logos, adjusting foreground and background colors, and fine-tuning other visual elements to align with their branding preferences.

## Links Listing Page

In addition to the link creation process, users can also view and edit QR codes directly from the links listing page. This centralized hub allows users to manage their QR codes efficiently, providing easy access to customization options for each shortened URL.

With high-quality QR codes available for every link, users can seamlessly incorporate QR code marketing strategies into their campaigns, enhancing user engagement and interaction with their content.

## Customization Options

* **Logo Insertion**: Personalize QR codes by adding logos or branding elements, reinforcing brand identity and recognition.
* **Color Adjustments**: Customize foreground and background colors of QR codes, ensuring visual consistency with brand aesthetics.
* **Downloadable Formats**: Download customized QR codes in PNG and JPEG formats for versatility in marketing materials and platforms.

## Benefits

* **Enhanced Branding**: Reinforce brand identity and recognition, fostering trust and credibility among the audience.
* **Improved Engagement**: Facilitate seamless interaction between offline and online channels, encouraging user engagement and action.
* **Streamlined Management**: Efficiently manage QR codes and track their performance alongside shortened URLs.
* **Versatile Applications**: Utilize custom QR codes as a versatile marketing tool for various campaigns and channels, including print materials, digital platforms, and offline events.

Experience the convenience and versatility of Custom QRs with CutMe Short, empowering users to elevate their marketing efforts with personalized QR code solutions tailored to their brand and objectives.

<Tip>
  Visit [CutMe Short](https://cutmeshort.com) and
  [Signup](https://cutmeshort.com) for free! For any queries drop us an email at
  [support@cutmeshort.com](mailto:support@cutmeshort.com).
</Tip>


# Link Attribution
Source: https://docs.cutmeshort.com/features/LeadSaleTrackAttribution

Track and attribute leads and sales to your shortened links

## Overview

CutMeShort’s **Lead & Sale Attribution** lets you track every click on your shortened links all the way through to actual leads and sales in real time. See exactly which links, campaigns, and channels drive conversions, so you can measure performance.

<Tip>
  If you use multiple links across channels, keep your UTM parameters consistent. Attribution credits the **last CutMeShort link clicked**, and UTMs let you slice results further by campaign or source in your own analytics tools.
</Tip>

## How it works

```
User clicks short link
        ↓
CutMeShort records the click + stores a tracking ID
        ↓
User converts (signup, purchase, etc.)
        ↓
Conversion is attributed back to the originating link
```

A tracking identifier is captured on click and persisted on the user's browser. When a conversion event fires, we resolve it back to the original click giving you a clear, auditable chain from link → conversion.

## Attribution model

CutMeShort uses **Last Click Attribution**. The industry standard approach for measuring direct-response performance.

### Last click attribution

Full conversion credit goes to the **last CutMeShort link clicked** before a conversion occurs.

```
User journey:  Click Link A  →  Click Link B  →  Purchase
                                      ↑
                              100% credit here
```

| Property     | Details                                    |
| ------------ | ------------------------------------------ |
| **Model**    | Last click                                 |
| **Credit**   | 100% to the final link interaction         |
| **Scope**    | Any CutMeShort shortened link              |
| **Use case** | Direct-response campaigns, email, paid ads |

**Why last click?**

* Captures the final touchpoint that drove action — the closest signal to conversion intent
* Simple to audit: one link, one conversion, clear credit
* Direct mapping between link performance and revenue
* Unaffected by multi-touch complexity in the broader user journey

### Deferred attribution

Deferred mode captures interactions and attributes them to the source link even when the conversion happens later ideal for longer sales cycles.

**Benefits:**

* Track leads that take days or weeks to convert
* Attribute delayed conversions back to the originating link
* Measure lead quality across different time windows
* Understand the full customer journey from first click to close

## Quick start

<Steps>
  <Step title="Enable attribution on your link">
    1. Log in to your [CutMeShort dashboard](https://app.cutmeshort.com)
    2. Navigate to **Home**
    3. If you already have a short link, click **Enable Lead & Sale Tracking** under the link you want to track. If you don't have a short link yet, create one first, then click **Enable Lead & Sale Tracking** for that link.
  </Step>

  <Step title="Add the tracking script">
    Place this script tag on your **conversion page** (e.g. thank-you page, post-signup page). It must load before any conversion event fires.

    ```html theme={null}
    <script
      src="https://cut-me-short-public.s3.ap-south-1.amazonaws.com/production/track.js"
      data-config='{"days":30,"attribution":"last"}'
    ></script>
    ```

    <Warning>
      The script must be present on the page where the conversion happens, not just the landing page.
    </Warning>
  </Step>

  <Step title="Send a conversion event">
    After a lead or sale occurs, call the appropriate API endpoint from your server. See [Lead API](/api-reference/endpoint/Lead) or [Sale API](/api-reference/endpoint/Sale).
  </Step>

  <Step title="Monitor results">
    1. Go to **Events → Attribution Dashboard**
    2. Filter by date range, link or location
    3. Review key metrics: total leads/sales, conversion rate, and attributed revenue
  </Step>
</Steps>

## API reference

<div>
  <a href="/api-reference/endpoint/Lead">
    <span>POST</span> /lead
  </a>

  <a href="/api-reference/endpoint/Sale">
    <span>POST</span> /sale
  </a>
</div>

## SDKs

Server-side SDKs are available for all major languages.

## Prerequisites

Before you begin, make sure you have:

* A CutMeShort account — [sign up here](https://app.cutmeshort.com)
* At least one shortened link created in your dashboard
* Access to your application codebase to add the tracking script and call the conversion API

## Real-world example

A customer sees an ad and clicks **Link A**. Later, they receive an email and click **Link B**, then complete a purchase.

```
Ad click  →  Link A  (not credited)
Email click  →  Link B  →  Purchase
                    ↑
             Link B gets 100% credit
```

This ensures you know which link drove the customer to convert making it straightforward to measure which campaigns and channels generate real revenue.

## Troubleshooting

| Issue                     | Likely cause                           | Fix                                                            |
| ------------------------- | -------------------------------------- | -------------------------------------------------------------- |
| Conversions not appearing | Script not on conversion page          | Move `<script>` tag to the page where the conversion fires     |
| Wrong link credited       | User clicked multiple links            | Expected — last click model is working correctly               |
| Zero revenue tracked      | Sale API payload missing `value` field | Check your server-side API call includes the `value` parameter |
| Attribution gap on mobile | Cookie blocked by browser              | Ensure your domain serves the page over HTTPS                  |


# Social Previews
Source: https://docs.cutmeshort.com/features/SocialPreviews

Preview how your URLs will appear on different social media platforms

<img />

CutMeShort introduces the Social Previews feature, empowering users to preview how their URLs will appear on different social media platforms before sharing them. By fetching and displaying meta tags from the destination URL during link creation, users can visualize and customize the previews for platforms such as LinkedIn, Twitter, and Facebook.

## Overview

Social Previews enhance user experience by providing a glimpse of how the shortened URLs will be presented on various social media platforms. By displaying preview images, titles, descriptions, and other metadata extracted from the destination URL, users can ensure that their shared content looks appealing and engaging across different platforms.

## How it Works

1. **Meta Tag Fetching**: During link creation, CutMeShort automatically fetches meta tags from the destination URL, including [Open Graph](https://ogp.me/) tags and Twitter Card tags.

2. **Preview Display**: The fetched meta tags are used to generate previews for different social media platforms such as LinkedIn, Twitter, and Facebook. Users can view how their shortened URLs will appear on these platforms in real-time.

## Benefits

* **Visual Representation**: Social Previews provide users with a visual representation of how their shared content will be displayed on social media platforms, helping them make informed decisions about sharing strategies.

* **Enhanced Engagement**: Appealing and well-optimized previews increase the likelihood of user engagement, clicks, and shares, ultimately driving traffic to the shared content.

* **Brand Consistency**: By customizing the preview elements such as titles and images, users can ensure brand consistency and reinforce their brand identity across different platforms.

* **Improved Click-Through Rates**: Optimized previews with compelling titles and descriptions attract more clicks and encourage users to explore the shared content further.

CutMeShort automatically fetches meta tags from the destination URL during link creation and generates previews for different social media platforms based on the extracted metadata. Users can review and customize the previews before finalizing the shortened URL, ensuring that the shared content looks appealing and engaging across various social media channels.

## Conclusion

Experience the power of Social Previews with CutMeShort, enabling users to visualize and customize how their URLs will appear on different social media platforms. Enhance engagement, increase click-through rates, and maintain brand consistency by leveraging the Social Previews feature to optimize your shared content for social media sharing.\`

<Tip>
  Visit [CutMe Short](https://cutmeshort.com) and
  [Signup](https://cutmeshort.com) for free! For any queries drop us an email at
  [support@cutmeshort.com](mailto:support@cutmeshort.com).
</Tip>


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

Meet CutMe Short - your ultimate Link Management Solution!

<img alt="Hero Light" />

<img alt="Hero Dark" />

A groundbreaking URL shortening platform that transcends traditional norms with its AI-driven capabilities designed to fuel your digital growth. More than just a link shortener, CutMe Short leverages advanced AI algorithms to provide unparalleled insights and growth recommendations at every turn.

## Features

CutMe Short offers some of the amazing features:

<CardGroup>
  <Card title="Advance Analytics" icon="chart-simple">
    Track your links and get real-time insights
  </Card>

  <Card title="AI powered Short Links" icon="microchip-ai">
    Let AI do the heavy lifting and shorten your links in no time
  </Card>

  <Card title="Personalize links with brand domains" icon="globe-pointer">
    Elevate your brand presence with personalized links by connecting it to your
    brand domain
  </Card>

  <Card title="Links to your favorite apps" icon="rocket-launch">
    Now open your links directly to your mobile applications instead of in app
    browsers
  </Card>

  <Card title="Custom QR codes" icon="qrcode">
    Drive Engagement and Impressions with Custom QR Codes Tailored to
    Perfection!
  </Card>

  <Card title="Social Previews" icon="image">
    Boost Clicks and Shares with Visually Appealing Link Previews!
  </Card>
</CardGroup>

<Tip>
  Visit [CutMe Short](https://cutmeshort.com) and
  [Signup](https://cutmeshort.com) for free! For any queries drop us an email at
  [support@cutmeshort.com](mailto:support@cutmeshort.com).
</Tip>


# Quickstart
Source: https://docs.cutmeshort.com/quickstart

Start building awesome documentation in under 5 minutes

## Setup your development

Learn how to update your docs locally and and deploy them to the public.

### Edit and preview

<AccordionGroup>
  <Accordion icon="github" title="Clone your docs locally">
    During the onboarding process, we created a repository on your Github with
    your docs content. You can find this repository on our
    [dashboard](https://dashboard.mintlify.com). To clone the repository
    locally, follow these
    [instructions](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
    in your terminal.
  </Accordion>

  <Accordion icon="rectangle-terminal" title="Preview changes">
    Previewing helps you make sure your changes look as intended. We built a
    command line interface to render these changes locally. 1. Install the
    [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the
    documentation changes locally with this command: `npm i -g mintlify`
    2\. Run the following command at the root of your documentation (where
    `docs.json` is): `mintlify dev`
  </Accordion>
</AccordionGroup>

### Deploy your changes

<AccordionGroup>
  <Accordion icon="message-bot" title="Install our Github app">
    Our Github app automatically deploys your changes to your docs site, so you
    don't need to manage deployments yourself. You can find the link to install on
    your [dashboard](https://dashboard.mintlify.com). Once the bot has been
    successfully installed, there should be a check mark next to the commit hash
    of the repo.
  </Accordion>

  <Accordion icon="rocket" title="Push your changes">
    [Commit and push your changes to
    Git](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push)
    for your changes to update in your docs site. If you push and don't see that
    the Github app successfully deployed your changes, you can also manually
    update your docs through our [dashboard](https://dashboard.mintlify.com).
  </Accordion>
</AccordionGroup>

## Update your docs

Add content directly in your files with MDX syntax and React components. You can use any of our components, or even build your own.

<CardGroup>
  <Card title="Style Your Docs" icon="paintbrush" href="/settings/global">
    Add flair to your docs with personalized branding.
  </Card>

  <Card title="Add API Endpoints" icon="square-code" href="/api-playground/configuration">
    Implement your OpenAPI spec and enable API user interaction.
  </Card>

  <Card title="Integrate Analytics" icon="chart-mixed" href="/analytics/supported-integrations">
    Draw insights from user interactions with your documentation.
  </Card>

  <Card title="Host on a Custom Domain" icon="browser" href="/settings/custom-domain/subdomain">
    Keep your docs on your own website's subdomain.
  </Card>
</CardGroup>


# Introduction
Source: https://docs.cutmeshort.com/sdks/clientside/introduction

Learn more about the CMS Analytics script and how to install it.

CMS Analytics is a client-side script for tracking conversion events with CMS.

```html theme={null}
<script
  src="https://cut-me-short-public.s3.ap-south-1.amazonaws.com/production/track.js"
  data-config='{"days":30,"attribution":"last"}'
></script>
```

The script detects the cms\_rf query parameter and stores it as a first-party cookie. You can configure cookie duration and attribution model using the `data-config` property.

<Tip>
  If you want to learn more about first-click vs last-click attribution, check out this [detailed guide](/api-reference/endpoint/clickattribution).
</Tip>

<img alt="Lead event attribution flow" />

## Installation Guides

You can install the CMS Analytics script:

## Properties

### `data-config`

|             |                                    |
| ----------- | ---------------------------------- |
| **Type**    | `JSON string`                      |
| **Example** | `{"days":30,"attribution":"last"}` |

Configure tracking behavior for cookie duration (`days`) and attribution model (`attribution`).

Use one of these script configurations based on your attribution strategy:

```html theme={null}
<!-- first-click, 90-day cookie -->
<script src="cms-tracker.js" data-config='{"days":90,"attribution":"first"}'></script>

<!-- last-click, 30-day cookie -->
<script src="cms-tracker.js" data-config='{"days":30,"attribution":"last"}'></script>
```


# Manual Installation
Source: https://docs.cutmeshort.com/sdks/clientside/manualinstallation

Add the CutMeShort Analytics script to any website

Use this option if you have access to your website’s HTML template (or a tag manager) and want to install the CutMeShort Analytics script directly.

## Add the script to your site

Paste the script **once** on every page of your website, ideally inside the `<head>` tag so it can read the landing-page URL before the user navigates.

```html theme={null}
<script
  src="https://cut-me-short-public.s3.ap-south-1.amazonaws.com/production/track.js"
  data-config='{"days":30,"attribution":"last"}'
></script>
```

### Where to place it

* **Static HTML sites**: put it in the shared layout file right before `</head>`.
* **Single-page apps (React/Vue/Next, etc.)**: put it in your app’s document/layout head so it loads on all routes.
* **Tag managers**: create a Custom HTML tag that fires on **All Pages**.

## What the script does

Once installed, the script:

* **Reads attribution from the landing URL**: detects `cms_rf` in the query string (example: `?cms_rf=abc123`).
* **Stores attribution as a first-party cookie**: saves the value for the configured cookie duration (for example, 30 or 90 days), so conversions that happen later can still be attributed.
* **Exposes a global tracking object**: makes the client SDK available under `window._cms` for debugging/verification.
* **Sends events with attribution attached**: when your lead/sale events are fired, the stored `cms_rf` is included so the conversion is credited to the original CutMeShort link click.

## Configuration options

You can pass the following attributes on the script tag:

### `data-config`

|             |                                    |
| ----------- | ---------------------------------- |
| **Type**    | `JSON string`                      |
| **Example** | `{"days":30,"attribution":"last"}` |

Used to configure cookie duration (`days`) and attribution model (`attribution`) for tracking.

Use one of these script configurations:

```html theme={null}
<!-- first-click, 90-day cookie -->
<script src="https://cut-me-short-public.s3.ap-south-1.amazonaws.com/production/track.js" data-config='{"days":90,"attribution":"first"}'></script>

<!-- last-click, 30-day cookie -->
<script src="https://cut-me-short-public.s3.ap-south-1.amazonaws.com/production/track.js" data-config='{"days":30,"attribution":"last"}'></script>
```

## Verification

1. Open your website, then open the browser console and run:
   * `window._cms`
2. Visit a test landing page URL that includes `cms_rf`, for example:
   * `https://your-site.com/?cms_rf=test`
3. Confirm a first‑party cookie is set (in your browser devtools under **Application → Cookies**).

If the checks fail, make sure:

* The script is present in the `<head>` and not duplicated.
* Your site (or CDN) is not serving a cached version of the page missing the script.

## Next steps

After the script is installed, you can send **Lead** and **Sale** conversions from your backend (recommended) using the Attribution endpoints.


# Overview
Source: https://docs.cutmeshort.com/sdks/overview

Open-source client libraries for the CMS API

## Server-side SDKs

Cutemshort offers server-side SDKs for many popular programming languages, making it easy to integrate the CMS API into your existing stack.

## Client-side SDKs

Use our client-side SDK to capture analytics and user events directly from the browser.

<div>
  <a href="/sdks/clientside/introduction">
    <div>
      <img alt="CMS Analytics SDK" />
    </div>

    <div>
      <div>
        CMS Analytics SDK
      </div>

      <div>
        Client-side tracking and analytics SDK
      </div>
    </div>

    <svg>
      <path />
    </svg>
  </a>
</div>


# PHP SDK
Source: https://docs.cutmeshort.com/sdks/serverside/phpSDK

Official PHP SDK for CutMeShort API

## Installation

Install via Composer:

```bash theme={null}
composer require cutmeshort
```

## Requirements

* PHP 7.4 or higher
* Composer for dependency management
* cURL extension enabled

## Quick Start

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use CutMeShort\SDK\Client;

$client = new Client();
$client->setAccessToken('your_api_token_here')
    ->setDebug(true);

$trackingApi = $client->getTrackingApi();
```

## Non-Deferred Lead Tracking

Track lead events when you have all the required information available immediately, including the `clickId`.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use CutMeShort\SDK\Client;
use CutMeShort\SDK\Models\LeadPayload;

$client = new Client();
$client->setAccessToken('your_api_token_here');

$trackingApi = $client->getTrackingApi();

// Create and track a lead with complete payload
$leadPayload = new LeadPayload();
$leadPayload->setClickId('clickid')
    ->setCustomerExternalId('user_123')
    ->setEventName('signup')
    ->setCustomerName('John Doe')
    ->setCustomerEmail('john@example.com');

try {
    $response = $trackingApi->trackLead($leadPayload);
    
    if ($response->getStatus()) {
        echo "✅ Lead Tracking successful!\n";
        echo "Message: " . $response->getData() . "\n";
    } else {
        echo "❌ Lead Tracking failed\n";
        echo "Error: " . $response->getData() . "\n";
    }
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>
```

### Lead Payload Methods

* `setClickId(string $clickId)` - The unique click identifier
* `setEventName(string $eventName)` - Name of the lead event (e.g., "signup", "email\_verified")
* `setCustomerExternalId(string $id)` - Your internal customer identifier
* `setCustomerName(string $name)` - Full name of the customer
* `setCustomerEmail(string $email)` - Customer's email address
* `setTimestamp(string $timestamp)` - ISO 8601 timestamp (auto-set if not provided)

## Deferred Lead Tracking

Use deferred mode for two-step lead attribution when the `clickId` isn't available at the time of the initial event.

### Step 1: Store the clickId Association

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use CutMeShort\SDK\Client;
use CutMeShort\SDK\Models\LeadPayload;

$client = new Client();
$client->setAccessToken('your_api_token_here');

$trackingApi = $client->getTrackingApi();

// Step 1: Create initial lead with deferred mode
$payload = new LeadPayload();
$payload->setClickId('clickid')
    ->setMode('deferred')
    ->setEventName('signup')
    ->setCustomerExternalId('user_123')
    ->setCustomerName('John Doe')
    ->setCustomerEmail('john@example.com');

try {
    $response = $trackingApi->trackLead($payload);
    
    if ($response->getStatus()) {
        echo "✅ Deferred Lead Tracking initialized!\n";
        echo "Stored clickId association with customerExternalId\n";
    } else {
        echo "❌ Failed to initialize deferred lead tracking\n";
    }
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>
```

### Step 2: Track Using Only customerExternalId

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use CutMeShort\SDK\Client;
use CutMeShort\SDK\Models\LeadPayload;

$client = new Client();
$client->setAccessToken('your_api_token_here');

$trackingApi = $client->getTrackingApi();

// Step 2: Later, track using just customerExternalId (no clickId)
$followUpPayload = new LeadPayload();
$followUpPayload->setCustomerExternalId('user_123')
    ->setEventName('email_verified');

try {
    $response = $trackingApi->trackLead($followUpPayload);
    
    if ($response->getStatus()) {
        echo "✅ Follow-up Lead Tracking successful!\n";
        echo "Used stored clickId from deferred mode\n";
    } else {
        echo "❌ Follow-up Lead Tracking failed\n";
    }
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>
```

**Key Benefits:**

* Store click context for later use
* Track multiple events in a user journey without losing click attribution
* No need to maintain clickId across complex workflows

## Sale Tracking

Track completed sales and revenue events with full transaction details.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use CutMeShort\SDK\Client;
use CutMeShort\SDK\Models\SalePayload;

$client = new Client();
$client->setAccessToken('your_api_token_here');

$trackingApi = $client->getTrackingApi();

// Create and track a sale
$salePayload = new SalePayload();
$salePayload->setClickId('clickid')
    ->setEventName('purchase')
    ->setCustomerExternalId('user_123')
    ->setCustomerName('Jane Smith')
    ->setCustomerEmail('jane@example.com')
    ->setInvoiceId('INV-2024-001')
    ->setAmount(4999) // Amount in cents
    ->setCurrency('USD');

try {
    $response = $trackingApi->trackSale($salePayload);
    
    if ($response->getStatus()) {
        echo "✅ Sale Tracking successful!\n";
        echo "Message: " . $response->getData() . "\n";
    } else {
        echo "❌ Sale Tracking failed\n";
        echo "Error: " . $response->getData() . "\n";
    }
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>
```

### Sale Payload Methods

* `setClickId(string $clickId)(optional)` - The unique click identifier
* `setEventName(string $eventName)` - Name of the sale event (e.g., "purchase", "purchase\_completed")
* `setCustomerExternalId(string $id)` - Your internal customer identifier
* `setInvoiceId(string $invoiceId)` - Invoice or transaction identifier
* `setAmount(float $amount)` - Amount in cents (e.g., 4999 = \$49.99)
* `setCurrency(string $currency)` - 3-letter currency code (e.g., "USD", "EUR", "INR")
* `setCustomerName(string $name)` - Customer's name
* `setCustomerEmail(string $email)` - Customer's email
* `setTimestamp(string $timestamp)` - ISO 8601 timestamp (auto-set if not provided)

## Error Handling

```php theme={null}
<?php
try {
    $response = $trackingApi->trackLead($leadPayload);
    
    if ($response->getStatus()) {
        echo "✅ Success!\n";
    } else {
        echo "Error: " . $response->getData() . "\n";
    }
} catch (\Exception $e) {
    echo "Exception caught: " . $e->getMessage() . "\n";
    echo "Code: " . $e->getCode() . "\n";
}
?>
```

## Configuration

```php theme={null}
<?php
$client = new Client();
$client->setAccessToken('your_api_token_here')
    ->setDebug(true)  // Enable debug mode
    ->setTimeout(10000) // Set timeout in milliseconds
    ->setMaxRetries(2); // Set maximum retries
?>
```

## Documentation

For complete documentation, visit [PHP SDK Docs](https://github.com/Cut-Me-Short/cutmeshort-php)


# Python SDK
Source: https://docs.cutmeshort.com/sdks/serverside/pythonSDK

Official Python SDK for CutMeShort API

## Installation

Install via pip:

```bash theme={null}
pip install cutmeshort
```

## Requirements

* Python 3.8 or higher
* requests library (installed as dependency)

## Quick Start

```python theme={null}
#!/usr/bin/env python3
from cutmeshort import CMSClient

bearer_token = "your_bearer_token"
client = CMSClient(token=bearer_token)
```

## Non-Deferred Lead Tracking

Track lead events with complete information including the `click_id`.

```python theme={null}
#!/usr/bin/env python3
from cutmeshort import CMSClient

bearer_token = "your_bearer_token"
client = CMSClient(token=bearer_token)

# Standard lead with complete payload
response = client.track_lead(
    click_id="5e6e1650-5641-4a2b-bec6-218288a86dbf",
    event_name="signup_started",
    customer_external_id="user_42",
    customer_name="John Doe",
    customer_email="john@example.com",
)

print(response)
```

### Lead Tracking Parameters

* `click_id` (str) - The unique click identifier
* `event_name` (str) - Name of the lead event (e.g., "signup\_started", "email\_verified")
* `customer_external_id` (str) - Your internal customer identifier
* `customer_name` (str, optional) - Full name of the customer
* `customer_email` (str, optional) - Customer's email address
* `timestamp` (str, optional) - ISO 8601 timestamp (auto-set if not provided)

## Deferred Lead Tracking

Use deferred mode for two-step lead attribution when the `click_id` isn't available at the event time.

### Step 1: Initialize Deferred Lead Tracking

```python theme={null}
#!/usr/bin/env python3
from cutmeshort import CMSClient

bearer_token = "your_bearer_token"
client = CMSClient(token=bearer_token)

# Step 1: Setup deferred mode - store clickId association
response = client.track_lead(
    click_id="5e6e1650-5641-4a2b-bec6-218288a86dbf",
    event_name="lead_captured",
    customer_external_id="user_72",
    customer_name="Jane Smith",
    customer_email="jane@example.com",
    mode="deferred",
)

print(response)
```

### Step 2: Track Follow-up Events

```python theme={null}
#!/usr/bin/env python3
from cutmeshort import CMSClient

bearer_token = "your_bearer_token"
client = CMSClient(token=bearer_token)

# Step 2: Later, track using just customer_external_id (no click_id)
response = client.track_lead(
    event_name="kyc_completed",
    customer_external_id="user_72",
)

print(response)
```

**Key Benefits:**

* Store click context for later reference
* Track multiple user journey events without losing attribution
* Simplify event tracking for complex workflows

**Complete Deferred Example:**

```python theme={null}
#!/usr/bin/env python3
from cutmeshort import CMSClient

bearer_token = "your_bearer_token"
client = CMSClient(token=bearer_token)

# Initialize deferred tracking
client.track_lead(
    click_id="5e6e1650-5641-4a2b-bec6-218288a86dbf",
    event_name="signup_started",
    customer_external_id="user_42",
    customer_name="cutmeshort",
    customer_email="cutmeshort@cms.com",
    mode="deferred",
)

# Track email verification without click_id
client.track_lead(
    event_name="email_verified",
    customer_external_id="user_42",
)
```

## Sale Tracking

Track completed sales and revenue events with full transaction details.

```python theme={null}
#!/usr/bin/env python3
import os
from cutmeshort import CMSClient

# Get Bearer token from environment
bearer_token = os.environ.get("CMS_BEARER_TOKEN", "your_bearer_token")

# Create client
client = CMSClient(token=bearer_token)

# Track a sale
response = client.track_sale(
    click_id="id_123",
    event_name="purchase_completed",
    customer_external_id="user_42",
    invoice_id="inv_987",
    amount=4999,  # amount in cents ($49.99)
    currency="USD",
    customer_name="John Doe",
    customer_email="john@example.com",
)

print(response)
```

### Sale Tracking Parameters

* `click_id` (str) (optional) - The unique click identifier
* `event_name` (str) - Name of the sale event (e.g., "purchase\_completed", "payment\_received")
* `customer_external_id` (str) - Your internal customer identifier
* `invoice_id` (str) - Invoice or transaction identifier
* `amount` (int) - Amount in cents (e.g., 4999 = \$49.99)
* `currency` (str) - 3-letter currency code (e.g., "USD", "EUR", "INR")
* `customer_name` (str, optional) - Customer's name
* `customer_email` (str, optional) - Customer's email
* `timestamp` (str, optional) - ISO 8601 timestamp (auto-set if not provided)

## Error Handling

```python theme={null}
#!/usr/bin/env python3
from cutmeshort import CMSClient

client = CMSClient(token="your_bearer_token")

try:
    response = client.track_lead(
        click_id="5e6e1650-5641-4a2b-bec6-218288a86dbf",
        event_name="signup_started",
        customer_external_id="user_42",
    )
    
    if response.success:
        print("✅ Lead tracking successful!")
    else:
        print(f"❌ Error: {response.error}")
        
except Exception as e:
    print(f"Exception: {str(e)}")
```

## Documentation

For complete documentation, visit [Python SDK Docs](https://github.com/Cut-Me-Short/cutmeshort)


# TypeScript SDK
Source: https://docs.cutmeshort.com/sdks/serverside/typescriptSDK

Official TypeScript SDK for CutMeShort API

## Installation

```bash theme={null}
npm install cutmeshort
```

## Requirements

* Node.js 18+ (recommended) or any runtime with global `fetch`
* TypeScript 5+ (optional, for type safety)

## Quick Start

```typescript theme={null}
import { CMS } from "cutmeshort";

const cms = new CMS({
  apiKey: process.env.CMS_API_KEY!,
});
```

## Non-Deferred Lead Tracking

Use non-deferred lead tracking when you can send the `clickId` at the moment you want to record a lead event.

```typescript theme={null}
import { CMS } from "cutmeshort";

const cms = new CMS({ apiKey: "sk_live_xxx" });

const response = await cms.trackLead({
  clickId: "id_123",
  eventName: "signup_started",
  customerExternalId: "user_42",
  timestamp: new Date().toISOString(),
  customerName: "John Doe",
  customerEmail: "john@example.com"
});
```

### Lead Payload Fields

* `clickId: string` - The unique click identifier
* `eventName: string` - Name of the lead event (e.g., "signup\_started", "email\_verified")
* `customerExternalId: string` - Your internal customer identifier
* `timestamp?: string` - ISO 8601 timestamp (defaults to current time)
* `customerName?: string` - Full name of the customer
* `customerEmail?: string` - Customer's email address

## Deferred Lead Tracking

Use deferred mode when you can't reliably send the `clickId` at the moment of recording a lead event. This enables two-step lead attribution.

### Step 1: Store the clickId Association

```typescript theme={null}
import { CMS } from "cutmeshort";

const cms = new CMS({ apiKey: "sk_live_xxx" });

// Store the clickId <-> customerExternalId association
await cms.trackLead({
  clickId: "id_123",
  eventName: "signup_started",
  customerExternalId: "user_42",
  mode: "deferred",
});
```

### Step 2: Track Using Only customerExternalId

```typescript theme={null}
// Later, track using just customerExternalId (no clickId needed)
await cms.trackLead({
  eventName: "email_verified",
  customerExternalId: "user_42",
});
```

**Key Differences:**

* In deferred mode's first call, you associate a `clickId` with a `customerExternalId`
* In subsequent calls, you only need the `customerExternalId` the SDK will use the stored association
* This is useful for complex user journeys where the click context may be lost

## Sale Tracking

Track sales/conversions with detailed transaction information.

```typescript theme={null}
import { CMS } from "cutmeshort";

const cms = new CMS({ apiKey: "sk_live_xxx" });

await cms.trackSale({
  customerExternalId: "user_123",
  eventName: "purchase_completed",
  invoiceId: "inv_987",
  amount: 4999,
  currency: "USD",
  timestamp: new Date().toISOString(),
  customerName: "Jane Smith",
  customerEmail: "jane@example.com"
});
```

### Sale Payload Fields

* `eventName: string` - Name of the sale event (e.g., "purchase\_completed")
* `customerExternalId: string` - Your internal customer identifier
* `invoiceId: string` - Invoice or transaction identifier
* `amount: number` - Amount in cents (e.g., 4999 = \$49.99)
* `currency: string` - 3-letter currency code (e.g., "USD", "EUR", "GBP")
* `timestamp?: string` - ISO 8601 timestamp (defaults to current time)
* `customerName?: string` - Customer's name
* `customerEmail?: string` - Customer's email

## Error Handling

```typescript theme={null}
import { CMS, CMSAPIError } from "cutmeshort";

const cms = new CMS({ apiKey: process.env.CMS_API_KEY });

try {
  await cms.trackLead({
    clickId: "id_123",
    eventName: "signup_started",
    customerExternalId: "user_42",
  });
} catch (error) {
  if (error instanceof CMSAPIError) {
    console.error("CMS API error", {
      statusCode: error.statusCode,
      type: error.type,
      message: error.message,
    });
  } else {
    console.error("Unexpected error", error);
  }
}
```

## Documentation

For complete documentation, visit [TypeScript SDK Docs](https://github.com/Cut-Me-Short/cms-ts)