# Welcome

Welcome to the twosided documentation. In this space, you'll learn how to integrate twosided with your own marketplace, as well as some useful tidbits about using twosided.

### Start your API integration

First, you should grab your API key from the dashboard. With that in hand, jump to the next chapter to start your API integration.

{% content-ref url="/pages/bWMJVfIto2nuDWGvmDKV" %}
[API Reference](/api-reference)
{% endcontent-ref %}

### Setting up Stripe Integrations

Attached are any helpful tips that can make your Stripe integration complete or achieve the next level.

{% content-ref url="/pages/q2RY9savyjR4zANDOwmz" %}
[Setting up your Stripe API key](/setting-up-your-stripe-api-key)
{% endcontent-ref %}


# User Segmentation

Segments let you slice your marketplace data by meaningful groups. Use the segment dropdown on any page to filter suppliers or customers and see how different groups compare. Segments are refreshed every night automatically.

***

### Volume

Ranks suppliers or customers by how much total volume they generate, compared to everyone else on your platform. Useful for quickly isolating your heaviest hitters or your long tail.

* **Top 5%**: Your absolute biggest players. The small group driving an outsized share of volume.
* **Top 25%**: Strong performers, consistently above average.
* **Median 50%**: The middle of the pack. Average volume.
* **Bottom 25%**: Below-average volume. May be new, inactive, or niche.

Available for both lifetime totals and the current month.

***

### RFM Segment

Combines three signals (how recently someone transacted, how often, and how much) into a single label. This is the most actionable segment for understanding participant health.

* **Champions**: Recent, frequent, high-value. Your best participants. Reward and retain them.
* **Loyal**: Transact frequently and recently, even if not the highest spenders. Reliable and engaged.
* **Big Spenders**: High transaction values but don't come back as often. Could become Champions with more frequency.
* **Promising**: Active recently but still early. Growing frequency or value could move them up.
* **Hibernating**: Haven't transacted in 1-3 months. Still recoverable with re-engagement.
* **Lost**: No activity in 3+ months. Unlikely to return without intervention.

***

### Tenure

How long someone has been part of your marketplace, based on their first transaction.

* **New (0-30 days)**: Just joined. Still in their onboarding window.
* **Growing (31-90 days)**: Past initial activation, building habits.
* **Established (91-365 days)**: Proven participant with a track record.
* **Veteran (366+ days)**: Long-term participant. Likely your most stable cohort.

***

### Recency

How long ago their last transaction was. A leading indicator of engagement.

* **0-7 days**: Active in the past week.
* **8-30 days**: Active in the past month.
* **31-90 days**: Starting to go cold.
* **90+ days**: Inactive for 3+ months.

***

### Frequency

How many total transactions they have. A measure of stickiness.

* **1 transaction**: Single-use so far.
* **2-3 transactions**: Early repeat behavior.
* **4-10 transactions**: Solid repeat participant.
* **10+ transactions**: Power user.

***

### AOV (Average Order Value)

Splits participants into three groups based on their average transaction size, relative to others on your platform.

* **Low AOV**: Bottom third. Smaller transactions on average.
* **Mid AOV**: Middle third. Typical transaction size.
* **High AOV**: Top third. Larger-than-average transactions.

Thresholds are calculated per-platform, so "high" is always relative to your marketplace.

***

### Supplier Loyalty (customers only)

Shows whether a customer keeps coming back to the same supplier or spreads purchases around. Helps you understand purchasing patterns and supplier dependency.

* **Single Purchase**: Only bought once. No loyalty signal yet.
* **Loyal to Supplier**: 70%+ of their purchases go to one supplier. Strong preference.
* **Variety Seeker**: Buys from 3+ different suppliers with no single one dominating. Shops around.
* **Mixed**: Some repeat behavior, but no strong pattern either way.

***

### Customer Diversity (suppliers only)

Shows how diversified a supplier's revenue base is. Helps identify concentration risk: suppliers that depend too heavily on one or two customers.

* **Single Customer**: All revenue from one customer. Maximum concentration risk.
* **Whale Dependent**: 70%+ of revenue from a single customer. Vulnerable if that customer leaves.
* **Diversified**: 5+ customers with no single one exceeding 30% of revenue. Healthy spread.
* **Balanced**: Multiple customers, moderate concentration. Not yet fully diversified.

***

### Region

Groups participants by geography, based on their country.

Regions are dynamic: only regions where you actually have participants will appear in the dropdown. Sub-regions include groupings like DACH, Nordics, BeNeLux, SEA, ANZ, and more.


# API Reference

{% content-ref url="/pages/Zyl7oEpzKw9Na0u2vDQ6" %}
[Track a new charge](/api-reference/track-a-new-charge)
{% endcontent-ref %}

{% content-ref url="/pages/FfgGwCtxdGshVt4XGxVC" %}
[Create a new supplier](/api-reference/create-a-new-supplier)
{% endcontent-ref %}

{% content-ref url="/pages/x40zEzkSZzYwvihUNlAh" %}
[Create a new customer](/api-reference/create-a-new-customer)
{% endcontent-ref %}


# Create a new supplier

<mark style="color:green;">`POST`</mark> `/supplier`

Create a new supplier

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

| Name           | Type   | Description                       |
| -------------- | ------ | --------------------------------- |
| `name*`        | string | Name of the user                  |
| `email*`       | string | Email of the user                 |
| `external_id*` | string | ID of supplier in external system |
| `country`      | string | Alpha-2 country code              |
| `description`  | string |                                   |
| `url`          | string |                                   |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": "ok",
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}


# Create a new customer

<mark style="color:green;">`POST`</mark> `/customer`

Create a new customer

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

| Name           | Type   | Description                       |
| -------------- | ------ | --------------------------------- |
| `name*`        | string | Name of the user                  |
| `email*`       | string | Email of the user                 |
| `external_id*` | string | ID of supplier in external system |
| `country`      | string | Alpha-2 country code              |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": "ok",
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}


# Track a new charge

<mark style="color:green;">`POST`</mark> `/charge`

Track a new charge

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

| Name           | Type                                                       | Description                                    |
| -------------- | ---------------------------------------------------------- | ---------------------------------------------- |
| `customer*`    | string \| [Customer](/api-reference/create-a-new-customer) | Can be external ID, or full customer object    |
| `supplier*`    | string \| [Supplier](/api-reference/create-a-new-supplier) | Can be external ID, or full supplier object    |
| `description*` | string                                                     |                                                |
| `amount*`      | float                                                      | USD amount of entire charge                    |
| `commission*`  | float                                                      | USD amount that was passed to platform         |
| `charge_id`    | string                                                     | Charge ID in external system                   |
| `created`      | timestamp                                                  | Unix timestamp in ms, defaults to current time |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": "ok",
  "internal_id": "<id:string>"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}


# Track a refund / Delete charge

<mark style="color:green;">`DELETE`</mark> `/charge/<id>`

Track a new charge

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**URL Parameter**

| Name  | Type   | Description                                      |
| ----- | ------ | ------------------------------------------------ |
| `ID*` | string | Can be external charge ID, or internal charge ID |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": "ok"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}


# Setting up your Stripe API key

The twosided platform requires a Stripe Secret API key in order to fully operate. You can use the Stripe integration using the account connection only, however you will have to deal with missing data:

* No personal data of suppliers and customers (only placeholders & customer IDs)
* Multi-split payments can't be supported
* No insights into aggregate supplier and customer locations

As this makes the twosided integration less effective, we recommend supplying an API key, or alternatively looking into substituting this information through our [REST API](/api-reference).

### Setting up a restricted key

Stripe allows you to set up a restricted key in their [developer section](https://dashboard.stripe.com/apikeys).

<figure><img src="/files/hRIyZ6z5lhhdvrRAOK5D" alt=""><figcaption></figcaption></figure>

It can be a good option to give looser restrictions to this key, to avoid breaking any integration when the twosided platform updates. At a high-level, we require the following permissions:

* All core resources – Read
* All core resources (Connect permissions) – Read
* All Connect resources – Read

You can restrict the key further to only allow for required resources to be accessible. However, note that this can lead to issues with platform updates later on.

<details>

<summary>All required resources (Detailed, Latest)</summary>

* Balance transaction sources (Permissions & Connect Permissions) – Read
* Balance Transfers (Permissions & Connect Permissions) – Read
* Charges (Permissions & Connect Permissions) – Read
* Customers (Permissions & Connect Permissions) – Read
* PaymentIntents (Permissions & Connect Permissions) – Read
* Products (Permissions & Connect Permissions) – Read
* All Connect resources – Read

</details>


# Connecting to Sharetribe

To connect your Sharetribe marketplace, you'll need your Client ID and Client Secret from the Sharetribe Console. These credentials allow secure access to your marketplace data.

If you haven't already, log into your [Sharetribe Console](https://console.sharetribe.com) and navigate to your Applications settings under Advanced > Applications.

<figure><img src="/files/B7xCOEYVDgEvOdhsKyO7" alt=""><figcaption></figcaption></figure>

Add a new application, and call it something descriptive like "twosided". You'll want to use the "Integration API" setting.

<figure><img src="/files/00f5VtjrJXCgyGsgplSa" alt=""><figcaption></figcaption></figure>

Copy your Client ID and Client secret to a safe place, like a password manager. After dismissing this dialog, you won't be able to look at it anymore!

<figure><img src="/files/K6XqXfQntdWk0bsuWyjW" alt=""><figcaption></figcaption></figure>

In the last step, copy over your Client ID and Client secret on your [Sharetribe connection to twosided](https://app.twosided.io/sharetribe/) – we'll take it from there.