# Tracktor API

#### Tracktor API

* [Fulfillments](#Fulfillments)
  * [Retrieve the tracking status of a Fulfillment](#jump-Fulfillments-RetrievethetrackingstatusofaFulfillment)
* [Orders](#Orders)
  * [Get the current package tracking status options for this shop](#jump-Orders-Getthecurrentpackagetrackingstatusoptionsforthisshop)
  * [Retrieve the tracking statuses of an Order](#jump-Orders-RetrievethetrackingstatusesofanOrder)
  * [Update the manual tracking status of an Order](#jump-Orders-UpdatethemanualtrackingstatusofanOrder)
* [Webhooks](#Webhooks)
  * [Retrieve a list of Webhooks](#jump-Webhooks-RetrievealistofWebhooks)
  * [Create a new Webhook](#jump-Webhooks-CreateanewWebhook)
  * [Delete a Webhook](#jump-Webhooks-DeleteaWebhook)

### Fulfillments

Endpoint: Retrieve the tracking status of a Fulfillment

GET <https://www.theshoppad.com/apps/tracktor/api/admin/\\{{uuid\\}}/fulfillments/\\{{fulfillment\\_id\\}}.json\\>
(Reference: <https://www.theshoppad.com/apps/tracktor/api/docs#collapse-Fulfillments-RetrievethetrackingstatusofaFulfillment>)

**Description**

Response Attributes

| Attribute                      | Description                                                                                                                             |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| shop\_url (string)             | URL of the store where the order was placed                                                                                             |
| order\_id (integer)            | The Shopify ID of the order                                                                                                             |
| order\_name (string)           | The human-readable name of the order, typically prefixed by a #                                                                         |
| shopify\_carrier (string)      | The `tracking_company` on the Shopify fulfillment                                                                                       |
| carrier (object)               | Full details about the actual carrier used (either from shopify\_carrier or after Carrier Mapping). Attributes include slug, name, etc. |
| tracking\_number (string)      | The tracking number set on the Shopify fulfillment                                                                                      |
| fulfillment\_id (integer)      | The Shopify ID of the fulfillment                                                                                                       |
| fulfillment\_status (string)   | The status of an order in terms of the line items being fulfilled. Valid values: `fulfilled`, `null`, or `partial`.                     |
| shipment\_status (string)      | Options: `order_ready`, `in_transit`, `out_for_delivery`, `delivered`, or any custom statuses configured in Tracktor                    |
| exception\_status (string)     | Only set if this fulfillment has an issue. Options: `not_found`, `exception`, `undelivered`, `pending`, `expired`                       |
| is\_automatic (boolean)        | `true` by default. `false` if not getting automatic updates from the carrier                                                            |
| line\_items (array of objects) | One object per line item. Attributes: name, quantity, requires\_shipping, id, product\_id, variant\_id                                  |
| latest\_status (object)        | Advanced: details about the latest status update for this fulfillment                                                                   |
| status (array of objects)      | Advanced: details about all potential statuses for this fulfillment                                                                     |

**Headers**

| Key          | Value            |
| ------------ | ---------------- |
| Content-Type | application/json |
| x-api-key    | {{api\_key}}     |

**Response (Found fulfillment | Code: 200)**

```json
{
    "fulfillments": {
        "shop_url": "https://myshop.myshopify.com",
        "order_id": 2031829090338,
        "order_name": "#1078",
        "shopify_carrier": "China Post",
        "carrier": {
            "slug": "china-post",
            "name": "China Post",
            "required_fields": [],
            "website": "http://yjcx.ems.com.cn/qps/yjcx",
            "phone": "86 20 11185",
            "picture": "//s.trackingmore.com/images/icons/express/companylogo/3010.jpg"
        },
        "tracking_number": "UJ509851438CN",
        "fulfillment_id": 1910857990178,
        "fulfillment_status": "success",
        "shipment_status": "order_ready",
        "exception_status": "not_found",
        "is_automatic": true,
        "line_items": [
            {
                "name": "Poulet1",
                "quantity": 1,
                "requires_shipping": true,
                "id": 5046976512034,
                "product_id": 10692440015,
                "variant_id": 7214955855905
            }
        ],
        "convert_to_local": null,
        "latest_status": {
            "key": "order_ready",
            "label": "Order Ready",
            "message": "Order Ready",
            "datetime": "2020-03-18T14:30:55-04:00",
            "tracking_location": null,
            "location_string": null,
            "address_string": null,
            "is_custom": true,
            "convert_to_local": true
        },
        "status": {
            "ordered": {
                "latest": {
                    "message": "Ordered",
                    "datetime": "2020-03-18T14:29:55-04:00",
                    "tracking_location": null,
                    "location_string": null,
                    "address_string": null,
                    "is_custom": false,
                    "convert_to_local": true
                },
                "all": [
                    {
                        "message": "Ordered",
                        "datetime": "2020-03-18T14:29:55-04:00",
                        "tracking_location": null,
                        "location_string": null,
                        "address_string": null,
                        "is_custom": false,
                        "convert_to_local": true
                    }
                ],
                "label": "Ordered"
            },
            "custom0": {
                "latest": {
                    "message": "1",
                    "datetime": "2020-03-18T14:30:55-04:00",
                    "tracking_location": null,
                    "location_string": null,
                    "address_string": null,
                    "is_custom": true
                },
                "all": [
                    {
                        "message": "1",
                        "datetime": "2020-03-18T14:30:55-04:00",
                        "tracking_location": null,
                        "location_string": null,
                        "address_string": null,
                        "is_custom": true
                    }
                ],
                "label": "1"
            },
            "custom1": {
                "latest": {
                    "message": "2",
                    "datetime": "2020-03-18T14:30:55-04:00",
                    "tracking_location": null,
                    "location_string": null,
                    "address_string": null,
                    "is_custom": true
                },
                "all": [
                    {
                        "message": "2",
                        "datetime": "2020-03-18T14:30:55-04:00",
                        "tracking_location": null,
                        "location_string": null,
                        "address_string": null,
                        "is_custom": true
                    }
                ],
                "label": "2"
            },
            "custom2": {
                "latest": {
                    "message": "3",
                    "datetime": "2020-03-18T14:30:55-04:00",
                    "tracking_location": null,
                    "location_string": null,
                    "address_string": null,
                    "is_custom": true
                },
                "all": [
                    {
                        "message": "3",
                        "datetime": "2020-03-18T14:30:55-04:00",
                        "tracking_location": null,
                        "location_string": null,
                        "address_string": null,
                        "is_custom": true
                    }
                ],
                "label": "3"
            },
            "order_ready": {
                "latest": {
                    "message": "Order Ready",
                    "datetime": "2020-03-18T14:30:55-04:00",
                    "tracking_location": null,
                    "location_string": null,
                    "address_string": null,
                    "is_custom": true,
                    "convert_to_local": true
                },
                "all": [
                    {
                        "message": "Order Ready",
                        "datetime": "2020-03-18T14:30:55-04:00",
                        "tracking_location": null,
                        "location_string": null,
                        "address_string": null,
                        "is_custom": true,
                        "convert_to_local": true
                    }
                ],
                "label": "Order Ready",
                "static": true
            },
            "in_transit": {
                "latest": {
                    "message": "In Transit",
                    "datetime": null,
                    "tracking_location": null,
                    "location_string": null,
                    "address_string": null,
                    "is_custom": true
                },
                "all": [
                    {
                        "message": "In Transit",
                        "datetime": null,
                        "tracking_location": null,
                        "location_string": null,
                        "address_string": null,
                        "is_custom": true
                    }
                ],
                "label": "In Transit",
                "static": true
            },
            "out_for_delivery": {
                "latest": {
                    "message": "Out for Delivery",
                    "datetime": null,
                    "tracking_location": null,
                    "location_string": null,
                    "address_string": null,
                    "is_custom": true
                },
                "all": [
                    {
                        "message": "Out for Delivery",
                        "datetime": null,
                        "tracking_location": null,
                        "location_string": null,
                        "address_string": null,
                        "is_custom": true
                    }
                ],
                "label": "Out for Delivery",
                "static": true
            },
            "delivered": {
                "latest": {
                    "message": "Delivered",
                    "datetime": null,
                    "tracking_location": null,
                    "location_string": null,
                    "address_string": null,
                    "is_custom": true
                },
                "all": [
                    {
                        "message": "Delivered",
                        "datetime": null,
                        "tracking_location": null,
                        "location_string": null,
                        "address_string": null,
                        "is_custom": true
                    }
                ],
                "label": "Delivered",
                "static": true
            }
        }
    }
}
```

***

### Orders

#### Get the current package tracking status options for this shop

GET <https://www.theshoppad.com/apps/tracktor/api/admin/\\{{uuid\\}}/status-options.json\\>
(Reference: <https://www.theshoppad.com/apps/tracktor/api/docs#collapse-Orders-Getthecurrentpackagetrackingstatusoptionsforthisshop>)

**Headers**

| Key          | Value            |
| ------------ | ---------------- |
| Content-Type | application/json |
| x-api-key    | {{api\_key}}     |

**Response (Success | Code: 200)**

```json
[
    { "label": "Ordered", "value": "ordered" },
    { "label": "Order Ready", "value": "pre_transit" },
    { "label": "Painting", "value": "painting" },
    { "label": "Packaging", "value": "packaging" },
    { "label": "Fulfilling", "value": "fulfilling" },
    { "label": "In Transit", "value": "in_transit" },
    { "label": "Out For Delivery", "value": "out_for_delivery" },
    { "label": "Delivered", "value": "delivered" }
]
```

***

#### Retrieve the tracking statuses of an Order

GET <https://www.theshoppad.com/apps/tracktor/api/admin/\\{{uuid\\}}/orders/\\{{order\\_id\\}}.json\\>
(Reference: <https://www.theshoppad.com/apps/tracktor/api/docs#collapse-Orders-RetrievethetrackingstatusesofanOrder>)

**Description**

Response Attributes

| Attribute                                                         | Description                                                                                                      |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| order\_id (integer)                                               | The Shopify ID of the order                                                                                      |
| order\_name (string)                                              | The human-readable name of the order                                                                             |
| order\_email (string)                                             | Customer email (empty if only phone provided)                                                                    |
| order\_phone (string)                                             | Phone number from the order                                                                                      |
| order\_source\_name (string)                                      | How the order was placed (e.g., `web`, `pos`, `shopify_draft_order`, `iphone`, `android`)                        |
| order\_created\_at (string)                                       | Date order was placed                                                                                            |
| customer\_first\_name, customer\_last\_name, customer\_full\_name | Customer name data                                                                                               |
| total\_price (float)                                              | Total price including taxes and shipping                                                                         |
| line\_item\_count (integer)                                       | Total number of line items                                                                                       |
| statuses (array of strings)                                       | One item per fulfillment (e.g., `order_ready`, `in_transit`, `out_for_delivery`, `delivered`, or custom)         |
| exception\_statuses (array of strings)                            | One item per fulfillment with an exception (e.g., `not_found`, `exception`, `undelivered`, `pending`, `expired`) |
| days\_since\_ordered (integer)                                    | If delivered: days from Ordered to Delivered                                                                     |
| automatic\_carrier\_updates (boolean)                             | `true` by default; `false` if automatic updates are off                                                          |
| fulfillments (array of objects)                                   | See fulfillment response above                                                                                   |

**Headers**

| Key          | Value            |
| ------------ | ---------------- |
| Content-Type | application/json |
| x-api-key    | {{api\_key}}     |

**Response (Found order | Code: 200)**

```json
{
    "order": {
        "order_id": 5217028303,
        "order_name": "#1002",
        "order_email": "example@gmail.com",
        "order_phone": null,
        "order_source_name": "shopify_draft_order",
        "order_created_at": "2017-04-24T18:57:32+00:00",
        "customer_first_name": "Frank",
        "customer_last_name": "Franz",
        "customer_full_name": "Frank Franz",
        "total_price": 49.16,
        "line_item_count": 3,
        "statuses": ["in_transit"],
        "exception_statuses": ["pending"],
        "days_since_ordered": 5,
        "automatic_carrier_updates": true,
        "created_at": "2020-03-11T17:09:57+00:00",
        "updated_at": "2020-03-26T04:42:42+00:00",
        "fulfillments": [
            {
                "shop_url": "https://myshop.myshopify.com",
                "order_id": 5217028303,
                "order_name": "#1002",
                "shopify_carrier": "FedEx",
                "carrier": null,
                "tracking_number": null,
                "fulfillment_id": 1904539992098,
                "fulfillment_status": "success",
                "shipment_status": "order_ready",
                "exception_status": "not_found",
                "is_automatic": true,
                "line_items": [
                    {
                        "name": "Poulet",
                        "quantity": 1,
                        "requires_shipping": true,
                        "id": 10122897615,
                        "product_id": 10692440015,
                        "variant_id": 39699225807
                    }
                ],
                "convert_to_local": null,
                "error": "",
                "latest_status": {
                    "key": "order_ready",
                    "label": "Order Ready",
                    "message": "Order Ready",
                    "datetime": "2020-03-11T13:12:16-04:00",
                    "tracking_location": null,
                    "location_string": null,
                    "address_string": null,
                    "is_custom": true,
                    "convert_to_local": true
                },
                "status": {
                    "ordered": {
                        "latest": {
                            "message": "Ordered",
                            "datetime": "2017-04-24T14:57:32-04:00",
                            "tracking_location": null,
                            "location_string": null,
                            "address_string": null,
                            "is_custom": false,
                            "convert_to_local": true
                        },
                        "all": [
                            {
                                "message": "Ordered",
                                "datetime": "2017-04-24T14:57:32-04:00",
                                "tracking_location": null,
                                "location_string": null,
                                "address_string": null,
                                "is_custom": false,
                                "convert_to_local": true
                            }
                        ],
                        "label": "Ordered"
                    },
                    "custom0": {
                        "latest": {
                            "message": "1",
                            "datetime": "2014-02-16T15:45:23+00:00",
                            "tracking_location": null,
                            "location_string": null,
                            "address_string": null,
                            "is_custom": true
                        },
                        "all": [
                            {
                                "message": "1",
                                "datetime": "2014-02-16T15:45:23+00:00",
                                "tracking_location": null,
                                "location_string": null,
                                "address_string": null,
                                "is_custom": true
                            }
                        ],
                        "label": "1"
                    },
                    "custom1": {
                        "latest": {
                            "message": "2",
                            "datetime": "2020-03-11T13:12:16-04:00",
                            "tracking_location": null,
                            "location_string": null,
                            "address_string": null,
                            "is_custom": true
                        },
                        "all": [
                            {
                                "message": "2",
                                "datetime": "2020-03-11T13:12:16-04:00",
                                "tracking_location": null,
                                "location_string": null,
                                "address_string": null,
                                "is_custom": true
                            }
                        ],
                        "label": "2"
                    },
                    "custom2": {
                        "latest": {
                            "message": "3",
                            "datetime": "2020-03-11T13:12:16-04:00",
                            "tracking_location": null,
                            "location_string": null,
                            "address_string": null,
                            "is_custom": true
                        },
                        "all": [
                            {
                                "message": "3",
                                "datetime": "2020-03-11T13:12:16-04:00",
                                "tracking_location": null,
                                "location_string": null,
                                "address_string": null,
                                "is_custom": true
                            }
                        ],
                        "label": "3"
                    },
                    "order_ready": {
                        "latest": {
                            "message": "Order Ready",
                            "datetime": "2020-03-11T13:12:16-04:00",
                            "tracking_location": null,
                            "location_string": null,
                            "address_string": null,
                            "is_custom": true,
                            "convert_to_local": true
                        },
                        "all": [
                            {
                                "message": "Order Ready",
                                "datetime": "2020-03-11T13:12:16-04:00",
                                "tracking_location": null,
                                "location_string": null,
                                "address_string": null,
                                "is_custom": true,
                                "convert_to_local": true
                            }
                        ],
                        "label": "Order Ready",
                        "static": true
                    },
                    "in_transit": {
                        "latest": {
                            "message": "In Transit",
                            "datetime": null,
                            "tracking_location": null,
                            "location_string": null,
                            "address_string": null,
                            "is_custom": true
                        },
                        "all": [
                            {
                                "message": "In Transit",
                                "datetime": null,
                                "tracking_location": null,
                                "location_string": null,
                                "address_string": null,
                                "is_custom": true
                            }
                        ],
                        "label": "In Transit",
                        "static": true
                    },
                    "out_for_delivery": {
                        "latest": {
                            "message": "Out for Delivery",
                            "datetime": null,
                            "tracking_location": null,
                            "location_string": null,
                            "address_string": null,
                            "is_custom": true
                        },
                        "all": [
                            {
                                "message": "Out for Delivery",
                                "datetime": null,
                                "tracking_location": null,
                                "location_string": null,
                                "address_string": null,
                                "is_custom": true
                            }
                        ],
                        "label": "Out for Delivery",
                        "static": true
                    },
                    "delivered": {
                        "latest": {
                            "message": "Delivered",
                            "datetime": null,
                            "tracking_location": null,
                            "location_string": null,
                            "address_string": null,
                            "is_custom": true
                        },
                        "all": [
                            {
                                "message": "Delivered",
                                "datetime": null,
                                "tracking_location": null,
                                "location_string": null,
                                "address_string": null,
                                "is_custom": true
                            }
                        ],
                        "label": "Delivered",
                        "static": true
                    }
                }
            }
        ]
    }
}
```

***

#### Update the manual tracking status of an Order

POST <https://www.theshoppad.com/apps/tracktor/api/admin/\\{{uuid\\}}/orders/\\{{order\\_id\\}}.json\\>
(Reference: <https://www.theshoppad.com/apps/tracktor/api/docs#collapse-Orders-UpdatethemanualtrackingstatusofanOrder>)

**Headers**

| Key          | Value            |
| ------------ | ---------------- |
| Content-Type | application/json |
| x-api-key    | {{api\_key}}     |

**Body**

```json
{
    "order": {
        "status": "in_transit",
        "date": "2014-02-16T10:45:23-05:00",
        "automatic_carrier_updates": false,
        "force": true
    }
}
```

**Response (Order status updated | Code: 200)**

```json
{
    "order": {
        "uuid": "poulet-sauvage",
        "active": true,
        "order_id": 5217028303,
        "order_name": "#1002",
        "order_email": "email@gmail.com",
        "order_phone": null,
        "order_source_name": "shopify_draft_order",
        "order_created_at": "2017-04-24T18:57:32+00:00",
        "customer_first_name": "John",
        "customer_last_name": "Smith",
        "customer_full_name": "John Smith",
        "total_price": 49.16,
        "line_item_count": 3,
        "statuses": [
            { "in_transit": "In Transit" }
        ],
        "exception_statuses": ["pending"],
        "trackings": [
            {
                "fulfillment_id": 1904539992098,
                "shopify_carrier": "FedEx",
                "provider": "shippo",
                "tracking_company": "fedex",
                "tracking_number": "61297937879321429293",
                "fulfillment_status": "success",
                "line_item_count": 1,
                "shipment_status": "in_transit",
                "exception_status": null,
                "last_updated_source": "webhook",
                "update_history": [
                    { "source": "webhook", "datetime": "2020-03-23T13:13:28-07:00", "status_counts": { "in_transit": 9, "delivered": 1 } }
                ],
                "days_since_ordered": 1051,
                "force_update": false,
                "data": {
                    "trackingParams": [],
                    "id": null,
                    "tracking_code": "61297937879321429293",
                    "status": "in_transit",
                    "created_at": "2019-01-30T18:24:00Z",
                    "updated_at": "2019-02-05T12:51:00Z",
                    "signed_by": "",
                    "est_delivery_date": "2019-02-05T00:00:00Z",
                    "carrier": "fedex",
                    "hide_carrier": false,
                    "tracking_details": [
                        {
                            "message": "Your shipment has been processed through a USPS facility.",
                            "status": "in_transit",
                            "datetime": "2019-01-31T02:24:00Z",
                            "tracking_location": {
                                "city": "Seoul International Post Office",
                                "state": "",
                                "country": "",
                                "zip": "",
                                "location": null
                            }
                        }
                    ],
                    "convert_to_local": true,
                    "exception_status": null
                },
                "data_hash": "53228df6af01d1b98f189f3c39cde553",
                "_id": null,
                "created_at": "2020-03-11T17:12:19+00:00",
                "updated_at": "2020-03-24T16:46:59+00:00"
            }
        ],
        "custom_statuses": [
            { "id": "pre_transit", "completed": true, "date": "2014-02-16T15:45:23+00:00" },
            { "id": "in_transit", "completed": true, "date": "2014-02-16T15:45:23+00:00" }
        ],
        "custom_is_automatic": false,
        "days_since_ordered": 1086,
        "_id": "5e691b6578e81e60633ce792",
        "created_at": "2020-03-11T17:09:57+00:00",
        "updated_at": "2020-03-27T22:18:13+00:00"
    }
}
```

***

### Webhooks

#### Retrieve a list of Webhooks

GET <https://www.theshoppad.com/apps/tracktor/api/admin/\\{{uuid\\}}/webhooks.json\\>
(Reference: <https://www.theshoppad.com/apps/tracktor/api/docs#collapse-Webhooks-RetrievealistofWebhooks>)

**Headers**

| Key          | Value            |
| ------------ | ---------------- |
| Content-Type | application/json |
| x-api-key    | {{api\_key}}     |

**Response (Success | Code: 200)**

```json
{
    "webhooks": [
        {
            "topic": "order/all",
            "address": "https://whatever.hostname.com/",
            "format": "json",
            "source": "mesa",
            "id": "5e964b4d32904d596c010ca2"
        },
        {
            "topic": "order/all",
            "address": "https://whatever.hostname.com/another",
            "format": "json",
            "source": "mesa",
            "id": "5e964bb776a93d3baf7b4a33"
        }
    ]
}
```

***

#### Create a new Webhook

POST <https://www.theshoppad.com/apps/tracktor/api/admin/\\{{uuid\\}}/webhooks.json\\>
(Reference: <https://www.theshoppad.com/apps/tracktor/api/docs#collapse-Webhooks-CreateanewWebhook>)

Valid topics:

* order/all
* order/pre\_transit
* order/in\_transit
* order/out\_for\_delivery
* order/delivered
* fulfillment/all
* fulfillment/pre\_transit
* fulfillment/in\_transit
* fulfillment/out\_for\_delivery
* fulfillment/delivered

**Headers**

| Key          | Value            |
| ------------ | ---------------- |
| Content-Type | application/json |
| x-api-key    | {{api\_key}}     |

**Body**

```json
{
    "webhook": {
        "topic": "order/all",
        "address": "https://whatever.hostname.com/another",
        "format": "json",
        "source": "mesa"
    }
}
```

**Response (Successfully created webhook | Code: 200)**

```json
{
    "webhook": {
        "topic": "order/all",
        "address": "https://whatever.hostname.com/",
        "format": "json",
        "source": "mesa",
        "id": "5e964b4d32904d596c010ca2"
    }
}
```

***

#### Delete a Webhook

DELETE <https://www.theshoppad.com/apps/tracktor/api/admin/\\{{uuid\\}}/webhooks/\\{{webhook\\_id\\}}.json\\>
(Reference: <https://www.theshoppad.com/apps/tracktor/api/docs#collapse-Webhooks-DeleteaWebhook>)

**Headers**

| Key          | Value            |
| ------------ | ---------------- |
| Content-Type | application/json |
| x-api-key    | {{api\_key}}     |

**Response (Webhook successfully deleted | Code: 200)**

```json
{
    "webhook": {
        "topic": "order/all",
        "address": "https://whatever.hostname.com/",
        "format": "json",
        "source": "mesa",
        "id": "5e964b4d32904d596c010ca2"
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://shoppad.gitbook.io/tracktor/developer-tools/tracktor-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.