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

# Ship From Your Own Tool

> Mark orders shipped, correct tracking and hear about packages through the Replo API.

Use the API when your warehouse, ERP or label tool ships orders and Replo should know: the buyer gets the shipped email, the order page shows the package, and your other tools hear about it by webhook. These routes are in beta and need API version `2026-11-17`.

## Before you begin

* A project API key from **Settings → Workspace → API Keys** with `orders.read` and `orders.write`. Add `webhooks.read` and `webhooks.write` to manage webhooks through the API.
* Send `Replo-Api-Version: 2026-11-17` on every request.

## Mark an order shipped

**1. Find orders waiting to ship**

List paid orders with nothing shipped yet. `fulfillmentStatus` takes `unfulfilled`, `partial`, `fulfilled` or `cancelled`. To pick up only what changed since your last run, add `updatedSince`, which also catches a package added or its tracking changed.

```bash theme={null}
curl "https://api.replo.app/v1/orders?projectId=$REPLO_PROJECT_ID&financialStatus=paid&fulfillmentStatus=unfulfilled&updatedSince=2026-11-12T00:00:00Z" \
  -H "Authorization: Bearer $REPLO_API_KEY" \
  -H "Replo-Api-Version: 2026-11-17"
```

Page with `next_cursor` as on every list. Both filters run before paging, so pages never skip or repeat orders.

**2. Record the package**

Send the tracking for one package. Leave out `items` to ship everything the store hasn't shipped yet, or list the items in this box for a split shipment.

```bash theme={null}
curl https://api.replo.app/v1/orders/$ORDER_ID/fulfillments \
  -H "Authorization: Bearer $REPLO_API_KEY" \
  -H "Replo-Api-Version: 2026-11-17" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumber": "794644102245",
    "trackingCarrier": "FedEx",
    "items": [{ "orderItemId": "a81f…", "quantity": 1 }],
    "notifyBuyer": true
  }'
```

The response is the package, with `source: "api"`:

```json theme={null}
{
  "object": "fulfillment",
  "id": "5f0d…",
  "orderId": "7c1e…",
  "status": "success",
  "source": "api",
  "trackingCarrier": "FedEx",
  "trackingNumber": "794644102245",
  "trackingUrl": "https://www.fedex.com/fedextrack/?trknbr=794644102245",
  "shipmentStatus": null,
  "estimatedDeliveryAt": null,
  "shippedAt": "2026-11-12T18:04:11.000Z",
  "deliveredAt": null,
  "items": [{ "orderItemId": "a81f…", "quantity": 1 }],
  "createdAt": "2026-11-12T18:04:11.000Z",
  "updatedAt": "2026-11-12T18:04:11.000Z"
}
```

Leave out `trackingUrl` and Replo links the carrier's own tracking page for USPS, UPS, FedEx and DHL. `notifyBuyer` defaults to `true`; send `false` if your own tool already emails the buyer, and Replo never emails them about this package. When the store has Replo Shipping set up, Replo tracks the package and the shipped email waits for the carrier's first scan (at most 24 hours); otherwise it goes out right away.

**3. Retry safely**

The call is safe to repeat. Sending the same tracking number and carrier for the same order again returns the package already recorded and ships nothing twice, so retry on a timeout without checking first.

Only the part of an order the store ships itself is touched. On an order split with a print partner, items the partner ships can't be marked shipped here.

| Status | Meaning |
| - | - |
| `201` | The package was recorded, or the same tracking was already recorded. |
| `400` | An item isn't on the order, or the body is invalid. |
| `404` | No such order, or the key lacks `orders.write` for its project. |
| `409` | The order was refunded, isn't paid, is on hold, or has nothing left to ship. |

## Correct tracking

Fix a typo or a wrong carrier on a package. A new number or carrier without a link gets the carrier's tracking page.

```bash theme={null}
curl -X PATCH https://api.replo.app/v1/fulfillments/$FULFILLMENT_ID \
  -H "Authorization: Bearer $REPLO_API_KEY" \
  -H "Replo-Api-Version: 2026-11-17" \
  -H "Content-Type: application/json" \
  -d '{ "trackingCarrier": "UPS", "trackingNumber": "1Z999AA10123456784" }'
```

List every package of an order, from any tool (Replo, ShipStation, a CSV import or the API), with `GET /v1/orders/{orderId}/fulfillments`.

## Hear about packages

Subscribe to `fulfillment.created` and `fulfillment.updated` to keep another system in sync, including packages shipped from Replo, ShipStation or a CSV import. See [Webhooks](https://docs.replo.app/api-reference/webhooks.md) for the payload and the signature check.

## Buy a label

Labels are bought with the store's Replo Shipping account and charged to its card, so they need a separate scope, `shipping_labels.write`, plus `shipping.read` for rates. Someone has to finish Replo Shipping setup in the app first, including the card; until then buying answers `409`.

**1. Get rates**

```bash theme={null}
curl https://api.replo.app/v1/orders/$ORDER_ID/label-rates \
  -H "Authorization: Bearer $REPLO_API_KEY" \
  -H "Replo-Api-Version: 2026-11-17" \
  -H "Content-Type: application/json" \
  -d '{ "shippingPackageId": null, "weightGrams": 227, "options": { "signature": "none" } }'
```

The answer has a `shipmentId` and the rates, cheapest first. Each rate has an `id`, `carrier`, `service`, `name`, `amount` in minor units, `deliveryDays`, `estimatedDeliveryAt`, and `isBuyerChoice` when it matches the service the buyer paid for. Leave out `shippingPackageId` for the default box and `weightGrams` to add up the item and box weights. To ship part of an order, send `items` here and again when you buy.

**2. Buy the label**

```bash theme={null}
curl https://api.replo.app/v1/orders/$ORDER_ID/labels \
  -H "Authorization: Bearer $REPLO_API_KEY" \
  -H "Replo-Api-Version: 2026-11-17" \
  -H "Content-Type: application/json" \
  -d '{ "shipmentId": "shp_abc", "rateId": "rate_abc" }'
```

Send the `shipmentId` and one rate `id` from the same rates call; the box, weight and options come from that quote. The label comes back with its `trackingNumber`, `amount` and a short-lived `labelUrl` to the PDF. Buying records the package like the steps above, so the buyer is notified and webhooks fire. The same `rateId` returns the same label, so a retry never buys twice. A quote older than a day, one the carrier no longer honors, or one for different items or options than you send, answers `400`; get rates again. While another purchase for the same order is still being confirmed with the carrier (up to two minutes), buying answers `409`; try again shortly, and you are never charged twice. Items a print-on-demand provider ships answer `409` too.

**3. Void it if plans change**

`POST /v1/shipping/labels/{shippingLabelId}/void` asks the carrier to void an unused label. The label reads `voidRequested` until the carrier refunds it; then the package is cancelled, its items can ship again, and `shipping_label.voided` and `fulfillment.cancelled` fire. A label already scanned can't be voided.

Boxes come from `GET /v1/shipping/packages`. Each has a `type` (`box`, `envelope` or `softPack`; new boxes default to `box`) and, for carrier packaging such as a FedEx Pak, a `carrierPackage`. Rates and labels for a box with a `carrierPackage` use the carrier's price for that packaging.

To buy many at once, `POST /v1/shipping/label-batches` with up to 500 orders. Set `maxAmount` (minor units) on an order to cap its price: a label quoted higher isn't bought and is listed in `failures`. Labels are bought in the background; poll `GET /v1/shipping/label-batches/{shippingLabelBatchId}` until its `status` is `completed` or `partiallyFailed`, and read `failures` for orders that got no label.

> [card] [Webhooks](https://docs.replo.app/api-reference/webhooks.md)
>
> Event types, payloads, retries and signature checks.

> [card] [API reference](https://docs.replo.app/api-reference/introduction.md)
>
> Authentication, versions and every route.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.