# Create a marketplace order
Source: https://docs.turtles.com/build/create-marketplace-order

Send a fulfillment order to Turtles

### Overview

Create a marketplace order when your customer has checked out and Turtles needs to fulfill the item.

<Note>
  Set `purchaseOrderNumber` to the internal order ID, transaction ID, or associated ID you want to use for future tracking.
</Note>

### Base URL

```http theme={null}
https://triton.turtles.com
```

This is the public production API. Turtles does not currently provide a sandbox URL.

### Authentication

Order endpoints use HTTP Basic Auth with your Turtles API credentials.

```bash theme={null}
-u "$TURTLES_USER:$TURTLES_PASS"
```

### Endpoint

```http theme={null}
POST https://triton.turtles.com/api/orders
```

Partners receive valid `itemId` values from the product feed provided during onboarding.

| Field                 | Type   | Required | Description                                                                                    |
| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
| `itemId`              | number | Yes      | Turtles item ID to fulfill.                                                                    |
| `purchaseOrderNumber` | string | Yes      | Your internal order ID, transaction ID, or associated ID for matching future tracking updates. |
| `name`                | string | Yes      | Recipient full name.                                                                           |
| `email`               | string | Yes      | Recipient email address.                                                                       |
| `phone`               | string | Yes      | Recipient phone number, preferably in E.164 format.                                            |
| `address`             | string | Yes      | Street address line 1.                                                                         |
| `address2`            | string | No       | Street address line 2.                                                                         |
| `city`                | string | Yes      | Recipient city.                                                                                |
| `state`               | string | Yes      | State or province code.                                                                        |
| `zipCode`             | string | Yes      | Postal code.                                                                                   |
| `country`             | string | Yes      | Two-letter country code, for example `US`.                                                     |

### Example

```bash theme={null}
curl -X POST "https://triton.turtles.com/api/orders" \
  -u "$TURTLES_USER:$TURTLES_PASS" \
  -H "Content-Type: application/json" \
  -d '{
    "itemId": 12345,
    "purchaseOrderNumber": "internal-order-1001",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+15551234567",
    "address": "123 Main St",
    "address2": "Apt 4B",
    "city": "Austin",
    "state": "TX",
    "zipCode": "78701",
    "country": "US"
  }'
```

A `201 Created` response means Turtles accepted the order. Store the `purchaseOrderNumber` you sent so you can match future tracking updates.

<Warning>
  Automatic retries should reuse the same `purchaseOrderNumber`. Confirm duplicate-order behavior with Turtles before retrying create requests automatically.
</Warning>

Next, [retrieve tracking updates](/build/retrieve-tracking-updates) for created orders.


# Create a marketplace
Source: https://docs.turtles.com/build/overview

Turtles is the leading OS for modern marketplaces

### Overview

Turtles is the operating system for modern, high-scale marketplaces. We provide the tooling to launch, operate, and scale, handling the complexity of liquidity, logistics, and compliance so you can focus on growth.

### The Platform

Turtles replaces fragmented tooling with a unified operating system:

* **Flexible Commerce Engines:** Support flash deals, auctions, social buying and more with personalized shopping feeds and 1-tap checkouts
* **Unified Operations:** Manage orders, payouts, rule-based commissions, fulfillment APIs, and AI-assisted support in a single system of record
* **Seller Infrastructure:** Instantly onboard third parties with dedicated portals, autonomous order routing, and inventory sync
* **Governance & Compliance:** Scale globally with automated tax calculation, fraud detection, and inventory reconciliation.
* **Logistics & Analytics:** Access integrated 3PLs and global shipping alongside real-time reporting and demand forecasting.

### Global Scale

Turtles is battle-tested for scale

* **27M+** US shopper accounts
* **\$250M+** annual MSRP volume
* **99.997%** historical API uptime
* **1.47B+** monthly API events

### Use Cases

* **For creators:** Turn your community into a thriving marketplace
* **For startups:** Build a marketplace business in days, not years
* **For enterprises:** Migrate to infrastructure built for global scale

### Get Access

We're currently prioritizing large marketplace opportunities. To learn more, request access in just three minutes.

[Request access →](/build/request)

Need to send orders directly? See [Create a marketplace order](/build/create-marketplace-order).


# Request access
Source: https://docs.turtles.com/build/request

Build or migrate your marketplace on Turtles

### Request access

We are currently onboarding partners selectively to ensure stability and support. Access is prioritized for existing marketplaces, funded startups, and large creators.

### Eligibility

We're prioritizing requests that meet one or more of the following criteria:

* **Funded Startups:** Companies with at least **\$2M+** in funding
* **Significant Volume:** Clear potential to drive **\$5M+** in annual GMV
* **Large Audiences:** Creators or brands with **500K+** engaged followers
* **Migrations:** Large existing marketplaces moving infrastructure

### Process

1. **Submit:** Provide details on your category, business model, and scale
2. **Review:** Our team evaluates technical fit and volume potential
3. **Onboard:** Approved partners receive access and implementation support

### Apply

[Start your application →](https://app.turtles.com/start)

Questions? Email [start@turtles.com](mailto:start@turtles.com).


# Retrieve tracking updates
Source: https://docs.turtles.com/build/retrieve-tracking-updates

Poll Turtles for shipment and delivery updates

### Overview

Retrieve tracking updates to keep your marketplace order statuses in sync after Turtles accepts an order.

Turtles returns updates keyed by `purchaseOrderNumber`, which should match the internal order ID, transaction ID, or associated ID you sent when you [created the marketplace order](/build/create-marketplace-order).

### Base URL

```http theme={null}
https://triton.turtles.com
```

This is the public production API. Turtles does not currently provide a sandbox URL.

### Authentication

Tracking endpoints use HTTP Basic Auth with your Turtles API credentials.

```bash theme={null}
-u "$TURTLES_USER:$TURTLES_PASS"
```

### Endpoint

```http theme={null}
GET https://triton.turtles.com/api/orders?updated_since={unixTimestamp}
```

Fetch Turtles orders updated since a Unix timestamp in seconds.

| Query parameter | Type    | Description                                                                  |
| --------------- | ------- | ---------------------------------------------------------------------------- |
| `updated_since` | integer | Unix timestamp in seconds. Use the timestamp from your last successful poll. |

We recommend polling once every 6 hours. Some partners poll daily or hourly depending on volume, but do not poll more than once per hour.

### Example

```bash theme={null}
curl -X GET "https://triton.turtles.com/api/orders?updated_since=1714413600" \
  -u "$TURTLES_USER:$TURTLES_PASS" \
  -H "Accept: application/json"
```

Advance your stored poll timestamp only after the request succeeds and your system finishes processing the response.

### Response

Turtles returns a JSON object keyed by `purchaseOrderNumber`.

```json theme={null}
{
  "internal-order-1001": {
    "status": "Shipped",
    "updated_at": "1714417200",
    "trackings": [
      {
        "carrier": "FedEx",
        "tracking": "380161079953",
        "url": "https://www.fedex.com/fedextrack/?trknbr=380161079953",
        "delivery_status": "intransit"
      }
    ],
    "vendor_order_id": 1654696
  }
}
```

| Field                         | Type   | Description                                                                                     |
| ----------------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| `status`                      | string | Turtles order status, for example `Received`, `Processing shipment`, `Shipped`, or `Delivered`. |
| `updated_at`                  | string | Last update timestamp.                                                                          |
| `trackings`                   | array  | Tracking records for the order.                                                                 |
| `trackings[].carrier`         | string | Carrier name.                                                                                   |
| `trackings[].tracking`        | string | Tracking number.                                                                                |
| `trackings[].url`             | string | Carrier tracking URL.                                                                           |
| `trackings[].delivery_status` | string | Carrier delivery status, for example `inforeceived`, `intransit`, or `delivered`.               |
| `vendor_order_id`             | number | Turtles vendor order ID.                                                                        |

### Suggested status handling

| Turtles value                                           | Suggested marketplace status |
| ------------------------------------------------------- | ---------------------------- |
| `Delivered` order status or `delivered` delivery status | Delivered                    |
| `Shipped` order status                                  | Shipped                      |
| `intransit` or `inforeceived` delivery status           | Shipped                      |
| `Processing shipment` or `Received` order status        | Processing                   |
| `Canceled` or `Cancelled` order status                  | Canceled                     |

### Suggested sync flow

1. Store the Unix timestamp from your last successful tracking poll.
2. Call the tracking endpoint with `updated_since`.
3. For each response key, find the marketplace order with the same internal reference.
4. Save the carrier, tracking number, tracking URL, and latest status.
5. Advance your stored poll timestamp after all updates are processed successfully.


# Create an account
Source: https://docs.turtles.com/create





# Approvals
Source: https://docs.turtles.com/sell/approvals

Quality standards for brands and inventory on the Turtles network

### Overview

To maintain the integrity of our network and the trust of 27M+ shoppers, Turtles enforces strict quality standards for all partners. We work with category-leading brands and manually review every applicant to ensure a premium customer experience.

### Brand eligibility

We partner with brands that demonstrate operational excellence and product quality. To join the network, you must meet the following criteria:

* **Owned Inventory:** You must physically hold and control your inventory
* **Domestic Fulfillment:** Orders must deliver from U.S. facilities within 5-7 days
* **Track Record:** Verifiable history of strong customer satisfaction and low return rates
* **Product Quality:** Catalog-wide average rating of 4.5 stars or higher

### Product guidelines

Our catalog is curated to ensure safety and brand suitability

**Restricted categories**\
Certain categories require additional documentation and compliance approval:

* **Food & Beverage:** Perishable and non-perishable goods must meet packaging and expiration standards
* **Health & Wellness:** Supplements and ingestibles must meet FDA labeling requirements
* **Alcohol:** Wine and spirits require valid licensure and age-verification workflows

**Prohibited categories**\
The following items are strictly banned from the network:

* **Offensive Materials:** Products promoting hate speech, violence, profanity, or discrimination
* **Weapons & Combat:** Firearms, ammunition, explosives, or related accessories
* **Adult Content:** Mature and adult content or services, or products that have nudity
* **Illegal & Counterfeit:** Fake goods, drug paraphernalia, or recalled products
* **Medical & Regulated:** Prescription medication, medical devices, and professional medical accessories
* **Hazardous Goods:** Unregulated chemicals, combustible materials, or items deemed non-shippable

### Review process

Our Trust & Safety team reviews all submissions to ensure compliance

* **Brand Applications:** Typically reviewed within **3 business days**
* **New Listings:** Typically reviewed within **24 hours**

We reserve the right to request additional documentation as well as reject, or later remove, partners who do not meet our strict thresholds


# Balance
Source: https://docs.turtles.com/sell/balance

Managing revenue, withdrawals, and reconciliation

### Overview

The Turtles Balance dashboard provides a real-time ledger of your balance and payouts. We streamline operations by automating payouts directly to your connected bank account, ensuring predictable cash flow without manual invoicing.

### Payout schedule

We process settlements on a weekly cadence to the bank account on file:

* **Frequency:** Weekly automated transfers
* **Method:** Direct ACH deposit
* **Fees:** \$0 for standard weekly processing

### Expedited access

We understand that inventory cycles occasionally require faster liquidity. Partners may request a one-time priority payout for urgent capital needs.

Please contact your **Account Manager** to request an exception. Approval is subject to account health and volume review.

### Reconciliation

The Seller Portal provides a granular ledger for financial tracking. Each payout includes:

* **Amount:** Gross sales minus the 7% platform fee
* **Payout ID:** Unique reference code for payout matching
* **Destination:** The bank account on file at the time of payout


# Boost
Source: https://docs.turtles.com/sell/boosts

Acquire new, incremental customers on Turtles

### Overview

Boost is a paid promotion engine built directly into the Turtles network. It allows sellers to acquire new customers by elevating product visibility across our ecosystem of marketplaces.

Unlike external ad networks, boosts integrate deeply with our demand engine, optimizing placement in real-time to target high-intent shoppers already browsing the network.

### Configuration

Boost is designed for "set and forget" simplicity. You define the budget, and our algorithm handles the distribution.

**Target daily boost**

You set a **Target daily boost** (e.g. \$500). The system will:

* Automatically bid on placement across feeds, search results, and recommendations
* Fluctuate daily spend based on opportunity, aiming to average your target on a weekly basis
* Spend more when conversion probability is high and less when demand is low

**Payment**

* Payments are processed securely via Stripe
* You can update your payment method or adjust your daily budget at any time via the **Manage** panel
* Turtles may pay your boosts using your balance

### Performance tracking

The Boost dashboard provides real-time visibility into your campaign performance.

**Key metrics**

* **Revenue:** Total GMV generated directly from boosted listings
* **ROAS:** Return on Ad Spend (Revenue ÷ Ad Spend)
* **Orders:** Total number of transactions attributed to Boost
* **Ad Spend:** Total amount billed for the period

**Granular reporting**

The data table breaks down performance by day, offering deeper insights into:

* **Customers:** How many customers you've found
* **AOV:** Average Order Value for boosted transactions
* **Trend Analysis:** View historical data to correlate spend with revenue spikes

### Getting started

1. Navigate to the **Boost** tab in your seller portal
2. Set your **Target daily boost** amount
3. Add a payment method
4. Click **Boost my listings 🚀** to go live immediately


# Integrations
Source: https://docs.turtles.com/sell/integrations

Connect your existing commerce platform to Turtles.

### Supported platforms

* **Shopify:** Live
* **Amazon:** Coming soon
* **BigCommerce:** Coming soon
* **Magento (Adobe Commerce):** Coming soon
* **Salesforce Commerce Cloud:** Coming soon
* **WooCommerce:** Coming soon

<div />

### Connect your Shopify to Turtles

<Check>
  To begin, you must have 'App Development' permissions in Shopify Admin
</Check>

<Steps>
  <Step title="Create your Turtles app">
    1. Visit [https://dev.shopify.com/dashboard/](https://dev.shopify.com/dashboard/)
    2. Click **Create app**, name it `Turtles` and click **Create**
  </Step>

  <Step title="App setup">
    1. Set the app URL to `https://app.turtles.com` <CopyButton />
    2. Set 'Scopes' to `read_products,read_inventory,write_orders` <CopyButton />
    3. Leave everything else as the default values or empty
    4. Click **Release** at the bottom, and then click **Release** again when the confirmation popup is displayed
  </Step>

  <Step title="Connect to Turtles">
    1. In the Shopify dashboard, click **Settings** from the left sidebar and copy the Client ID and secret
    2. Go back to the **Turtles Portal**, and paste the Client ID and secret
    3. Click **Connect Shopify**
    4. Click **Install** on the Shopify installation page to finish authorizing the app

       <img alt="Shopify" />
  </Step>
</Steps>

### Troubleshooting Shopify

<AccordionGroup>
  <Accordion title="Shopify app is missing permissions">
    This means the app is missing one of the 3 required scopes. Here's how to fix it:

    1. Visit [https://dev.shopify.com/dashboard/](https://dev.shopify.com/dashboard/)
    2. Click on the **Turtles** app to open it
    3. Click **Versions** from the left sidebar
    4. Click **Create version**
    5. Change 'Scopes' to `read_products,read_inventory,write_orders` <CopyButton />
    6. Click **Release** at the bottom, and then click **Release** again when the confirmation popup is displayed
    7. In the Shopify dashboard, click **Settings** from the left sidebar and copy the **Client ID** and **secret**
    8. Go back to the **Turtles Portal**, and paste the **Client ID** and **secret**
    9. Click **Install** on the Shopify installation page to finish authorizing the app
  </Accordion>

  <Accordion title="OAuth error invalid_request: The redirect_uri and application url must have matching hosts">
    <img alt="Oops" />

    This means the App URL was entered incorrectly during app setup. Here's how to fix it:

    1. Visit [https://dev.shopify.com/dashboard/](https://dev.shopify.com/dashboard/)
    2. Click on the **Turtles** app to open it
    3. Click **Versions** from the left sidebar
    4. Click **Create version**
    5. In the URLs section, change 'App URL' to `https://app.turtles.com` <CopyButton />
    6. Click **Release** at the bottom, and then click **Release** again when the confirmation popup is displayed
    7. In the Shopify dashboard, click **Settings** from the left sidebar and copy the **Client ID** and **secret**
    8. Go back to the **Turtles Portal**, and paste the **Client ID** and **secret**
    9. Click **Install** on the Shopify installation page to finish authorizing the app
  </Accordion>
</AccordionGroup>

<div />

### WooCommerce Integration Guide

<Steps>
  <Step title="Generate API keys">
    1. Go to: WooCommerce > Settings > Advanced > REST API.

       <img alt="WooCommerce" />

    2. Click Create an API key OR Add Key. You’ll be taken to the Key Details screen.

    3. Add a Description.

    4. Select the User you would like to generate a key for in the dropdown.

    5. Select Read/Write access

    6. Click Generate API Key, and WooCommerce creates API keys for that user.

    7. Now that keys have been generated, you should see Consumer Key and Consumer Secret keys.

       <img alt="WooCommerce" />
  </Step>

  <Step title="Connect to Turtles">
    1. Log in to your [Turtles Dashboard](https://app.turtles.com)
    2. Navigate to **Settings > Integrations**
    3. Click **Connect WooCommerce**
    4. Fill in the Store URL, Consumer key and secret
  </Step>
</Steps>

Need help? Contact [support@turtles.com](mailto:support@turtles.com)


# Listings
Source: https://docs.turtles.com/sell/listings

Manage and optimize your product catalog.

### Automated sync

For most partners, listings are created automatically via your integrated commerce platform (e.g. Shopify). Once connected, Turtles syncs product details, inventory, and pricing in real-time.

[View integration guides →](/sell/integrations)

### Managing listings

The **Listings** tab provides a centralized view of your entire catalog. From here you can:

* **Monitor Status:** View items that are Active, Paused, or In Review
* **Audit Content:** Verify photos, descriptions, and pricing imported from your store
* **Create Manually:** Upload individual products directly if they do not exist in your source system

### Exclusions

By default, the integration syncs all eligible products from your store.

To exclude specific SKUs or collections from appearing on the Turtles network, please contact your **Account Manager**. We handle exclusions at the configuration level to ensure inventory accuracy.


# Orders
Source: https://docs.turtles.com/sell/orders

Automated order routing and fulfillment synchronization

### Overview

Turtles operates as a headless demand layer. When a purchase occurs on any marketplace in our network, the order is instantly routed to your connected commerce platform (e.g. Shopify) for fulfillment.

### Order lifecycle

The order process is fully automated to fit your existing logistics workflows:

1. **Capture:** A customer places an order on a Turtles-powered marketplace
2. **Sync:** The order appears in your dashboard marked as a Turtles channel sale
3. **Fulfillment:** Your warehouse picks, packs, and ships the item using your process
4. **Confirmation:** Tracking numbers automatically sync back to Turtles infrastructure
5. **Notification:** We trigger shipment and delivery notifications to the customer

### Managing orders

While fulfillment happens in your commerce dashboard, the **Orders** view in the Seller Portal acts as your financial and operational ledger.

Each order record includes:

* **Status:** Real-time state (Ordered, Shipped, Delivered, Returned)
* **Financials:** Gross revenue, platform fees, and net payout amount
* **Customer:** Customer information and shipping address
* **Reference:** The corresponding platform order ID

### Support and communication

Turtles owns the post-purchase customer relationship.

* **Support:** Our 24/7 support team handles all questions regarding status, tracking, and returns
* **Returns:** Unless the product arrives damaged with documentation, Turtles covers all returns
* **Privacy:** To protect privacy and platform integrity, sellers may not communicate directly with customers

<Danger>
  Direct customer contact is strictly prohibited under the Turtles Seller Terms. Violation of this policy will result in removal from the platform and may result in other penalties.
</Danger>

**Note:** If a shipping exception or inventory error occurs, flag the order in the Seller Portal immediately to alert our support team.


# Sell on Turtles
Source: https://docs.turtles.com/sell/overview

The unified distribution layer for modern brands

### Overview

Turtles for Sellers is a managed commerce platform that connects your inventory to a network of premium marketplaces serving 27M+ US shoppers. By integrating once, brands gain immediate reach across our entire ecosystem without the operational overhead of managing individual storefronts.

You bring the product, we'll handle the rest. For some brands, Turtles is one of their largest channels and even more performant than Amazon, META, and AppLovin.

With just a flat 7% selling fee (93% of every sale goes to you) and no subscriptions or listing fees, Turtles is one of the best channels to expand your brand's audience,

### How it works

Turtles functions as a plug-and-play supply layer on top of your existing infrastructure:

1. **Connect:** Link your store (eg Shopify) to sync catalog and inventory in real-time
2. **Distribute:** Products automatically populate across our marketplace network
3. **Sell:** Orders flow back to your store's dashboard for standard fulfillment
4. **Scale:** Optionally boost your listings and acquire new customers

### The Platform

The Seller Portal lets you track and manage your growth

* **Unified Distribution:** List SKUs once to reach millions of high-intent buyers across multiple marketplaces
* **Managed Operations:** Turtles owns 100% of the checkout experience, fraud detection, tax compliance, and 24/7 customer support
* **Seamless Fulfillment:** Ship orders using your existing warehouse and logistics workflows without new tooling
* **Supercharged Listings:** Deploy boosts to find and acquire new incremental customers
* **Fully Transparent:** Weekly payouts and real-time revenue reconciliation

### Next steps

[Become a Turtles seller →](https://app.turtles.com/start)


# Brand profile
Source: https://docs.turtles.com/sell/profile

Manage your public identity on the Turtles network.

### Overview

Your brand profile is the shopper-facing identity that appears across all marketplaces in the Turtles network. It is critical to keep this information up-to-date to build trust and ensure high conversion rates.

You can manage these details directly from the **Settings** tab in your seller portal.

### Profile settings

To modify your brand's appearance:

1. Navigate to **Settings** in the sidebar menu
2. Locate the **Brand details** card
3. Click the **Edit** button to open the configuration modal

**Configurable fields**

* **Name:** Your official brand name as it appears on listings and receipts
* **Logo:** A clear, high-resolution square image (recommended 512x512px)
* **Description:** A short bio telling your brand story, philosophy, and value proposition

### Approval process

To maintain network integrity, all changes to your brand profile are subject to review by our Trust & Safety team.

When you save changes, fields will display an **In review** badge. Updates typically process within **24 hours**. During this period, your previous profile details will remain live to ensure no disruption to your presence.


# Team management
Source: https://docs.turtles.com/sell/team

Control access and permissions for your organization

### Overview

Team settings allow you to securely collaborate with colleagues within the Turtles Seller Portal. Administrators can invite new members, assign roles, and revoke access as needed.

### Invite members

To add a new user to your organization:

1. Navigate to **Settings > Team**
2. Click the **Invite +** button in the top right corner
3. Enter the user's **First name**, **Last name**, and **Email**
4. Click **Invite** to send the invitation email

The user will receive a secure link to create their account and join your workspace

### Manage access

You can modify or revoke access for existing team members at any time via the team list.

**Remove a user**

1. Locate the user in the **Team settings** list
2. Click the **...** (overflow menu) in the **Edit** column
3. Select **Remove** to immediately revoke access

**Roles**

The **Role** column displays the current permission level for each user. Currently, team members are added as **Admins**, granting full access to listings, orders, payouts, and settings.


# 24/7 support
Source: https://docs.turtles.com/support

Whether you're building a new marketplace or selling across our network, our team is here to ensure your business scales smoothly on Turtles

### To get support

* **For existing accounts:** Your Account Manager is your best resource. They can provide the fastest, most personalized support.
* **For new accounts:** For general help or dev questions, email [**support@turtles.com**](mailto:support@turtles.com) any time. Our team can't wait to help you scale.

<Note>
  Turtles support is available 24/7 for existing accounts, with optional enterprise SLAs for support. For new accounts, please allow for up to a 1 business day response time.
</Note>


# Welcome to Turtles.com
Source: https://docs.turtles.com/welcome

Turtles.com is the leading OS for marketplaces. Build your marketplace with Turtles or start selling alongside global icons like Jimmy Choo, Nike, and Lego and reach 27M+ shoppers.

<img alt="" title="" />

## Getting started

Choose your path to begin building and integrating with Turtles

<CardGroup>
  <Card title="Build a marketplace" href="/build/overview">
    Design and power a marketplace with tools built for global scale
  </Card>

  <Card title="Sell on Turtles" href="/sell/overview">
    Tap into a network of 27M+ active US shoppers with just a low 7% fee
  </Card>
</CardGroup>