Retrieve tracking 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.

Base URL

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.

-u "$TURTLES_USER:$TURTLES_PASS"

Endpoint

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

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.

{
  "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

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

Overview

Build a marketplace

Sell on Turtles

Overview

Base URL

Authentication

Endpoint

Example

Response

Suggested status handling

Suggested sync flow

​Overview

​Base URL

​Authentication

​Endpoint

​Example

​Response

​Suggested status handling

​Suggested sync flow

Overview

Base URL

Authentication

Endpoint

Example

Response

Suggested status handling

Suggested sync flow