# Orders API

> Look up an order's routing status and the orders it was routed to, including their fulfillments and tracking, and route an order to a connected store on demand.

Source: https://www.synkro-app.com/documentation/orders-api
Last updated: 2026-11-18

The Orders API lets your own system work with [**order routing**](https://www.synkro-app.com/documentation/order-routing.md):

- [**Get an order**](#get-an-order) to see whether it was routed, and the order number, fulfillments and tracking of the order it was routed to.
- [**Route an order**](#route-an-order) to a connected store.

Both endpoints act on orders of the store associated with the provided API access token, so the store isn't part of the request URL. `order_id` is the Shopify ID of an order in that store.

## Get an order

Get Synkro's information about an order, including its routing status and the orders it was routed to.

`GET /api/orders/{order_id}`

### Example

The following example cURL request gets the order **5551234567890**, which was routed to the store **example-2**.myshopify.com and fulfilled there.

#### Request

```json
curl --location 'https://api.synkro-app.com/api/orders/5551234567890' \
--header 'Accept: application/json' \
--header 'X-Synkro-Access-Token: synkro_at_*******'
```

#### Successful response `200`

```json
{
  "id": 5551234567890,
  "name": "#1042",
  "order_number": 1042,
  "financial_status": "paid",
  "created_at": "2026-11-18T14:02:11Z",
  "cancelled_at": null,
  "tags": "wholesale",
  "fulfillments": [],
  "routing_status": "routed",
  "destinations": [
    {
      "store": "example-2.myshopify.com",
      "order": {
        "id": 6661234567890,
        "name": "#2087",
        "order_number": 2087,
        "financial_status": "paid",
        "created_at": "2026-11-18T14:02:19Z",
        "cancelled_at": null,
        "fulfillments": [
          {
            "id": 7771234567890,
            "name": "#2087.1",
            "status": "success",
            "tracking_company": "UPS",
            "tracking_numbers": ["1Z999AA10123456784"],
            "tracking_urls": ["https://www.ups.com/track?tracknum=1Z999AA10123456784"],
            "created_at": "2026-11-18T15:30:02",
            "updated_at": "2026-11-18T15:30:02"
          }
        ]
      }
    }
  ]
}
```

#### Order not found `404`

Synkro has no record of an order with that ID in the store associated with the API access token.

## Route an order

Route an order to a connected store following your [order routing setting](https://www.synkro-app.com/documentation/order-routing.md#reference-deep-dive-into-order-routing-settings) for that store.

`POST /api/orders/{order_id}/route`

An order is only routed to a store once. If the destination store already has the order, no second order is created and the request is [rejected](#already-routed-or-in-progress-409).

### Parameters

| Parameter           | Required | Description                                                                                                                                                                                                                               |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `destination_store` | Yes      | The store to route the order to, given as its myshopify.com URL, e.g. `example-2.myshopify.com`.                                                                                                                                          |
| `async`             | No       | Defaults to `true`, which routes the order in the background and responds right away with a `job_id`. Set to `false` to have the request respond once the order has been routed, with the same body as [**Get an order**](#get-an-order). |

Parameters can be sent in the query string or as a JSON request body.

### Example: route in the background

The following example cURL request routes the order **5551234567890** to the store **example-2**.myshopify.com.

#### Request

```json
curl --location --request POST 'https://api.synkro-app.com/api/orders/5551234567890/route?destination_store=example-2.myshopify.com' \
--header 'Accept: application/json' \
--header 'X-Synkro-Access-Token: synkro_at_*******'
```

#### Successful response `202`

```json
{
  "job_id": "3f1c7a52-8d4e-4b9a-9c2f-6e0d1b7a4c18",
  "message": "Routing order 5551234567890 to example-2.myshopify.com"
}
```

Use the returned `job_id` with the [**Job API**](https://www.synkro-app.com/documentation/api-overview.md#job-api) to follow the routing's progress. A job's status is available for 10 minutes.

A **complete** job means the routing has finished, not that it succeeded. Once the job is complete, [get the order](#get-an-order) to check that its `routing_status` is **routed** and to read the order which was created in the destination store.

### Example: route and wait for the result

Add `async=false` to wait for the order to be routed.

#### Request

```json
curl --location --request POST 'https://api.synkro-app.com/api/orders/5551234567890/route?destination_store=example-2.myshopify.com&async=false' \
--header 'Accept: application/json' \
--header 'X-Synkro-Access-Token: synkro_at_*******'
```

#### Successful response `200`

The same body as [**Get an order**](#get-an-order), including the order which was just created in the destination store:

```json
{
  "id": 5551234567890,
  "name": "#1042",
  "order_number": 1042,
  "financial_status": "paid",
  "created_at": "2026-11-18T14:02:11Z",
  "cancelled_at": null,
  "tags": "wholesale",
  "fulfillments": [],
  "routing_status": "routed",
  "destinations": [
    {
      "store": "example-2.myshopify.com",
      "order": {
        "id": 6661234567890,
        "name": "#2087",
        "order_number": 2087,
        "financial_status": "paid",
        "created_at": "2026-11-18T14:02:19Z",
        "cancelled_at": null,
        "fulfillments": []
      }
    }
  ]
}
```

Routing an order takes several seconds, and can take longer, so allow your request a timeout of at least 60 seconds. If the connection is closed before Synkro responds, the order is still routed: [get the order](#get-an-order) to see the result.

### Errors

#### Invalid parameters `400`

`destination_store` is missing, or a parameter is invalid. The response names each invalid parameter.

```json
{
  "destination_store": ["can't be blank"]
}
```

The other error responses have a `message` explaining the problem.

#### Order not found `404`

The order wasn't found in the store associated with the API access token.

```json
{
  "message": "Order 5551234567890 was not found. If it is older than 60 days, Synkro needs permission to read all of this store's orders before it can be routed."
}
```

#### Already routed or in progress `409`

The destination store already has the order, or the order is being routed to that store right now. No second order is created.

```json
{
  "message": "Order 5551234567890 was already routed to example-2.myshopify.com"
}
```

```json
{
  "message": "Order 5551234567890 is already being routed to example-2.myshopify.com"
}
```

An order which is being routed stays **in progress** until its routing finishes, for at most 10 minutes.

#### Unable to route `422`

The order can't be routed to the destination store:

- The store has no enabled order routing setting to the destination store.
- The order was itself routed from the destination store, so it can't be routed back to it.
- With `async=false`: the routing failed, for example because no shipping rates are available for the order in the destination store. Your store's [**sync logs**](https://www.synkro-app.com/documentation/sync-logs.md) have the details.

```json
{
  "message": "This store has no enabled order routing to example-2.myshopify.com"
}
```

```json
{
  "message": "Unable to route order 5551234567890 to example-2.myshopify.com: no shipping rates are available for the order in that store"
}
```

## Need Help?

Contact our support team at [support@synkro-app.com](mailto:support@synkro-app.com) for assistance with the Orders API.
