> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turtles.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.